Package 'contourforest'

BCG Vaccine Trials Dataset

Description

This dataset contains summary data from 13 BCG vaccine studies, including the number of events in treatment and control groups, total sample sizes, and subgroup classification.

Usage

bcg()

Value

A data frame with 13 rows and 6 variables:

Study

Character. Name and year of the study.

events_t

Numeric. Number of events (e.g., TB cases) in the treatment (BCG) group.

n_t

Numeric. Total number of participants in the treatment group.

events_c

Numeric. Number of events in the control group.

n_c

Numeric. Total number of participants in the control group.

subgroup

Character. Type of study or subgroup classification ("random", "alternate", or "systematic").

---

Hypothetical dataset: GAD-7 Anxiety Scores by Socioeconomic Status

Description

GAD-7 scores (mean ± SD) for high SES (control) vs low SES (treatment) groups across 6 studies.

Usage

dat1

Format

A data frame with 6 rows and 8 variables:

Study

Study name or year

mean_c

Mean GAD-7 score in high SES (control) group

sd_c

Standard deviation of GAD-7 scores in high SES (control) group

n_c

Sample size in high SES (control) group

mean_t

Mean GAD-7 score in low SES (treatment) group

sd_t

Standard deviation of GAD-7 scores in low SES (treatment) group

n_t

Sample size in low SES (treatment) group

subgroup

Geographical subgroup of the study (e.g., Asia, Europe)

Source

Hypothetical data

---

Contour-Enhanced Binary Outcome Forest Plot

Description

Generates a contour-enhanced forest plot for binary outcome data (e.g., odds ratios, risk ratios), with study-level effects, confidence intervals, pooled effect, prediction interval, and heterogeneity statistics.

Usage

forest_bin(
  dat,
  measure = "OR",
  method = "REML",
  xlab = "",
  title = NULL,
  model = "Random-effects",
  estimator = "REML",
  nc_col = "n_c",
  ne_col = "n_t",
  event_c_col = "events_c",
  event_t_col = "events_t",
  diamond.col = "red",
  study.col = "blue",
  CI.col = "blue",
  Pred.Inter.col = "black",
  square.size = 10,
  contour_fill = c("gray95", "gray80", "gray60", "gray40"),
  text_size = 3.5,
  xlim = c(-1.7, 3.5),
  pred = TRUE,
  xpos = list(EventsT = -0.9, EventsC = -0.3, Effect = 2.6, Weight = 3.1),
  study_x = -1.8,
  hetero_x = -1.7,
  tlim = c(0, 2.3),
  truncate_PI = FALSE,
  contour_left_min = c(0, 0.5, 0.67, 0.83),
  contour_left_max = c(0.5, 0.67, 0.83, 1),
  contour_right_min = c(1, 1.2, 1.5, 2),
  contour_right_max = c(1.2, 1.5, 2, 2.5)
)

Arguments

dat	Data frame containing study-level binary outcome data.
measure	Character. Effect measure ("OR" for odds ratio, "RR" for risk ratio, etc.).
method	Character. Method for meta-analysis heterogeneity estimation (default "REML").
xlab	Character. Label for the x-axis.
title	Character. Plot title. If NULL, a default title is generated.
model	Character. Meta-analysis model ("Random-effects" or "Fixed-effects").
estimator	Character. Estimator used in the meta-analysis (default "REML").
nc_col	Character. Column name for control group sample sizes.
ne_col	Character. Column name for treatment group sample sizes.
event_c_col	Character. Column name for number of events in control group.
event_t_col	Character. Column name for number of events in treatment group.
diamond.col	Color of the pooled effect polygon.
study.col	Color of the study-level effect points.
CI.col	Color of the study-level confidence interval lines.
Pred.Inter.col	Color of the prediction interval line.
square.size	Numeric. Maximum size of study-level effect squares.
contour_fill	Vector of colors for contour shading levels.
text_size	Numeric. Base size of plot text.
xlim	Numeric vector of length 2. Limits of the x-axis.
pred	Logical. Whether to show the prediction interval.
xpos	List of numeric positions for text labels (EventsT, EventsC, Effect, Weight).
study_x	Numeric. X-position for study names.
hetero_x	Numeric. X-position for heterogeneity text.
tlim	Numeric vector of length 2. Limits for truncating study confidence intervals.
truncate_PI	Logical. Whether to truncate the prediction interval to tlim.
contour_left_min	Numeric vector. Minimum x-values for left-side contour shading.
contour_left_max	Numeric vector. Maximum x-values for left-side contour shading.
contour_right_min	Numeric vector. Minimum x-values for right-side contour shading.
contour_right_max	Numeric vector. Maximum x-values for right-side contour shading.

