viz_tlma_forest: Forest plot for the visualization of all three levels of a three-level meta-analysis

Description

Creates a thick or classic forest plot which shows the effects contained in each study, the overall effect of each study and the summary effect of a three-level meta-analysis.

Usage

viz_tlma_forest(
  x,
  variant = "classic",
  median_precision = FALSE,
  median_precision_thick = TRUE,
  annotate_CI = FALSE,
  study_table = NULL,
  summary_table = NULL,
  table_headers = NULL,
  ordered = FALSE,
  clouds = TRUE,
  spread = 0.3,
  col = FALSE,
  labels = NULL,
  xlab = "Effect Size",
  ylab = NULL,
  title = NULL,
  confidence_level_ci = 0.95,
  prediction_level_pi = 0.95,
  show_nr_ES = TRUE,
  x_limit = NULL,
  table_layout = NULL,
  line = TRUE,
  linewidth = 0.4,
  text_size = 3,
  tick_col = "firebrick"
)

Value

A forest plot containing point estimates for single effects, study effects and the overall result of a three-level meta-analysis is created using ggplot2.

Arguments

x: metafor rma.mv object
variant: “classic” (default) or “thick” to create a classic or thick TLMA forest plot variant
median_precision: adds grey errorbars that represent the median precision of an effect contained in the respective study. The errorbar’s thickness denotes the number of effects contained in the study.
median_precision_thick: determines whether the thickness of the median precision errorbars represents the number of effect sizes contained within the respective study
annotate_CI: adds a right-hand side table to the plot containing the confidence intervals and number of effects of each study
study_table: custom table on the left-hand side of the plot that contains study information. Takes a dataframe as input which has to be of a length equal to the number of studies.
summary_table: custom table on the left-hand side of the plot that contains information about the summary effect. Takes a dataframe as input which contains one row.
table_headers: headers for each column of the left-hand side table. Takes a character vector as input
ordered: orders the plot by effect size when TRUE
clouds: “TRUE”: shows the effects contained in each study as a cloud around the study effect. “FALSE”: only study effects are shown.
spread: determines how far the single effects spread around the study effect
col: colors single effects by study
labels: y-axis tick labels. Takes a vector the length of the dataset as input.
xlab: x-axis label
ylab: y-axis label
title: plot title
confidence_level_ci: numeric confidence level for the confidence intervals of the study effects. This argument is also used in the calculation of the median precision of an effect included in a study for additional grey error bars.
prediction_level_pi: numeric confidence level for the prediction interval of the summary effect
show_nr_ES: adds columns to the right-hand side table which shows the number of effects contained in the respective study
x_limit: determines the limits of the x-axis. Input is a numeric vector of length 2 (min, max).
table_layout: numeric layout matrix to customize the arrangement of the plot and tables
line: if “TRUE” it creates a line connecting the ordered study effects
linewidth: determines the width of the line connecting the ordered study effects
text_size: determines text size within the plot
tick_col: determines color of study effect markers

Author

Verena Pilar <[email protected]>

Details

The function viz_tlma_forest creates a forest plot which visualizes all three levels of a three-level meta-analysis. The study effects are most prominently featured and sized according to their weight in the meta-analysis. Each overall effect of a study that contains at least two effects is surrounded by a cloud of the effects that are contained within it. The plot is completed by the overall result with its prediction interval shown at the bottom. It is available in the classic and the thick (Schild & Voracek, 2015) forest plot variant.

Note: This function was developed on the basis of the viz_forest code which was created by Michael Kossmeier. Note: This function adapted parts of the forest_plot_3 function code by Fernández-Castilla et al (2020) to generate study-level information of the three-level meta-analysis.

References

Fernández-Castilla, B., Declercq, L., Jamshidi, L., Beretvas, N., Onghena, P., & Van den Noortgate, W. (2020). Visual representations of meta-analyses of multiple outcomes: extensions to forest plots, funnel plots, and caterpillar plots. Methodology, 16(4), 299-315. https://doi.org/10.1002/jrsm.1424

Schild, A. H. E., & Voracek, M. (2015). Finding your way out of the forest without a trail of bread crumbs: Development and evaluation of two novel displays of forest plots. Research Synthesis Methods, 6(1), 74–86. https://doi.org/10.1002/jrsm.1125

Examples

Run this code

if (requireNamespace("psymetadata", quietly = TRUE)) {

  # Get wibbelink2017 data
  testdata <- psymetadata::wibbelink2017


  # Calculate the three-level meta-analytic model
  testmodel <- metafor::rma.mv(yi,
                               vi,
                               random = ~ 1 | study_id/es_id,
                               tdist = TRUE,
                               data = testdata,
                               method = "REML")

  # Plot the TLMA forest plot
  viz_tlma_forest(x = testmodel)
  # Plot the thick variant of the TLMA forest plot with a table showing study
  # effects plus their confidence intervals
  viz_tlma_forest(x = testmodel, variant = "thick", annotate_CI = TRUE)
}

Run the code above in your browser using DataLab