Package 'forestmap'

Example meta-analysis data

Description

Made-up studies from a meta-analysis of an intervention: each study's standardised mean difference and sampling variance (the yi/vi pair that metafor::escalc() produces), its sample size, and four study properties. Some studies don't report their outcome measure or country (NA). Use it to try out plot_forestmap().

Usage

forestmap_example

Format

A data frame with 60 rows (studies) and 8 columns:

study

Study label (first author and year).

smd

Standardised mean difference (Hedges' g).

vi

Sampling variance of smd.

n

Total sample size.

population

Factor: Adults, Children or Clinical.

outcome

Factor: Self-report or Behavioural; NA = not reported.

design

Factor: RCT or Quasi-experimental.

country

Factor: USA, UK, Australia, Germany or Canada; NA = not reported.

Source

Simulated; see data-raw/forestmap_example.R in the package source.

---

Colour palettes for forestmap plots

Description

Ready-made palettes that can be passed by name to the palette argument of plot_forestmap(). Each palette has three colours:

Usage

forestmap_palettes

Format

A named list of named character vectors (hex colours):

default

Blue / red / grey.

okabe_ito

Blue and vermillion from the Okabe-Ito palette (Okabe & Ito, 2008), designed to stay distinguishable with common colour-vision deficiencies; light grey for null.

viridis

Teal / purple / grey.

greyscale

Black / dark grey / light grey, for print.

Details

• positive: the 95% CI lies entirely above the null value.

• negative: the 95% CI lies entirely below the null value.

• null: the 95% CI includes the null value.

Examples

names(forestmap_palettes)
forestmap_palettes$okabe_ito

---

Forest plot of studies with a heatmap of study properties

Description

Plots each study's effect size and 95% confidence interval, sorted from smallest to largest, above a heatmap showing each study's properties (population, design, country, ...). It shows at a glance whether studies with particular properties tend to find larger or smaller effects.

Usage

plot_forestmap(
  data,
  es,
  lb = NULL,
  ub = NULL,
  moderators,
  vi = NULL,
  se = NULL,
  font = "Roboto Condensed",
  palette = "default",
  text_size = 9,
  forest_height = "auto",
  null_value = 0,
  rope = NULL,
  y_limits = NULL,
  y_label = "Effect size",
  x_label = "Effect",
  max_levels = NULL,
  layout = c("standard", "compact")
)

Arguments

data	A data frame with one row per study.
es	Name of the column holding each study's effect size.
lb, ub	Names of the columns holding the lower and upper bounds of each study's 95% confidence interval. Give these, or vi, or se.
moderators	Names of the columns holding study properties (factors). Name the vector to set each moderator's heading, e.g. c("Study design" = "design", "Population" = "population"); unnamed entries use the column name.
vi	Name of a column holding each study's sampling variance (e.g. vi from metafor::escalc()). The 95% confidence interval is computed as es ± 1.96 × √vi. Use instead of lb and ub.
se	Name of a column holding each study's standard error. The 95% confidence interval is computed as es ± 1.96 × se. Use instead of lb and ub.
font	A font family installed on your computer (e.g. "Helvetica"), or the path to a .ttf/.otf font file. The default, "Roboto Condensed", comes with the package, so it works on every computer.
palette	A palette name from forestmap_palettes ("default", "okabe_ito", "viridis", "greyscale") or three colours, e.g. c(positive = "darkgreen", negative = "purple", null = "grey").
text_size	Base text size in points.
forest_height	Share of the plot's height given to the forest plot (the top panel), between 0 and 1 (0.5 gives the forest plot and heatmap equal height). "auto" (the default) gives the heatmap more room the more rows it has.
null_value	The value meaning "no effect": 0 for differences and log ratios, 1 for raw ratios such as odds ratios.
rope	Optional region of practical equivalence, drawn as a shaded band: two numbers such as c(-0.1, 0.1), or one number for a band symmetric around null_value.
y_limits	Optional y-axis limits, e.g. c(-1, 1). By default the axis is symmetric around null_value and shows every confidence interval in full; for ratios (null_value above 0 and every value positive) it starts at 0.
y_label, x_label	Axis titles.
max_levels	Optional maximum number of rows per moderator. With max_levels = 3, the 2 most common levels are shown and the rest are merged into one "Other" row. If levels tie for the last place, all of them are kept (with a warning). NULL (the default) shows every level.
layout	"standard" puts a bold heading above each moderator's rows; "compact" puts the moderator name to the left of its rows instead, which makes the heatmap shorter.

Details

Each row of data is one study. Effects are coloured by their confidence interval: positive when it lies entirely above null_value, negative when entirely below, and null otherwise. Each study's heatmap tiles take the same colour.

Value

A patchwork object. Print it to display it, or save it with ggplot2::ggsave().

Moderators

Each moderator (study property) gets its own block in the heatmap with one row per factor level, in the order of the factor's levels. Use factor() with ⁠levels =⁠ to control the order. A missing value (NA) means the study doesn't report that property, so it gets no filled tile in that block. Character columns are converted to factors (with a message).

Size and saving

The plot has no fixed physical size; choose the width and height when you save it, e.g. ggplot2::ggsave("plot.png", p, width = 7, height = 5.25). forest_height and text_size control proportions and text.

PNG and SVG files saved with ggplot2::ggsave() always use the chosen font. Some other graphics devices only see fonts installed on your computer, and show the bundled Roboto Condensed in another font until you install it (the files are in system.file("fonts", package = "forestmap")):

• RStudio's Plots pane: or set Tools > Global Options > General > Graphics > Backend to AGG.

• PDF: save with device = cairo_pdf.

Examples

p <- plot_forestmap(
  forestmap_example,
  es = "smd", vi = "vi",
  moderators = c(
    "Population" = "population",
    "Outcome measure" = "outcome",
    "Study design" = "design",
    "Country" = "country"
  ),
  rope = c(-0.1, 0.1),
  y_label = "SMD (95% CI)"
)
p

# With confidence interval bounds instead of variances
dat <- forestmap_example
dat$ci_lower <- dat$smd - 1.96 * sqrt(dat$vi)
dat$ci_upper <- dat$smd + 1.96 * sqrt(dat$vi)
plot_forestmap(
  dat, es = "smd", lb = "ci_lower", ub = "ci_upper",
  moderators = c("Population" = "population", "Study design" = "design")
)

# Compact layout, Okabe-Ito palette
plot_forestmap(
  forestmap_example, "smd", vi = "vi",
  moderators = c("Population" = "population", "Study design" = "design"),
  palette = "okabe_ito",
  layout = "compact"
)

## Not run: 
ggplot2::ggsave("forestmap.png", p, width = 7, height = 5.25, dpi = 300)

## End(Not run)

---