Value

A ggplot2 object of the forest plot.

Examples

forest_bin(
  dat = bcg(),
  measure = "OR",
  xlab = "Odds Ratio",
  title = "BCG Vaccine Meta-analysis",
  tlim = c(0, 2.3),
  contour_left_min = c(0,0.3,0.5,0.7),
  contour_left_max = c(0.3,0.5,0.7,1),
  contour_right_min = c(1,1.2,1.5,1.8),
  contour_right_max = c(1.2,1.5,1.8,2.5)
)

---

Subgroup Forest Plot for Binary Outcome Meta-analysis

Description

Generates a contour-enhanced forest plot for binary outcome data, with optional subgroup analysis. This function calculates risk ratios (or other measures) and displays study-specific effect sizes, pooled subgroup effects, overall pooled effect, and heterogeneity statistics (I^2, tau^2).

Usage

forest_bin_subgroup(
  dat,
  subgroup = NULL,
  measure = "RR",
  method = "REML",
  nc_col = "n_c",
  ne_col = "n_t",
  event_c_col = "events_c",
  event_t_col = "events_t",
  xlab = "Risk Ratio (RR)",
  title = "Subgroup Forest Plot",
  diamond.col = "red",
  overall.col = "darkgreen",
  study.col = "blue",
  CI.col = "blue",
  Pred.Inter.col = "black",
  square.size = 8,
  Pred.Int.size = 2,
  xlim = c(-2, 3.5),
  tlim = c(0, 2.3),
  text_size = 3.5,
  xpos = list(EventsT = -1, EventsC = -0.4, Effect = 2.5, Weight = 3.2),
  study_x = -1.8,
  val_x = 2.6,
  contour_left_min = c(0, 0.5, 0.67, 0.83),
  contour_left_max = c(0.5, 0.67, 0.83, 1),
  contour_right_min = c(1, 1.2, 1.5, 2),
  contour_right_max = c(1.2, 1.5, 2, 2.5),
  pred = TRUE
)

Arguments

dat	A data frame containing study-level data. Must include columns for treatment and control events and sample sizes, and optionally a subgroup column.
subgroup	Column name in dat specifying subgroup membership (character or factor). Defaults to NULL (no subgroups).
measure	Effect measure to use. Default is "RR" (risk ratio).
method	Method for random-effects meta-analysis. Default is "REML".
nc_col	Character. Column name for control group sample sizes.
ne_col	Character. Column name for treatment group sample sizes.
event_c_col	Character. Column name for number of events in control group.
event_t_col	Character. Column name for number of events in treatment group.
xlab	Label for the x-axis. Default is "Risk Ratio (RR)".
title	Plot title. Default is "Subgroup Forest Plot".
diamond.col	Color for subgroup pooled effect diamonds. Default is "red".
overall.col	Color for overall pooled effect diamond. Default is "darkgreen".
study.col	Color for individual study points. Default is "blue".
CI.col	Color for study confidence interval bars. Default is "blue".
Pred.Inter.col	Color for prediction interval bars. Default is "black".
square.size	Maximum size of study points. Default is 8.
Pred.Int.size	Thickness of prediction interval line. Default is 2.
xlim	Numeric vector of length 2 giving x-axis limits. Default is c(-2, 3.5).
tlim	Numeric vector of length 2 for truncating study CIs. Default is c(0, 2.3).
text_size	Base text size for labels. Default is 3.5.
xpos	List of x-axis positions for EventsT, EventsC, Effect, and Weight labels. Default is list(EventsT=-1, EventsC=-0.4, Effect=2.5, Weight=3.2).
study_x	X position for study names. Default is -1.8.
val_x	X position for pooled effect labels. Default is 2.6.
contour_left_min	Numeric vector defining left contour minimum values. Default is c(0, 0.5, 0.67, 0.83).
contour_left_max	Numeric vector defining left contour maximum values. Default is c(0.5, 0.67, 0.83, 1).
contour_right_min	Numeric vector defining right contour minimum values. Default is c(1, 1.2, 1.5, 2).
contour_right_max	Numeric vector defining right contour maximum values. Default is c(1.2, 1.5, 2, 2.5).
pred	Logical indicating whether to show the prediction interval. Default is TRUE.

