---
title: "Get Started with ggforestplotR"
output:
  rmarkdown::html_vignette:
    highlight: pygments
vignette: >
  %\VignetteIndexEntry{Get Started with ggforestplotR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 8,
  fig.height = 5
)
```

```{r setup}
library(ggforestplotR)
library(ggplot2)
```

`ggforestplotR` is built for coefficient-driven forest plots that stay inside a
normal `ggplot2` workflow.

## Choose a workflow

Use the package in one of three ways:

1. Start from a coefficient table and map the required columns directly.
2. Start from a fitted model and let `tidy_forest_model()` or `ggforestplot()` call `broom::tidy()`.
3. Add `add_forest_table()` or `add_split_table()` after styling the main plot.

This article covers the basic entry points and the minimum data you need.

## Start from a coefficient table

The simplest input is a data frame with a term, estimate, and confidence limits. If your columns use different names, map them explicitly.

```{r basic-plot}
basic_coefs <- data.frame(
  term = c("Age", "BMI", "Treatment"),
  estimate = c(0.10, -0.08, 0.34),
  conf.low = c(0.02, -0.16, 0.12),
  conf.high = c(0.18, 0.00, 0.56)
)

ggforestplot(basic_coefs)
```

## Add grouped sections and row striping

Use `grouping` when you want related variables separated into labeled panels.
Add `striped_rows = TRUE` to color alternating rows in the plot.

```{r grouped-striped}
sectioned_coefs <- data.frame(
  term = c("Age", "BMI", "Smoking", "Stage II", "Stage III", "Nodes"),
  estimate = c(0.10, -0.08, 0.20, 0.34, 0.52, 0.28),
  conf.low = c(0.02, -0.16, 0.05, 0.12, 0.20, 0.06),
  conf.high = c(0.18, 0.00, 0.35, 0.56, 0.84, 0.50),
  section = c("Clinical", "Clinical", "Clinical", "Tumor", "Tumor", "Tumor")
)

ggforestplot(
  sectioned_coefs,
  grouping = "section",
  striped_rows = TRUE,
  stripe_fill = "grey94"
)
```

## Add a summary table

Use `add_forest_table()` to add a summary table to your forest plot.

```{r side-table}
tabled_coefs <- data.frame(
  term = c("Age", "BMI", "Smoking", "Stage II", "Stage III"),
  estimate = c(0.12, -0.10, 0.18, 0.30, 0.46),
  conf.low = c(0.03, -0.18, 0.04, 0.10, 0.18),
  conf.high = c(0.21, -0.02, 0.32, 0.50, 0.74),
  sample_size = c(120, 115, 98, 87, 83)
)

ggforestplot(tabled_coefs, n = "sample_size", striped_rows = TRUE) +
  add_forest_table(
    position = "left",
    show_n = TRUE,
    estimate_label = "Beta"
  )
```

## Add split summary tables

Use `add_split_table()` to create a more traditional looking forest plot, with summary data on either side of the plot.

```{r split-table}
ggforestplot(tabled_coefs, n = "sample_size", striped_rows = T) +
  add_split_table(
    left_columns = c("term", "n"),
    right_columns = c("estimate")
  )
```

## Start from a fitted model

If `broom` is installed, `ggforestplot()` can work directly from a fitted model.

```{r model-plot}
fit <- lm(mpg ~ wt + hp + qsec, data = mtcars)

ggforestplot(fit, sort_terms = "descending")
```

## Next articles

For more detail, see:

- `ggforestplotR-plot-customization` for enhanced customization of the plots and summary tables.
- `ggforestplotR-data-helpers` for `as_forest_data()` and `tidy_forest_model()`.