Type: Package
Title: Contour-Enhanced Forest Plots for Meta-Analysis
Version: 0.2.0
Description: Provides functions to create contour-enhanced forest plots for meta-analysis, supporting binary outcomes (e.g., odds ratios, risk ratios), continuous outcomes (e.g., correlations), and prevalence estimates. Includes options for prediction intervals, customized colors, study labeling, and contour shading to highlight regions of statistical significance. Based on 'metafor' and 'ggplot2'.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Imports: ggplot2, dplyr, metafor, stringr, grid
Depends: R (≥ 4.0)
NeedsCompilation: no
Packaged: 2026-01-20 05:53:50 UTC; DR. Umar Hussain
Author: Umar Hussain [aut, cre], Muhammad Abdullah Kamran [aut], Fayez Hussain Niazi [aut]
Maintainer: Umar Hussain <drumarhussain@gmail.com>
Repository: CRAN
Date/Publication: 2026-01-20 09:20:02 UTC

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)

Forest Plot for Correlation Coefficients

Description

Creates a contour-enhanced forest plot for correlation coefficients from multiple studies. Applies Fisher's Z transformation for meta-analysis and displays study-level correlations with 95% confidence intervals, pooled correlation, weights, and heterogeneity statistics.

Usage

forest_corr(
  dat,
  r_col = "r",
  n_col = "n",
  study_col = "Study",
  xlab = "Correlation (r)",
  title = "Correlation Forest Plot",
  xlim = c(-2.5, 1.5),
  diamond.col = "red",
  study.col = "blue",
  CI.col = "blue",
  square.size = 6,
  text_size = 3.5,
  xpos_study = -1.3,
  xpos_n = -1.1,
  xpos_ci = 1.2,
  xpos_weight = 1.45,
  xpos_pooled_label = NULL,
  xpos_pooled_value = NULL,
  contour_breaks = c(-1, -0.5, -0.3, -0.1, 0, 0.1, 0.3, 0.5, 1),
  contour_colors = c("gray70", "gray50", "gray30", "gray10", "gray70", "gray50",
    "gray30", "gray10")
)

Arguments

dat

Data frame containing study-level correlation data.

r_col

Character. Name of the column containing correlation coefficients. Default is "r".

n_col

Character. Name of the column containing sample sizes. Default is "n".

study_col

Character. Name of the column containing study labels. Default is "Study".

xlab

Character. Label for the x-axis. Default is "Correlation (r)".

title

Character. Plot title. Default is "Correlation Forest Plot".

xlim

Numeric vector of length 2. Limits for the x-axis. Default is c(-2.5,1.5).

diamond.col

Color for the pooled effect diamond. Default is "red".

study.col

Color for the study points. Default is "blue".

CI.col

Color for the horizontal confidence intervals. Default is "blue".

square.size

Numeric. Size of the squares representing study effect sizes. Default is 6.

text_size

Numeric. Size of text annotations. Default is 3.5.

xpos_study

Numeric. X-position for study labels. Default is -1.3.

xpos_n

Numeric. X-position for sample size labels. Default is -1.1.

xpos_ci

Numeric. X-position for correlation (95% CI) labels. Default is 1.2.

xpos_weight

Numeric. X-position for study weight labels. Default is 1.45.

xpos_pooled_label

Numeric. X-position for the pooled effect label. Default is calculated automatically.

xpos_pooled_value

Numeric. X-position for the pooled effect value. Default is calculated automatically.

contour_breaks

Numeric vector. Breakpoints for contour shading along the x-axis. Default is c(-1, -0.5, -0.3,-0.1, 0, 0.1, 0.3, 0.5, 1).

contour_colors

Character vector. Colors corresponding to contour breaks. Default is c("gray70","gray50","gray30", "gray10", "gray70", "gray50","gray30","gray10").

Value

A ggplot object representing the correlation forest plot.

Examples

## Not run: 
dat <- data.frame(
  Study = c("Smith 2010","Jones 2012","Lee 2015","Kim 2018"),
  r = c(0.2, 0.35, -0.1, 0.5),
  n = c(50, 120, 80, 60)
)
forest_corr(dat)

## End(Not run)

Prevalence Forest Plot

Description

Generates a forest plot for prevalence data with study-level estimates, confidence intervals, weights, and pooled prevalence. Supports contour shading for prevalence ranges.

Usage

forest_prev(
  dat,
  events_col = "events",
  n_col = "n",
  study_col = "Study",
  xlab = "Prevalence (%)",
  title = "Prevalence Forest Plot",
  xlim = c(-25, 140),
  diamond.col = "red",
  study.col = "blue",
  CI.col = "blue",
  square.size = 7,
  text_size = 3.5,
  xpos_study = -12,
  xpos_events = -5,
  xpos_prev = 50,
  xpos_weight = 55,
  xpos_pooled_label = NULL,
  xpos_pooled_value = NULL,
  contour_breaks = c(0, 5, 10, 25, 50),
  contour_colors = c("gray90", "gray70", "gray50", "gray30"),
  legend_title = "Prevalence"
)

Arguments

dat

A data frame containing study-level prevalence data.

events_col

Name of the column containing the number of events.

n_col

Name of the column containing the total sample size.

study_col

Name of the column with study labels.

xlab

Label for the x-axis. Default is "Prevalence (%)".

title

Plot title.

xlim

Numeric vector of length 2 specifying x-axis limits.

diamond.col

Color of the pooled prevalence diamond.

study.col

Color of the study points.

CI.col

Color of the confidence intervals.

square.size

Size of the study-level squares.

text_size

Base text size for labels and annotations.

xpos_study

X-axis position for study labels.

xpos_events

X-axis position for event counts.

xpos_prev

X-axis position for prevalence values.

xpos_weight

X-axis position for study weights.

xpos_pooled_label

X-axis position for pooled label (optional; defaults relative to pooled prevalence).

xpos_pooled_value

X-axis position for pooled value (optional; defaults relative to pooled prevalence).

contour_breaks

Numeric vector defining contour thresholds.

contour_colors

Colors for contour shading.

legend_title

Title for the contour legend.

Value

A ggplot object representing the prevalence forest plot.

Examples

dat <- data.frame(
  Study = c("Bazargani et al. 2015", "Nandhra et al. 2015", "Rai 2015", "Romano et al. 2011"),
  events = c(25, 109, 24, 9),
  n = c(454, 757, 380, 100)
)

forest_prev(
  dat = dat,
  title = "Prevalence Forest Plot",
  xlim = c(-25, 80),
  xpos_study = -12,
  xpos_events = -5,
  xpos_prev = 40,
  xpos_weight = 52,
  contour_breaks = c(0,5,10,25,35),
  contour_colors = c("gray90","gray70","gray50","gray30"),
  legend_title = "Prevalence (%)"
)