Value

A ggplot object representing the contour-enhanced subgroup forest plot.

Examples

# Load example dataset
data <- bcg()

# Generate subgroup forest plot
forest_bin_subgroup(
  dat = bcg(),
  tlim = c(0, 2.3),
  contour_left_min  = c(0, 0.3, 0.5, 0.7),
  contour_left_max  = c(0.3, 0.5, 0.7, 1),
  contour_right_min = c(1, 1.2, 1.5, 1.8),
  contour_right_max = c(1.2, 1.5, 1.8, 2.4)
)

---

Contour-enhanced Forest Plot for Continuous Outcomes

Description

Creates a forest plot for continuous outcomes (MD or SMD) with optional contour shading, prediction interval, and annotated study-level means, effect sizes, and weights.

Usage

forest_cont(
  dat,
  measure = "SMD",
  method = "REML",
  sort = c("effect", "none"),
  xlab = "",
  title = NULL,
  model = "Random-effects",
  estimator = "REML",
  m_c_col = "mean_c",
  sd_c_col = "sd_c",
  n_c_col = "n_c",
  m_t_col = "mean_t",
  sd_t_col = "sd_t",
  n_t_col = "n_t",
  diamond.col = "red",
  study.col = "blue",
  CI.col = "blue",
  Pred.Inter.col = "black",
  contour_left_min = c(-0.8, -0.5, -0.2, 0),
  contour_left_max = c(-0.5, -0.2, 0, 0.2),
  contour_right_min = c(0, 0.2, 0.5, 0.8),
  contour_right_max = c(0.2, 0.5, 0.8, 1),
  square.size = 10,
  contour_fill = c("gray95", "gray80", "gray60", "gray40"),
  text_size = 3.5,
  pred = TRUE,
  study_x = NULL,
  treatment_x = NULL,
  control_x = NULL,
  effect_x = NULL,
  weight_x = NULL,
  PredInt_x = NULL,
  xlim = NULL,
  hetero_x = -8
)

Arguments

dat	Data frame containing study-level data. Must include treatment and control means, SDs, sample sizes, and study labels.
measure	Effect size measure: "MD" (mean difference) or "SMD" (standardized mean difference). Default is "SMD".
method	Meta-analysis method for rma() (e.g., "REML"). Default is "REML".
sort	Logical. If TRUE, the studies will be sorted by effect size before plotting.
xlab	Label for the x-axis.
title	Plot title. If NULL, a default title including measure is used.
model	Model description for heterogeneity annotation. Default "Random-effects".
estimator	Estimator for heterogeneity. Default "REML".
m_c_col	Column name for control group means. Default "mean_c".
sd_c_col	Column name for control group SDs. Default "sd_c".
n_c_col	Column name for control group sample sizes. Default "n_c".
m_t_col	Column name for treatment group means. Default "mean_t".
sd_t_col	Column name for treatment group SDs. Default "sd_t".
n_t_col	Column name for treatment group sample sizes. Default "n_t".
diamond.col	Color for the pooled effect diamond. Default "red".
study.col	Color for study effect points. Default "blue".
CI.col	Color for study confidence intervals. Default "blue".
Pred.Inter.col	Color for prediction interval. Default "black".
contour_left_min	Numeric vector specifying the left-side minimum x-axis boundaries for contour shading bands (values less than the null effect).
contour_left_max	Numeric vector specifying the left-side maximum x-axis boundaries for contour shading bands (values less than or equal to the null effect).
contour_right_min	Numeric vector specifying the right-side minimum x-axis boundaries for contour shading bands (values greater than or equal to the null effect).
contour_right_max	Numeric vector specifying the right-side maximum x-axis boundaries for contour shading bands (values greater than the null effect).
square.size	Size of study points. Default 10.
contour_fill	Vector of four colors for contour shading. Default c("gray95","gray80","gray60","gray40").
text_size	Size of annotated text. Default 3.5.
pred	Logical; whether to show prediction interval. Default TRUE.
study_x	X-position for study labels. Default computed automatically.
treatment_x	X-position for treatment means. Default computed automatically.
control_x	X-position for control means. Default computed automatically.
effect_x	X-position for effect sizes. Default computed automatically.
weight_x	X-position for weights. Default computed automatically.
PredInt_x	X-position for prediction interval label. Default computed automatically.
xlim	X-axis limits. Default computed automatically.
hetero_x	X-position for heterogeneity annotation. Default -8.

