orchard_plot: orchard_plot

In daniel1noble/orchaRd: Orchard Plots and Prediction Intervals for Meta-analysis and Meta-regression

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,
  tree.order = NULL,
  trunk.size = 0.5,
  branch.size = 1.2,
  twig.size = 0.5,
  transfm = c("none", "tanh", "invlogit", "percent", "percentr"),
  condition.lab = "Condition",
  legend.pos = c("bottom.right", "bottom.left", "top.right", "top.left", "top.out",
    "bottom.out", "none"),
  k.pos = c("right", "left", "none"),
  colour = FALSE,
  fill = TRUE,
  weights = "prop",
  by = NULL,
  at = NULL,
  upper = TRUE,
  flip = TRUE
)

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.
tree.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.
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".
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.
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.

Value

Orchard plot

Author(s)

Shinichi Nakagawa - [e-mail]

Daniel Noble - [e-mail]

Examples

## Not run: 
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")

## End(Not run)

daniel1noble/orchaRd documentation built on May 12, 2024, 7:46 a.m.