---
title: "Getting started with forestmap"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with forestmap}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 5.25,
  out.width = "100%",
  dpi = 150,
  dev = if (requireNamespace("ragg", quietly = TRUE)) "ragg_png" else "png"
)
```

```{r setup}
library(forestmap)
```

## What forestmap draws

A forest plot shows each study in a meta-analysis with its effect size and
confidence interval. forestmap sorts the studies from the smallest to the
largest effect and adds a heatmap underneath showing each study's
properties: its population, design, country, or anything else you've coded.
Reading down a column tells you about one study; reading across a row tells
you where studies with that property fall among the effects.

## 1. Prepare your data

You need a data frame with **one row per study** and these columns:

| Column | What it holds |
|---|---|
| Effect size | The study's effect, e.g. a standardised mean difference. |
| Sampling variance | The variance of that effect, e.g. `vi` from `metafor::escalc()`. |
| One column per study property | A factor giving the study's level, e.g. `"RCT"`. `NA` means the study doesn't report it. |

The package comes with made-up data from 60 studies:

```{r}
head(forestmap_example)
```

The order of a factor's levels sets the order of the rows in the heatmap,
so use `factor(x, levels = ...)` to change it.

If you've computed effect sizes with
[metafor](https://www.metafor-project.org)'s `escalc()`, your data already
has the effect (`yi`) and sampling variance (`vi`): pass them as
`es = "yi", vi = "vi"`.

Instead of variances you can give **standard errors** (`se = "..."`), or the
**lower and upper bounds** of each 95% confidence interval
(`lb = "...", ub = "..."`). Use the bounds when the interval isn't
symmetric, such as odds ratios on their original scale. From variances or
standard errors, the interval is the effect ± 1.96 standard errors.

## 2. Make the plot

Tell `plot_forestmap()` which column is which. Naming the study properties
sets the headings in the plot:

```{r}
plot_forestmap(
  forestmap_example,
  es = "smd",
  vi = "vi",
  moderators = c(
    "Population" = "population",
    "Outcome measure" = "outcome",
    "Study design" = "design",
    "Country" = "country"
  )
)
```

## 3. Read the plot

* Each column is one study. The top panel shows its effect and 95%
  confidence interval; the tiles below show its properties.
* **Blue** studies have a confidence interval entirely above zero, **red**
  ones entirely below, and **grey** ones include zero. Each study's tiles
  take the same colour.
* A row with its tiles bunched at one end means studies with that property
  tend to find smaller (left) or larger (right) effects. Here, every
  negative effect comes from an RCT, and the largest effects come mostly
  from quasi-experimental studies using self-report measures.

## 4. Save it

`plot_forestmap()` returns the plot; saving it is up to you. Choose the size
when you save:

```{r, eval = FALSE}
p <- plot_forestmap(
  forestmap_example, "smd", vi = "vi",
  moderators = c("Population" = "population", "Study design" = "design")
)

ggplot2::ggsave("forestmap.png", p, width = 7, height = 5.25, dpi = 300)
ggplot2::ggsave("forestmap.svg", p, width = 7, height = 5.25)
ggplot2::ggsave("forestmap.pdf", p, width = 7, height = 5.25, device = cairo_pdf)
```

With many study properties, make the plot taller (e.g. `height = 10`).

The default font, Roboto Condensed, comes with forestmap, and PNG and SVG
files saved with `ggsave()` always use it. Two places only see fonts
installed on your computer, and show another font until you install Roboto
Condensed (the font files are in the folder given by
`system.file("fonts", package = "forestmap")`):

* **RStudio's Plots pane.** Alternatively, set *Tools > Global Options >
  General > Graphics > Backend* to **AGG**.
* **PDF files**, saved with `device = cairo_pdf` as above.

## Next steps

[Customising the plot](https://shaheedazaad.github.io/forestmap/articles/customising.html) shows how to change the
headings, colours, font, sizes and layout, with an example of each.