Value

A ggplot2 object representing the forest plot.

Examples

forest_cont(
  dat1,
  measure = "MD",
  xlab = "Mean Difference",
  study_x = -9,
  sort = "effect",
  hetero_x = -12,
  treatment_x = -7,
  control_x = -5,
  effect_x = 5.5,
  weight_x = 10,
  PredInt_x = 7
)

forest_cont(
  dat1,
  measure = "SMD",
  xlab = "Standardized Mean Difference",
  hetero_x = -9.9,
  study_x = -7,
  sort = "effect",
  treatment_x = -5,
  control_x = -3,
  effect_x = 2.5,
  weight_x = 4,
  PredInt_x = 4
)
forest_cont(
dat1,
study.col = "darkgreen",
CI.col = "black",
diamond.col = "red",
Pred.Inter.col = "black",
measure = "SMD",
sort = "effect",
xlab = "Standardized Mean Difference",
contour_fill = c("gray90","gray70","gray50", "gray30"),
hetero_x = -9.9,
study_x = -7,
square.size = 9,
treatment_x = -5,
control_x = -3.2,
text_size = 4,
effect_x = 2.5,
weight_x = 5.8,
PredInt_x = 3
)

---

Forest Plot for Subgroup Meta-Analysis

Description

Creates a detailed forest plot for subgroup meta-analysis, including study-level effect sizes, subgroup pooled effects, heterogeneity statistics, overall pooled effect, and prediction intervals.

Usage

forest_cont_subgroup(
  dat,
  m_t_col = "mean_t",
  sd_t_col = "sd_t",
  n_t_col = "n_t",
  m_c_col = "mean_c",
  sd_c_col = "sd_c",
  n_c_col = "n_c",
  subgroup_col = "subgroup",
  study_col = "Study",
  measure = "SMD",
  method = "REML",
  xlab = NULL,
  xlim = NULL,
  model = "RE",
  title = "Subgroup Forest Plot",
  diamond.col = "red",
  overall.col = "darkgreen",
  study.col = "blue",
  CI.col = "blue",
  Pred.Inter.col = "black",
  square.size = 5,
  Pred.Int.size = 1.5,
  text_size = 3.5,
  pred = TRUE,
  xpos = list(Study = NULL, MeanT = NULL, MeanC = NULL, Effect = NULL, Weight = NULL,
    PredInt = NULL, Hetero = NULL)
)

Arguments

dat	A data frame containing the study-level data. Use dat1 included in the package for examples.
m_t_col	Name of the column for treatment group means.
sd_t_col	Name of the column for treatment group standard deviations.
n_t_col	Name of the column for treatment group sample sizes.
m_c_col	Name of the column for control group means.
sd_c_col	Name of the column for control group standard deviations.
n_c_col	Name of the column for control group sample sizes.
subgroup_col	Name of the column indicating subgroup membership.
study_col	Name of the column with study labels.
measure	Effect size measure: "SMD" (standardized mean difference) or "MD" (mean difference).
method	Method for meta-analysis: "REML" (default) or "FE".
xlab	Label for the x-axis.
xlim	Limits for the x-axis as a numeric vector of length 2.
model	Random-effects ("RE") or fixed-effects ("FE") model for pooled estimates.
title	Plot title.
diamond.col	Color for subgroup pooled effect diamonds.
overall.col	Color for the overall pooled effect diamond.
study.col	Color for study-level points.
CI.col	Color for confidence intervals of individual studies.
Pred.Inter.col	Color for the overall prediction interval.
square.size	Maximum size of study-level effect squares.
Pred.Int.size	Line thickness for prediction interval.
text_size	Base text size for annotations.
pred	Logical; if TRUE, display overall prediction interval.
xpos	numeric vector of x-axis positions for annotations

Value

A ggplot object representing the subgroup forest plot.

Examples

# Using the built-in dataset dat1
forest_cont_subgroup(dat1)

---