orchard_plot: orchard_plot

Description

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

Usage

orchard_plot(
  object,
  mod = "1",
  group,
  xlab,
  N = NULL,
  alpha = 0.5,
  angle = 90,
  cb = TRUE,
  k = TRUE,
  g = TRUE,
  est = FALSE,
  mod.order = NULL,
  trunk.size = 0.5,
  branch.size = 1.2,
  twig.size = 0.5,
  point.size = c(1, 3.5),
  transfm = c("none", "tanh", "invlogit", "percent", "percentr", "inv_ft"),
  n_transfm = NULL,
  condition.lab = NULL,
  legend.pos = c("bottom.right", "bottom.left", "top.right", "top.left", "top.out",
    "bottom.out", "none"),
  k.pos = c("right", "left", "none"),
  k.size = 3.5,
  est.size = 3,
  refline.pos = 0,
  colour = FALSE,
  fill = TRUE,
  weights = "prop",
  by = NULL,
  at = NULL,
  upper = TRUE,
  flip = TRUE
)

Value

Orchard plot

Arguments

object: model object of class rma.mv, rma, or orchard table of model results.
mod: the name of a moderator. Defaults to "1" for an intercept-only model. Not needed if an orchard_plot is provided with a mod_results object of class orchard.
group: The grouping variable that one wishes to plot beside total effect sizes, k. This could be study, species, or any grouping variable one wishes to present sample sizes for. Not needed if an orchard_plot is provided with a mod_results object of class orchard.
xlab: The effect size measure label.
N: The name of the column in the data specifying the sample size so that each effect size estimate is scaled to the sample size, N. Defaults to NULL, so that precision is used for scaling each raw effect size estimate instead of sample size.
alpha: The level of transparency for effect sizes represented in the orchard plot.
angle: The angle of y labels. The default is 90 degrees.
cb: If TRUE, it uses 20 colour blind friendly colors.
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.
est: If TRUE, it displays the mean estimate and confidence interval (e.g., 0.25 [0.10, 0.40]) alongside or below the k labels on the plot. Defaults to FALSE.
mod.order: Order in which to plot the groups of the moderator when it is a categorical one. Should be a vector of equal length to number of groups in the categorical moderator, in the desired order (bottom to top, or left to right for flipped orchard plot)
trunk.size: Size of the mean, or central point.
branch.size: Size of the confidence intervals.
twig.size: Size of the prediction intervals.
point.size: Numeric vector of length 2, specifying the minimum and maximum point sizes for effect size bubbles. Defaults to c(1, 3.5). Useful for controlling bubble size in small figures.
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.
condition.lab: Label for the condition being marginalized over.
legend.pos: Where to place the legend. To remove the legend, use legend.pos = "none".
k.pos: Where to put k (number of effect sizes) on the plot. Users can specify the exact position or they can use specify "right", "left", or "none". Note that numeric values (0, 0.5, 1) can also be specified and this would give greater precision.
k.size: Numeric, the font size for k (and g) labels on the plot. Defaults to 3.5.
est.size: Numeric, the font size for estimate and CI labels when est = TRUE. Defaults to 3.0.
refline.pos: Where to put the reference line. defaults to 0.
colour: Colour of effect size shapes. By default, effect sizes are colored according to the mod argument. If TRUE, they are colored according to the grouping variable
fill: If TRUE, effect sizes will be filled with colours. If FALSE, they will not be filled with colours.
weights: Used when one wants marginalised means. How to marginalize categorical variables. The default is weights = "prop", which weights moderator level means 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".
by: Character vector indicating the name that predictions should be conditioned on for the levels of the moderator.
at: List of levels one wishes to predict at for the corresponding varaibles in 'by'. Used when one wants marginalised means. This argument can also be used to suppress levels of the moderator when argument subset = TRUE. Provide a list as follows: list(mod = c("level1", "level2")).
upper: Logical, defaults to TRUE, indicating that the first letter of the character string for the moderator variable should be capitalized.
flip: Logical, defaults to TRUE, indicating whether the plot should be flipped.

Author

Shinichi Nakagawa - s.nakagawa@unsw.edu.au

Daniel Noble - daniel.noble@anu.edu.au

Examples

Run this code

# \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 - accounting 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 = "ExptID")
orchard_plot(results, mod = "Grazer.type",
group = "ExptID", xlab = "log(Response ratio) (lnRR)")
# or
orchard_plot(eklof_MR, mod = "Grazer.type", group = "ExptID",
xlab = "log(Response ratio) (lnRR)")

# 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)
orchard_plot(lim_MR, mod = "Phylum", group = "Article",
xlab = "Correlation coefficient", transfm = "tanh", N = "N")
# }

Run the code above in your browser using DataLab