orchaRd (version 2.2.1)

caterpillars: caterpillars

Description

Using a metafor model object of class rma or rma.mv or a results table of class orchard, this function produces a caterpillar plot from mean effect size estimates for all levels of a given categorical moderator, their corresponding confidence intervals, and prediction intervals.

Usage

caterpillars(
  object,
  mod = "1",
  group,
  xlab,
  overall = TRUE,
  transfm = c("none", "tanh", "invlogit", "percent", "percentr", "inv_ft"),
  n_transfm = NULL,
  colerrorbar = "#00CD00",
  colpoint = "#FFD700",
  colpoly = "red",
  k = TRUE,
  g = TRUE,
  at = NULL,
  by = NULL,
  weights = "prop"
)

Value

Caterpillars plot

Arguments

object

Model object of class rma.mv, rma or orchard table of model results

mod

The name of a moderator variable. Otherwise, "1" for an intercept-only model.

group

The grouping variable that one wishes to plot beside total effect sizes, k. This could be study, species, or whatever other grouping variable one wishes to present sample sizes for.

xlab

The effect size measure label.

overall

Logical, indicating whether to re-label "Intrcpt" (the default label from rma or rma.mv intercept only models or meta-analyses) to "Overall". Defaults to TRUE.

transfm

If set to "tanh", a tanh transformation will be applied to effect sizes, converting Zr to a correlation or pulling in extreme values for other effect sizes (lnRR, lnCVR, SMD). "invlogit" can be used to convert lnRR to the inverse logit scale. "percentr" can convert to the percentage change scale when using response ratios and "percent" can convert to the percentage change scale of an log transformed effect size. Defaults to "none".

n_transfm

The vector of sample sizes for each effect size estimate. This is used when transfm = "inv_ft". Defaults to NULL.

colerrorbar

Colour of the error bar in the caterpillars plot. Defaults to hex code - "#00CD00".

colpoint

Point estimate colour in the caterpillars plot. Defaults to hex code - "#FFD700".

colpoly

Polygon colour in the caterpillars plot. Defaults to "red".

k

If TRUE, it displays k (number of effect sizes) on the plot.

g

If TRUE, it displays g (number of grouping levels for each level of the moderator) on the plot.

at

Used when one wants marginalised means. List of levels one wishes to predict at for the corresponding variables in by, but is not presented in output. Provide a list as follows: list(mod = c("level1", "level2")).

by

Used when one wants marginalised means. Character vector indicating the name that predictions should be conditioned on for the levels of the moderator.

weights

Used when one wants marginalised means. How to marginalize categorical variables. The default is weights = "prop", which weights means for moderator levels based on their proportional representation in the data. For example, if "sex" is a moderator, and males have a larger sample size than females, then this will produce a weighted average, where males are weighted more towards the mean than females. This may not always be ideal. In the case of sex, for example, males and females are roughly equally prevalent in a population. As such, you can give the moderator levels equal weight using weights = "equal".

Author

Shinichi Nakagawa - [e-mail]

Daniel Noble - [e-mail]

Examples

# \donttest{
data(eklof)
eklof<-metafor::escalc(measure="ROM", n1i=N_control, sd1i=SD_control,
m1i=mean_control, n2i=N_treatment, sd2i=SD_treatment, m2i=mean_treatment,
data=eklof)
# Add the unit level predictor
eklof$Datapoint<-as.factor(seq(1, dim(eklof)[1], 1))
# fit a MLMR - accouting for some non-independence
eklof_MR<-metafor::rma.mv(yi=yi, V=vi, mods=~ Grazer.type-1, random=list(~1|ExptID,
~1|Datapoint), data=eklof)
results <- mod_results(eklof_MR, mod = "Grazer.type",  group = "First.author")
caterpillars(results, mod = "Grazer.type",
group = "First.author", xlab = "log(Response ratio) (lnRR)", g = FALSE)

# Example 2
data(lim)
lim$vi<- 1/(lim$N - 3)
lim_MR<-metafor::rma.mv(yi=yi, V=vi, mods=~Phylum-1, random=list(~1|Article,
~1|Datapoint), data=lim)
results_lim <- mod_results(lim_MR, mod = "Phylum", group = "Article")
caterpillars(results_lim, mod = "Phylum",
group = "Article", xlab = "Correlation coefficient", transfm = "tanh")
# }