Package {orchaRd}

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling 'rhs(lhs)'.

.MSb

Description

Computes the between group mean-squares difference.

Usage

.MSb(x1, x2, n1, n2, paired = FALSE)

Arguments

Value

The between group mean-squares difference.

.MSw

Description

Computes the within group mean-squares difference.

Usage

.MSw(sd1, sd2, n1, n2, paired = FALSE)

Arguments

Value

The within group mean-squares difference.

Add Confidence Interval Lines to Orchard Plot

Description

Internal function that creates a ggplot2 layer to add horizontal lines corresponding to the original model's 95

Usage

.add_ci_lines(orig_results, ci_lines_color)

Arguments

Details

These lines help visualize how the leave-one-out effect size estimates compare to the overall model estimate.

Value

A ggplot2 layer (via geom_hline) that can be added to a plot.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Add Ghost Points to Orchard Plot

Description

Internal function to add ghost points to an orchard plot.

Usage

.add_ghost_points(data, transfm)

Arguments

Details

Ghost points represent the effect sizes that were omitted in each leave-one-out iteration. They are plotted as empty points with reduced opacity to indicate their auxiliary role.

Value

A ggplot2 layer (via geom_quasirandom) displaying the ghost points.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Create the base bubble plot layer.

Description

Create the base bubble plot layer.

Usage

.base_bubble_plot(data_trim, alpha)

Create base for orchard plot

Description

Create base for orchard plot

Usage

.base_orchard_plot(data_trim, colour, fill, alpha)

Add axis labels to bubble plot.

Description

Add axis labels to bubble plot.

Usage

.bbp_axis_labels(xlab, ylab)

Set fill colors for bubble plot points.

Description

Set fill colors for bubble plot points.

Usage

.bbp_colors(data_trim, cb)

Add confidence interval lines to bubble plot.

Description

Add confidence interval lines to bubble plot.

Usage

.bbp_conf_interval(mod_table, ci.lwd, ci.col)

Add estimate line to bubble plot.

Description

Add estimate line to bubble plot.

Usage

.bbp_estimate_line(mod_table, est.lwd, est.col)

Add facetting to bubble plot by condition.

Description

Add facetting to bubble plot by condition.

Usage

.bbp_facets(data_trim, condition.nrow, condition.order)

Add k and g annotation labels to bubble plot.

Description

Add k and g annotation labels to bubble plot.

Usage

.bbp_kg_labels(k, g, k.pos, kg_labels)

Add and position legends on bubble plot.

Description

Add and position legends on bubble plot.

Usage

.bbp_legends(legend.pos, scale_legend)

Add prediction interval lines to bubble plot.

Description

Add prediction interval lines to bubble plot.

Usage

.bbp_pred_interval(mod_table, pi.lwd, pi.col)

Bubble plot ggplot2 theme settings.

Description

Bubble plot ggplot2 theme settings.

Usage

.bbp_theme()

.calc.kurtosis

Description

Computes the excess kurtosis of a numeric vector using small sample correction.

Usage

.calc.kurtosis(x)

Arguments

Value

A numeric value representing the kurtosis estimate or variance.

.calc.skewness

Description

Computes the skewness of a numeric vector using small sample correction.

Usage

.calc.skewness(x)

Arguments

Value

A numeric value representing the skewness estimate or variance.

Colour blind palette

Description

Colour blind palette

Usage

.colour_blind_palette

Format

An object of class character of length 20.

Check if Column Exists

Description

Verifies if a specified column exists in the data frame

Usage

.column_exists(data, column_name)

Arguments

Value

logical. TRUE if the column exists, FALSE otherwise

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Check if Column is Categorical

Description

Determines if a column can be used as a categorical variable. Valid categorical variables include: - Character vectors - Factors - Integer values (common for ID numbers used as factors)

Usage

.column_is_categorical(col)

Arguments

Value

logical. TRUE if the column can be used as a category, FALSE otherwise

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Create Temporary Phylogenetic Matrix For Leave-One-Out Analysis

Description

Creates a correlation matrix from a phylogenetic tree for the species remaining in the data subset during leave-one-out analysis.

Usage

.create_tmp_phylo_matrix(data, phylo_args)

Arguments

Value

A phylogenetic correlation matrix for the species in the data subset.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Create Temporary Variance-Covariance Matrix

Description

Creates a variance-covariance matrix for a subset of data using metafor's vcalc function.

Usage

.create_tmp_vcv(data, vcalc_args)

Arguments

Value

A variance-covariance matrix for use in meta-analytic models.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Extract model data used in metafor model

Description

Gets the data actually used to fit a metafor model, after applying any subset and removing rows with missing values.

Usage

.extract_model_data(model)

Arguments

Value

A data frame of the used observations.

Get Leave-One-Out Effect Sizes

Description

Extracts and aggregates effect size data from each leave-one-out iteration into a single data frame. Applies mod_results() to each model and combines the resulting data values.

Usage

.get_effectsizes(outputs, group)

Arguments

Value

A data frame of effect sizes with a column 'moderator' indicating the omitted group. Contains the same structure as the data element from mod_results() for each model iteration.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Get Leave-One-Out Model Estimates

Description

Extracts and combines the model estimates from each leave-one-out iteration into a single data frame. Applies mod_results() to each model and combines the resulting mod_table values.

Usage

.get_estimates(outputs, group)

Arguments

Value

A data frame of model estimates with an added column 'name' indicating the omitted group. Contains the same structure as the mod_table from mod_results() for each model iteration.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Compute k and g labels for each condition.

Description

Takes data from mod_results and compute the K (number of effect sizes) and G (number of groups). NOTE: It expects the condition from data to be a factor

Usage

.get_kg_labels(dat)

.get_kg_labels(dat)

Get the output from mod_results

Description

Take the inputs passed to plotting functions and make sure to convert them into the results from mod_results.

Usage

.get_results(object, mod, group, N, by, at, weights, upper = TRUE)

Set scale for bubble plot.

Description

Set scale for bubble plot.

Usage

.get_size_scale(N, dat)

Validate Group Argument

Description

Checks if a group variable meets the requirements for analysis: - It is not missing or NULL - It exists in the data frame - It is a categorical variable - It has no missing values

Usage

.is_group_valid(data, column_name)

Arguments

Value

logical. TRUE if the group variable is valid, otherwise stops with an error message

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Check if Object is from metafor Package

Description

Verifies if an object is of class rma.mv, rma, rma.uni, or robust.rma

Usage

.is_metafor_object(obj)

Arguments

Value

logical. TRUE if the object is from metafor package, FALSE otherwise

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Validate Model Argument

Description

Checks if a model argument is valid for meta-analysis: - It is not missing or NULL - It is a metafor package object (rma.mv, rma, etc.)

Usage

.is_model_valid(model)

Arguments

Value

logical. TRUE if the model is valid, otherwise stops with an error message

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

.lnM

Description

Computes the natural logarithm of the ratio of between and within group variances as a measure of the magnitude of difference.

Usage

.lnM(x1, x2, sd1, sd2, n1, n2)

Arguments

Value

The natural logarithm of the ratio of between and within group variances.

Add axis labels to orchard plot

Description

Add axis labels to orchard plot

Usage

.orcd_axis_labels(xlab)

Set a colour-blind-friendly palette

Description

Set a colour-blind-friendly palette

Usage

.orcd_colour_blind_palette(cb)

Add confidence intervals

Description

Add confidence intervals

Usage

.orcd_conf_intervals(mod_table, branch.size)

Add k and g to base orchard plot

Description

Add k and g to base orchard plot

Usage

.orcd_k_and_g(
  k,
  k.pos,
  g,
  data_trim,
  mod_table,
  flip = TRUE,
  k.size = 3.5,
  est = FALSE,
  est.size = 3
)

Arguments

Value

ggplot object with added text annotations.

Add legends to orchard plot

Description

Add legends to orchard plot

Usage

.orcd_legends(legend.pos, scale_legend, condition.lab, flip = TRUE)

Add point estimates for orchard plot

Description

Note: Point estimate previously used 'geom_pointrange', plotting the estimate and prediction interval at the same time. However, that was less flexible. Now PI are plotted with 'geom_linerange' and point estimate with 'geom_point'.

Usage

.orcd_point_estimates(mod_table, colour, trunk.size)

Add prediction intervals

Description

Add prediction intervals

Usage

.orcd_pred_intervals(mod_table, twig.size)

Add reference line for orchard plot

Description

Add reference line for orchard plot

Usage

.orcd_reference_line(alpha, refline.pos)

Theme for orchard plot

Description

Theme for orchard plot

Usage

.orcd_theme(angle, flip = TRUE)

Reorder the tree

Description

Reorder the position of the moderators in the plot by reordering the factors in the model table and the data.

Usage

.order_mod(results, mod.order)

Prune Phylogenetic Tree For Leave-One-Out Analysis

Description

Removes species from a phylogenetic tree that are not present in the current data subset during leave-one-out analysis.

Usage

.prune_tree(tree, species_names)

Arguments

Value

A pruned phylogenetic tree containing only the tips for species in species_names.

Author(s)

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

Facundo Decunta - fdecunta@agro.uba.ar

Fisher Z-transformation of Correlation Coefficient

Description

Converts a Pearson correlation coefficient r to Fisher's Zr using the inverse hyperbolic tangent.

Usage

.r.to.zr(r)

Arguments

Value

The Zr-transformed correlation value(s).

Fit Multiple Meta-Analytic Models For Leave-One-Out Analysis

Description

Iteratively refits a meta-analytic model, leaving out one level of a specified grouping variable in each iteration. This internal function handles the actual model refitting process for the leave-one-out analysis.

Usage

.run_leave1out(
  model,
  group,
  vcalc_args = NULL,
  robust_args = NULL,
  phylo_args = NULL
)

Arguments

Details

The function creates a subset of the original data for each unique value in the grouping variable, removing that group and refitting the model using the same specification as the original model. If variance-covariance matrices or phylogenetic corrections were used in the original model, these are recalculated for each subset. If a model fails to fit, NULL is returned for that group.

Value

A named list of models, each fitted after omitting one group. Names correspond to the omitted group IDs. Any failed model fits will be NULL.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

SAFE bootstrap : dependent samples

Description

Computes a SAFE bootstrap estimate of the effect size and its variance for dependent samples.

Usage

.safe_lnM_dep(
  x1bar,
  x2bar,
  sd1,
  sd2,
  n,
  r,
  min_kept = 2000,
  chunk_init = 4000,
  chunk_max = 2e+06,
  max_draws = Inf,
  patience_noaccept = 5,
  seed = 565
)

Arguments

Value

A list containing the point estimate, variance, number of kept samples, total draws, number of attempts, and status.

SAFE bootstrap : independent samples

Description

Computes a SAFE bootstrap estimate of the effect size and its variance for independent samples.

Usage

.safe_lnM_indep(
  x1bar,
  x2bar,
  sd1,
  sd2,
  n1,
  n2,
  min_kept = 2000,
  chunk_init = 4000,
  chunk_max = 2e+06,
  max_draws = Inf,
  patience_noaccept = 5,
  seed = 565
)

Arguments

Value

A list containing the point estimate, variance, number of kept samples, total draws, number of attempts, and status.

Set Color Palette for Orchard Plot

Description

Internal function to determine the appropriate color palette based on the number of elements in the leave-one-out results.

Usage

.set_color_palette(loo_results)

Arguments

Details

When the number of rows in the leave-one-out results exceeds 20, a viridis color scale is used. Otherwise, a color-blind friendly manual palette is applied.

Value

A list with two components:

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Set the condition variable for plotting.

Description

Set the condition variable for plotting.

Usage

.set_condition(results, condition.order)

Set width for ggplot2::position_dodge2()

Description

When the model use has some condition, the plot needs separation for estimates from the same moderator. This function adds space when a condition is present.

Usage

.set_width(mod_table)

Jackknife Estimation of Skewness and Kurtosis for computing sampling variances

Description

Computes jackknife estimate and standard error for skewness and kurtosis.

Usage

.sv_jack(
  x,
  bias.correct = TRUE,
  return.replicates = FALSE,
  type = c("skew", "kurt")
)

Arguments

Value

A list with estimate ('est'), bias-corrected estimate ('est_bc'), variance, and standard error.

Trim whitespace from a single column in a data frame

Description

Strips leading and trailing whitespace from character or factor columns. This prevents mismatches between moderator levels, mod.order values, and model coefficient names (e.g., "Echinodermata " vs "Echinodermata").

Usage

.trimws_col(x)

Arguments

Value

The same vector with whitespace trimmed (character/factor only).

.v_lnM

Description

Computes the sampling variance of the natural logarithm of the ratio of between and within group variances.

Usage

.v_lnM(x1, x2, sd1, sd2, n1, n2, r = NULL)

Arguments

Value

The sampling variance of the natural logarithm of the ratio of between and within group variances.

Validate Phylogenetic Arguments

Description

Checks the validity of the arguments provided for phylogenetic matrix calculations. Ensures the tree is a proper phylogenetic object and that the species column name is correctly linked to a random effect in the model.

Usage

.validate_phylo_args(model, phylo_args)

Arguments

Value

The validated phylo_args list if all checks pass.

Validate Robust Variance Estimation Arguments

Description

Validates that robust_args contains the required parameters and that they reference valid columns in the data. Ensures that the cluster variable exists in the provided model data.

Usage

.validate_robust_args(model_data, robust_args)

Arguments

Value

The validated robust_args list if all checks pass.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Validate Variance-Covariance Calculation Arguments

Description

Ensures that the arguments provided for variance-covariance calculation are valid and refer to existing variables in the model data. Performs checks on the structure and content of the vcalc_args list.

Usage

.validate_vcalc_args(model_data, vcalc_args)

Arguments

Value

The validated vcalc_args list if all checks pass.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Variance of Fisher Z-transformed Correlation

Description

Computes the approximate sampling variance of Fisher's Zr given a sample size.

Usage

.zr.variance(n)

Arguments

Value

The variance of the Zr-transformed correlation.

R2_calc

Description

Calculated R2 (R-squared) for mixed (mulitlevel) models, based on Nakagawa & Schielzeth (2013).

Usage

R2_calc(model)

Arguments

Value

A named numeric vector of length two: R2_marginal, the proportion of variance explained by the fixed effects (moderators) alone, and R2_conditional, the proportion explained by both the fixed and random effects. Values range from 0 to 1.

Author(s)

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

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

Examples

data(lim)
lim$vi<-(1/sqrt(lim$N - 3))^2
lim_MR<-metafor::rma.mv(yi=yi, V=vi, mods=~Phylum-1,
random=list(~1|Article, ~1|Datapoint), data=lim)
R2 <- R2_calc(lim_MR)

VCV_dARR

Description

Sampling error matrix used in Pottier et al. (2021) meta-analysis on sex-differences in acclimation

Format

A sampling variance matrix :

References

Pottier et al. 2022. Functional Ecology

Zr_to_r

Description

Converts Zr back to r (Pearson's correlation coefficient)

Usage

Zr_to_r(df)

Arguments

Value

A data frame containing all the model results including mean effect size estimate, confidence and prediction intervals with estimates converted back to r

Author(s)

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

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

bubble_plot

Description

Using a metafor model object of class rma or rma.mv, a results table of class orchard, or a raw data.frame, the bubble_plot function creates a bubble plot from slope estimates or raw effect sizes. When a raw data.frame is provided, only the data points are plotted (no model fit lines). In cases when a model includes interaction terms, this function creates panels of bubble plots.

Usage

bubble_plot(
  object,
  mod,
  group = NULL,
  xlab = "Moderator",
  ylab = "Effect size",
  N = NULL,
  alpha = 0.5,
  cb = TRUE,
  k = TRUE,
  g = FALSE,
  transfm = c("none", "tanh", "invlogit", "percent", "percentr"),
  n_transfm = NULL,
  est.lwd = 1,
  ci.lwd = 0.5,
  pi.lwd = 0.5,
  est.col = "black",
  ci.col = "black",
  pi.col = "black",
  point.size = c(1, 3.5),
  legend.pos = c("top.left", "top.right", "bottom.right", "bottom.left", "top.out",
    "bottom.out", "none"),
  k.pos = c("top.right", "top.left", "bottom.right", "bottom.left", "none"),
  condition.nrow = 2,
  condition.order = NULL,
  weights = "prop",
  by = NULL,
  at = NULL,
  yi = NULL,
  vi = NULL,
  stdy = NULL
)

Arguments

Value

Bubble plot

Author(s)

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

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

Examples

data(lim)
lim[, "year"] <- as.numeric(lim$year)
lim$vi <- 1 / (lim$N - 3)
model <- metafor::rma.mv(
  yi = yi, V = vi, mods = ~ Environment * year,
  random = list(~ 1 | Article, ~ 1 | Datapoint), data = na.omit(lim)
)
test <- orchaRd::mod_results(
  model, mod = "year", group = "Article",
  data = lim, weights = "prop", by = "Environment")
orchaRd::bubble_plot(
  test, mod = "year", group = "Article",
  legend.pos = "top.left")
# Or just using model directly
orchaRd::bubble_plot(
  model, mod = "year", legend.pos = "top.left",
  group = "Article", weights = "prop",
  by = "Environment")

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"
)

Arguments

Value

Caterpillars plot

Author(s)

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

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

Examples

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")

Correlation Difference

Description

Computes the difference in correlation coefficients between two groups along with associated sampling variance for meta-analysis. The correlation and associated sample size or the data frame of the two variables can be provided

Usage

cor_diff(cor1 = NULL, cor2 = NULL, n1 = NULL, n2 = NULL, x1 = NULL, x2 = NULL)

Arguments

Value

A data frame with the difference in correlations and the sampling variances of the difference.

Examples

set.seed(982)
# Example with known correlations
cor_diff(0.5, 0.3, 100, 100)
cor_diff(0.2, 0.4, 40, 40)

cvh1_ml

Description

CVH1 for mulilevel meta-analytic models, based on Yang et al. (2023). Under multilevel models, we can have multiple CVH1. TODO - we need to cite original CVH1 paper

Usage

cvh1_ml(model, boot = NULL)

Arguments

Value

A data frame containing all the model results including mean effect size estimate, confidence, and prediction intervals

Author(s)

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

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

References

TODO

Examples

library(metafor)
# NOTE: boot is set LOW here for speed; use boot >= 1000 in practice.
data(english)
english <- escalc(measure = "SMD", n1i = NStartControl,
  sd1i = SD_C, m1i = MeanC, n2i = NStartExpt, sd2i = SD_E,
  m2i = MeanE, var.names = c("SMD", "vSMD"), data = english)
english_MA <- rma.mv(yi = SMD, V = vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID), data = english)
cvh1_ml(english_MA)
cvh1_ml(english_MA, boot = 10)

cvh2_ml

Description

CVH2 for mulilevel meta-analytic models, based on Yang et al. (2023). Under multilevel models, we can have multiple CVH2. TODO - we need to cite original CVH2 paper

Usage

cvh2_ml(model, boot = NULL)

Arguments

Value

A data frame containing all the model results including mean effect size estimate, confidence, and prediction intervals

Author(s)

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

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

References

TODO

Examples

library(metafor)
# NOTE: boot is set LOW here for speed; use boot >= 1000 in practice.
data(english)
english <- escalc(measure = "SMD", n1i = NStartControl,
  sd1i = SD_C, m1i = MeanC, n2i = NStartExpt, sd2i = SD_E,
  m2i = MeanE, var.names = c("SMD", "vSMD"), data = english)
english_MA <- rma.mv(yi = SMD, V = vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID), data = english)
cvh2_ml(english_MA)
cvh2_ml(english_MA, boot = 10)

eklof

Description

Eklof et al. (2012) evaluated the effects of predation on benthic invertebrate communities. Using the log response ratio they quantified differences in abundance and/or biomass of gastropods and Amphipods in groups with and without predation in an experimental setting. Below we describe the variables used in our examples and analyses.

Format

A data frame :

ExptID

Experiment / effect size ID

First.author

First author of publication

Publication.year

Year of publication

Journal

Journal published within

Research.group

Research group that data arose from

Grazer.type

Type of grazer

mean_treatment

Mean abundance/biomass of invertebrates in treatment group

SD_treatment

Standard deviation in abundance/biomass of invertebrates in treatment group

N_treatment

Sample size of invertebrate sample in treatment group

mean_control

Mean abundance/biomass of invertebrates in control group

SD_control

Standard deviation in abundance/biomass of invertebrates in control group

N_control

Sample size of invertebrate sample in control group

...

References

Eklof J.S., Alsterberg C., Havenhand J.N., Sundback K., Wood H.L., Gamfeldt L. 2012. Experimental climate change weakens the insurance effect of biodiversity. Ecology Letters, 15:864-872. https://doi.org/10.1111/j.1461-0248.2012.01810.x

english

Description

English and Uller (2016) performed a meta-analysis on the effects of early life dietary restriction (a reduction in a major component of the diet without malnutrition; e.g. caloric restriction) on average age at death, using the standardised mean difference (often called *d*). In a subsequent publication, Senior et al. (2017) analysed this dataset for effects of dietary-restriction on among-individual variation in the age at death using the log coefficient of variation ratio. A major prediction in both English & Uller (2016) and Senior et al. (2017) was that the type of manipulation, whether the study manipulated quality of food versus the quantity of food, would be important.

Format

A data frame :

StudyNo

Study ID

EffectID

Effect size ID

Author

First author of study

Year

Year of study publication

Journal

Research journal where study was published

Species

Common name of species

Phylum

Phylum of species

ExptLifeStage

Life stage when manipulation was undertaken

ManipType

Type of food manipulation

CatchUp

Whether species exhibits catchup growth

Sex

Sex of organisms in sample

AdultDiet

Diet adults were provided and whether it was restricted (treatment) or the control

NStartControl

Sample size of the control group

NStartExpt

Sample size of the treatment group

MeanC

Mean of the control group

MeanE

Mean of the treatment/experimental group

SD_C

Standard deviation of the control group

SD_E

Standard deviation of the treatment/experimental group

...

References

English S, Uller T. 2016. Does early-life diet affect longevity? A meta-analysis across experimental studies. Biology Letters, 12: http://doi:10.1098/rsbl.2016.0291

firstup

Description

Uppercase moderator names

Usage

firstup(x, upper = TRUE)

Arguments

Value

Returns a character string with all combinations of the moderator level names with upper case first letters

Author(s)

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

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

fish

Description

Fish data example.

Format

A data frame

deg_dif

Temperature difference between treatments

es_ID

Effect size ID

experimental_design

Experimental design type

group_ID

Group ID

lnrr

Log Response ratio effect size

lnrr_vi

Sampling variance for lnRR

mean_control

Mean for control

mean_treat

Mean for treatment

n_control

Sample size for control

n_treat

Sample size for treatment

paper_ID

Paper ID

sd_control

SD for control

sd_treat

SD for treatment

species_ID

Species ID

trait.type

Type of trait effect size was calculated from

treat_end_days

Duration of time developmental treatmemt was applied

References

Lim J.N., Senior A.M., Nakagawa S. 2014. Heterogeneity in individual quality and reproductive trade-offs within species. Evolution. 68(8):2306-18. doi: 10.1111/evo.12446

geom_pub_stats_naka

Description

This function adds a corrected meta-analytic mean, sensu Nakagawa et al. 2022, confidence interval and text annotation to an intercept only orchard plot.

Usage

geom_pub_stats_naka(
  data,
  col = "blue",
  plotadj = -0.05,
  textadj = 0.05,
  branch.size = 1.2,
  trunk.size = 3
)

Arguments

Value

A list of ggplot2 objects to be added to the orchard plot.

Author(s)

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

geom_pub_stats_yang

Description

This function adds a corrected meta-analytic mean, sensu Yang et al. 2023, confidence interval and text annotation to an intercept only orchard plot.

Usage

geom_pub_stats_yang(
  data,
  col = "red",
  plotadj = -0.05,
  textadj = 0.05,
  branch.size = 1.2,
  trunk.size = 3
)

Arguments

Value

A list of ggplot2 objects to be added to the orchard plot.

Author(s)

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

get_data_raw

Description

Collects and builds the data used to fit the rma.mv or rma model in metafor.

Usage

get_data_raw(
  model,
  mod,
  group,
  N = NULL,
  at = NULL,
  subset = TRUE,
  upper = TRUE
)

Arguments

Value

Returns a data frame

Author(s)

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

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

Examples

data(fish)
warm_dat <- fish
model <- metafor::rma.mv(
  yi = lnrr, V = lnrr_vi,
  random = list(~1 | group_ID, ~1 | es_ID),
  mods = ~ experimental_design + trait.type +
    deg_dif + treat_end_days,
  method = "REML", test = "t", data = warm_dat,
  control = list(optimizer = "optim",
    optmethod = "Nelder-Mead"))
test <- get_data_raw(
  model, mod = "trait.type",
  group = "group_ID",
  at = list(trait.type = c("physiology",
    "morphology")))
 test2 <- get_data_raw(model, mod = "1", group = "group_ID")

get_data_raw_cont

Description

Collects and builds the data used to fit the rma.mv or rma model in metafor when a continuous variable is fit within a model object.

Usage

get_data_raw_cont(model, mod, group, N = NULL, by)

Arguments

Value

Returns a data frame

Author(s)

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

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

get_ints_dat

Description

This function extracts the corrected meta-analytic mean and confidence intervals from a model object.

Usage

get_ints_dat(model, type = c("bc", "br"))

Arguments

Value

A list containing the corrected meta-analytic mean and confidence intervals, and a label for the plot.

Author(s)

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

Convert a glmmTMB model to an rma.mv-compatible object

Description

Wraps a fitted glmmTMB model in a light-weight object with class c("rma.mv", "rma") so it can be passed to orchaRd functions that operate on metafor model objects. The main use-case is multilevel meta-analysis fitted with glmmTMB, including models that use structured covariance terms such as equalto() and propto().

Usage

glmmTMB_to_rma(
  model,
  yi,
  vi,
  data = NULL,
  V = NULL,
  measure = NULL,
  test = "z",
  ddf = NULL,
  study_col = NULL
)

Arguments

Details

The returned object is intended for analytical summaries and plotting functions that only consume the fitted model components. Workflows that require refitting a metafor model, such as leave_one_out() or bootstrap paths inside some heterogeneity helpers, are not supported for converted objects.

Value

A list of class c("rma.mv", "rma") containing the slots that orchaRd and metafor summary helpers expect.

i2_ml

Description

I2 (I-squared) for mulilevel meta-analytic models, based on Nakagawa & Santos (2012). Under multilevel models, we can have multiple I2 (see also Senior et al. 2016). Alternatively, the method proposed by Wolfgang Viechtbauer can also be used.

Usage

i2_ml(model, method = c("ratio", "matrix"), boot = NULL)

Arguments

Value

A data frame containing all the model results including mean effect size estimate, confidence, and prediction intervals

Author(s)

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

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

References

Senior, A. M., Grueber, C. E., Kamiya, T., Lagisz, M., O’Dwyer, K., Santos, E. S. A. & Nakagawa S. 2016. Heterogeneity in ecological and evolutionary meta-analyses: its magnitudes and implications. Ecology 97(12): 3293-3299. Nakagawa, S, and Santos, E.S.A. 2012. Methodological issues and advances in biological meta-analysis.Evolutionary Ecology 26(5): 1253-1274.

Examples

library(metafor)
# NOTE: boot is set LOW here for speed; use boot >= 1000 in practice.
data(english)
english <- escalc(measure = "SMD", n1i = NStartControl,
  sd1i = SD_C, m1i = MeanC, n2i = NStartExpt, sd2i = SD_E,
  m2i = MeanE, var.names = c("SMD", "vSMD"), data = english)
english_MA <- rma.mv(yi = SMD, V = vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID), data = english)
i2_ml(english_MA)
i2_ml(english_MA, method = "matrix")
i2_ml(english_MA, boot = 10)

Check if an Object is Categorical

Description

Determines whether the given object is categorical, defined as a character vector, a factor, or 'NULL'.

Usage

is_categorical(x)

Arguments

Value

A logical value: 'TRUE' if 'x' is a character vector, a factor, or 'NULL'; otherwise, 'FALSE'.

Leave-One-Out Analysis for Meta-Analytic Models

Description

Performs a leave-one-out analysis on a meta-analytic model from the **metafor** package by iteratively removing each level of a grouping variable and refitting the model.

Usage

leave_one_out(
  model,
  group,
  vcalc_args = NULL,
  robust_args = NULL,
  phylo_args = NULL
)

Arguments

Value

An object of class "orchard" containing:

• mod_table: A data frame with model estimates from each leave-one-out iteration, with an additional column indicating which group was omitted.

• data: A data frame with effect sizes from each iteration, with an additional column indicating which group was omitted.

• orig_mod_results: The results from the original model without any omissions, as returned by mod_results().

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Examples

# Subset to a few studies so the leave-one-out refits run quickly
fish_sub <- fish[fish$paper_ID %in% unique(fish$paper_ID)[1:5], ]
res <- metafor::rma.mv(lnrr, lnrr_vi, random = ~ 1 | paper_ID, data = fish_sub)
loo_results <- leave_one_out(res, group = "paper_ID")

# With robust variance estimation
loo_robust <- leave_one_out(res, group = "paper_ID",
                            robust_args = list(cluster = "paper_ID"))

lim

Description

Lim et al. (2014) meta-analysed the strength of correlation between maternal and offspring size within-species, across a very wide range of taxa. They found that typically there is a moderate positive correlation between maternal size and offspring size within species (i.e. larger mothers have larger offspring). Below we describe the variables use in our examples and analyses.

Format

A data frame :

Amniotes

Amniote group

Article

Study or research paper that data were collected from

Author

Authors of article

Class

Class of organism

Common.Name

Common name of species

Datapoint

Observation level ID that identified each unique datapoint

Environment

Environment organism is found, wild or captive

Family

Family of species

Genus

Genus of species

Maternal

Mother length, or mass

N

Sample size used to estaimted correlation

Offspring

Order

Order of species

Phylum

Phylum of the species

Propagule

RU

Reproduction

Reproductive mode of species

animal

Species name use for phylogenetic reconstruction

year

year of study

yi

Effect size correlation coefficient between maternal and offspring size within-species

...

References

Lim J.N., Senior A.M., Nakagawa S. 2014. Heterogeneity in individual quality and reproductive trade-offs within species. Evolution. 68(8):2306-18. doi: 10.1111/evo.12446

m1_ml

Description

M1 for mulilevel meta-analytic models, based on Yang et al. (2023). Under multilevel models, we can have multiple M1 - TODO - we need to cite original M1 paper

Usage

m1_ml(model, boot = NULL)

Arguments

Value

A data frame containing all the model results including mean effect size estimate, confidence, and prediction intervals

Author(s)

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

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

References

TODO

Examples

library(metafor)
# NOTE: boot is set LOW here for speed; use boot >= 1000 in practice.
data(english)
english <- escalc(measure = "SMD", n1i = NStartControl,
  sd1i = SD_C, m1i = MeanC, n2i = NStartExpt, sd2i = SD_E,
  m2i = MeanE, var.names = c("SMD", "vSMD"), data = english)
english_MA <- rma.mv(yi = SMD, V = vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID), data = english)
m1_ml(english_MA)
m1_ml(english_MA, boot = 10)

m2_ml

Description

M2 for mulilevel meta-analytic models, based on Yang et al. (2023). Under multilevel models, we can have multiple M2 - TODO - we need to cite original M2 paper

Usage

m2_ml(model, boot = NULL)

Arguments

Value

A data frame containing all the model results including mean effect size estimate, confidence, and prediction intervals

Author(s)

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

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

References

TODO

Examples

library(metafor)
# NOTE: boot is set LOW here for speed; use boot >= 1000 in practice.
data(english)
english <- escalc(measure = "SMD", n1i = NStartControl,
  sd1i = SD_C, m1i = MeanC, n2i = NStartExpt, sd2i = SD_E,
  m2i = MeanE, var.names = c("SMD", "vSMD"), data = english)
english_MA <- rma.mv(yi = SMD, V = vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID), data = english)
m2_ml(english_MA)
m2_ml(english_MA, boot = 10)

Magnitude Effects using SAFE Bootstrap

Description

Computes the magnitude effect size and its variance using the SAFE bootstrap method for either independent or dependent samples.

Usage

magnitude_effects(
  x1bar,
  x2bar,
  sd1,
  sd2,
  n1,
  n2,
  min_kept = 2000,
  chunk_init = 4000,
  chunk_max = 2e+06,
  max_draws = Inf,
  patience_noaccept = 5,
  paired = FALSE,
  r = NULL,
  seed = 565
)

Arguments

Value

A list containing the point estimate, variance, number of kept samples, total draws, number of attempts, and status.

Examples

# min_kept/chunk_init are set LOW here for speed; use the
# defaults for real analyses.
# Independent samples
magnitude_effects(x1bar = 10, x2bar = 7, sd1 = 2, sd2 = 3,
                  n1 = 30, n2 = 30, min_kept = 200, chunk_init = 400)
# Dependent (paired) samples, given the correlation between groups
magnitude_effects(x1bar = 10, x2bar = 7, sd1 = 2, sd2 = 3,
                  n1 = 30, n2 = 30, paired = TRUE, r = 0.5,
                  min_kept = 200, chunk_init = 400)

matrix_i2

Description

Calculated I2 (I-squared) for mulilevel meta-analytic models, based on a matrix method proposed by Wolfgang Viechtbauer.

Usage

matrix_i2(model)

Arguments

Value

A named numeric vector of I2 (I-squared) values expressed as percentages. The first element, I2_Total, is the total heterogeneity; each remaining element (named I2_<level> after a random-effect level of the model) is the heterogeneity attributable to that level.

Examples

library(metafor)
data(english)
english <- escalc(
  measure = "SMD", n1i = NStartControl,
  sd1i = SD_C, m1i = MeanC,
  n2i = NStartExpt, sd2i = SD_E, m2i = MeanE,
  var.names = c("SMD", "vSMD"), data = english)
english_MA <- rma.mv(
  yi = SMD, V = vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID),
  data = english)
matrix_i2(english_MA)

ml_cvh1

Description

Calculated CVH1 for mulilevel meta-analytic models

Usage

ml_cvh1(model)

Arguments

Value

A named numeric vector of CVH1 values (the coefficient of variation of the heterogeneity, on the standard-deviation scale). The first element, CVH1_Total, is the overall value across all random effects; each remaining element (named CVH1_<level> after a random-effect level of the model) is the value for that level.

ml_cvh2

Description

Calculated CVH2 for mulilevel meta-analytic models

Usage

ml_cvh2(model)

Arguments

Value

A named numeric vector of CVH2 values (the coefficient of variation of the heterogeneity, on the variance scale). The first element, CVH2_Total, is the overall value across all random effects; each remaining element (named CVH2_<level> after a random-effect level of the model) is the value for that level.

ml_m1

Description

Calculated M1 for mulilevel meta-analytic models

Usage

ml_m1(model)

Arguments

Value

A named numeric vector of M1 heterogeneity values (a proportion-type index on the standard-deviation scale, bounded between 0 and 1). The first element, M1_Total, is the overall value across all random effects; each remaining element (named M1_<level> after a random-effect level of the model) is the value for that level.

ml_m2

Description

Calculated CV for mulilevel meta-analytic models

Usage

ml_m2(model)

Arguments

Value

A named numeric vector of M2 heterogeneity values (a proportion-type index on the variance scale, bounded between 0 and 1). The first element, M2_Total, is the overall value across all random effects; each remaining element (named M2_<level> after a random-effect level of the model) is the value for that level.

Validate 'mod'

Description

Checks if 'mod' argument is valid. This argument must be either '"1"' (indicating an intercept-only model) or a moderator that is included in the meta-analytic model (as specified in 'model$formula.mods').

Usage

mod_is_valid(model, mod)

Arguments

Value

A logical value: TRUE if 'mod' is valid, strop and throw an error otherwise.

mod_results

Description

Using a metafor model object of class rma or rma.mv, this function creates a table of model results containing the mean effect size estimates for all levels of a given categorical moderator, and their corresponding confidence and prediction intervals. The function is capable of calculating marginal means from meta-regression models, including those with multiple moderator variables of mixed types (i.e. continuous and categorical variables).

Usage

mod_results(
  model,
  mod = "1",
  group,
  N = NULL,
  weights = "prop",
  by = NULL,
  at = NULL,
  subset = FALSE,
  upper = TRUE,
  ...
)

Arguments

Details

Prediction intervals with random-slope models (struct = "GEN" or "HCS"):

When your rma.mv model includes a random-slope term (e.g., random = ~ moderator | study with struct = "GEN" or "HCS"), prediction intervals require the full variance-covariance matrix of the random effects — not just the sum of the variance components. In a random-slope model the random intercept and slope are typically correlated, and a correct prediction interval at a given moderator value x must incorporate:

Var(u_{0j} + u_{1j} x) = \tau^2_0 + 2 x \rho \tau_0 \tau_1 + x^2 \tau^2_1

where \tau^2_0 and \tau^2_1 are the random intercept and slope variances, and \rho is their correlation. Simply summing tau2, gamma2, and sigma2 ignores the slope variance contribution and the covariance, producing intervals that may be too narrow or too wide depending on the moderator value.

metafor::predict.rma() does not currently return prediction intervals for models with GEN or HCS structures for this reason. orchaRd will issue a warning when it detects such a structure. Users should verify prediction intervals manually using the approach described by Pustejovsky (2024, R-sig-meta-analysis mailing list): https://stat.ethz.ch/pipermail/r-sig-meta-analysis/2024-March/005152.html.

A practical workaround is to re-centre the moderator at the value of interest (so the random slope term evaluates at zero) and then compare the resulting prediction interval with a manual calculation using the full variance-covariance matrix from the model.

Value

A data frame containing all the model results including mean effect size estimate, confidence and prediction intervals

Author(s)

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

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

Examples

# Simple eklof data
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, random=list(~1|ExptID,
~1|Datapoint), data = eklof)
results <- mod_results(eklof_MR, mod = "Grazer.type", group = "ExptID")

# Fish example demonstrating marginalised means
data(fish)
model <- metafor::rma.mv(yi = lnrr, V = lnrr_vi,
  random = list(~1 | group_ID, ~1 | es_ID),
  mods = ~ trait.type + deg_dif,
  method = "REML", test = "t", data = fish)
overall <- mod_results(model, group = "group_ID")
across_trait <- mod_results(model, group = "group_ID", mod = "trait.type")
# Marginalised means, conditioning on levels of a continuous moderator
across_trait_by_deg <- mod_results(model, group = "group_ID",
  mod = "trait.type", at = list(deg_dif = c(5, 10, 15)), by = "deg_dif")

Validate 'model'

Description

Checks if 'model' is a valid metafor model object. The model must be one of the following classes: 'robust.rma', 'rma.mv', 'rma', or 'rma.uni'.

Usage

model_is_valid(model)

Arguments

Value

Logical 'TRUE' if the 'model' argument is valid. If the model is missing or not of an accepted class, the function stops with an error message.

moment_effects

Description

Computes the effect estimate of the difference in skewness and kurtosis between two groups along with associated sampling variance for meta-analysis.

Usage

moment_effects(x1, x2, type = c("skew", "kurt"))

Arguments

Value

A data frame with the difference in moment effects and their variances.

Examples

set.seed(982)

# Just some random comparisons
moment_effects(rnorm(100), rnorm(100), type = "skew")
moment_effects(rnorm(40), rnorm(40), type = "skew")
moment_effects(rnorm(40), rnorm(40), type = "kurt")
moment_effects(rnorm(100), rnorm(100), type = "kurt")

# Comparisons with known moment differences
m1 <- c(mean = 0, variance = 1, skewness = 0, kurtosis = 2)
m2 <- c(mean = 0, variance = 1, skewness = 0, kurtosis = 4)

x1 <- PearsonDS::rpearson(1000, moments = m1)
x2 <- PearsonDS::rpearson(1000, moments = m2)
moment_effects(x1, x2, type = "skew") # ~0
moment_effects(x1, x2, type = "kurt") # ~-2

m1 <- c(mean = 0, variance = 1, skewness = 0, kurtosis = 3)
m2 <- c(mean = 0, variance = 1, skewness = 1, kurtosis = 3)
x1 <- PearsonDS::rpearson(1000, moments = m1)
x2 <- PearsonDS::rpearson(1000, moments = m2)
moment_effects(x1, x2, type = "skew") # ~-1
moment_effects(x1, x2, type = "kurt") # ~0

num_studies

Description

Computes how many studies are in each level of categorical moderators of a rma.mv model object.

Usage

num_studies(data, mod, group)

Arguments

Value

Returns a table with the number of studies in each level of all parameters within a rma.mv or rma object.

Author(s)

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

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

Examples

data(fish)
warm_dat <- fish
model <- metafor::rma.mv(
  yi = lnrr, V = lnrr_vi,
  random = list(~1 | es_ID, ~1 | group_ID),
  mods = ~ experimental_design - 1,
  method = "REML", test = "t", data = warm_dat,
  control = list(optimizer = "optim",
    optmethod = "Nelder-Mead"))
res <- mod_results(model, mod = "experimental_design", group = "group_ID")
num_studies(res$data, moderator, stdy)

Orchard Plot for Leave-One-Out Analysis

Description

Plots the output of a leave-one-out analysis for a meta-analytic model. The plot displays the effect sizes, overall effect estimate (with confidence and prediction intervals), and optionally, the effect sizes left out ("ghost points") in each iteration. In addition, the original model's 95% confidence limits are shown as reference lines.

Usage

orchard_leave1out(
  leave1out,
  ylab = NULL,
  ci_lines = TRUE,
  ci_lines_color = "red",
  ghost_points = TRUE,
  angle = 0,
  g = FALSE,
  transfm = c("none", "tanh", "invlogit", "percent", "percentr"),
  ...
)

Arguments

Details

This function is useful to see how sensitive is the overall effect size estimated by a meta-analytic model to exclusion of each element from a group.

The y-axis shows the elements from the group. For each one, the plot shows the result from the model that left-out that element. For each model, the plot shows the effect sizes, overall effect estimate with confidence and prediction intervals, and "ghost points". This "ghost points" are the effect sizes left out and they are shown as empty points. They can be ommited setting 'ghost_points' to FALSE.

The plot also shows 95 as red dotted lines. The arguments 'ci_lines' and 'ci_lines_color' allow to remove this lines or select their color.

The function internally sets a color palette for the plot. If more than 20 elements are in the group, a viridis palette is used. Otherwise, a color-blind friendly palette is applied by default.

Value

A ggplot2 object displaying the leave-one-out analysis with reference lines for the original model's confidence limits.

Author(s)

Facundo Decunta - fdecunta@agro.uba.ar

Examples

  # Subset to a few studies so the leave-one-out refits run quickly
  fish_sub <- fish[fish$paper_ID %in% unique(fish$paper_ID)[1:5], ]
  res <- metafor::rma.mv(lnrr, lnrr_vi, random = ~ 1 | paper_ID, data = fish_sub)
  loo_res <- orchaRd::leave_one_out(res, group = "paper_ID")
  orchard_leave1out(leave1out = loo_res, xlab = "lnRR")

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
)

Arguments

Value

Orchard plot

Author(s)

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

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

Examples

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")

phylo_matrix

Description

Phylogenetic matrix used in Pottier et al. (2021) meta-analysis on sex-differences in acclimation

Format

A phylogenetic correlation matrix :

References

Pottier et al. 2022. Functional Ecology

pottier

Description

Pottier et al. (2021) meta-analysis on sex-differences in acclimation

Format

A data frame :

initials

es_ID

study_ID

species_ID

population_ID

family_ID

shared_trt_ID

cohort_ID

note_ID

data_source

data_url

fig_file_name

data_type

data_file_name

peer.reviewed

ref

title

pub_year

journal

thesis_chapter

doi

citation

phylum

class

order

family

genus

species

genus_species

habitat

taxonomic_group

reproduction_mode

life_stage_manip

life_stage_tested

brought_common_temp

mobility_life_stage_manip

time_common_temp

common_temp

exp_design

origin_hatching

latitude

longitude

elevation

season

year

body_length

body_mass

age_tested

sex

housing_temp

incubation_independent

metric

endpoint

acc_temp_low

acc_temp_high

acc_temp_var

is_acc_temp_fluctuating

acc_duration

ramping

set_time

n_test_temp

n_replicates_per_temp

n_animals_per_replicate

humidity

oxygen

salinity

pH

photoperiod

gravidity

starved

minor_concerns

major_concerns

notes_moderators

mean_HT_low

sd_HT_low

n_HT_low

mean_HT_high

sd_HT_high

n_HT_high

error_type

notes_es

exclude

n_trt

n_cohort

within_study_mean_low

within_study_mean_high

within_study_sd_low

within_study_sd_high

between_study_mean_low

between_study_mean_high

between_study_sd_low

between_study_sd_high

imputed

imputed_sd_low

imputed_sd_high

dARR

Var_dARR

precision

is_concern

search_string

unique_name

ott_id

phylogeny

...

References

Pottier et al. 2022. Functional Ecology

pred_interval_esmeans

Description

Function to get prediction intervals (credibility intervals) from esmeans objects (metafor).

Usage

pred_interval_esmeans(model, mm, mod, ...)

Arguments

Value

A data frame built from summary() of the emmeans object: one row per level of the moderator giving the estimated marginal mean and its confidence limits, plus two added columns, lower.PI and upper.PI, containing the lower and upper bounds of the prediction (credibility) interval.

Author(s)

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

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

print.orchard

Description

Print method for class 'orchard'

Usage

## S3 method for class 'orchard'
print(x, ...)

Arguments

Value

Returns a data frame

Author(s)

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

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

pub_bias_plot

Description

This function adds the bias corrected mean and confidence intervals to an existing orchard plot that displays the overall meta-analytic mean effect size.

Usage

pub_bias_plot(
  plot,
  fe_model,
  v_model = NULL,
  col = c("red", "blue"),
  plotadj = -0.05,
  textadj = 0.05,
  branch.size = 1.2,
  trunk.size = 3
)

Arguments

Value

An orchard plot with the corrected meta-analytic mean and confidence intervals added.

Author(s)

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

Examples

library(metafor)
# Data
data(english)
# We need to calculate the effect sizes, in this case d
english <- escalc(
  measure = "SMD",
  n1i = NStartControl, sd1i = SD_C, m1i = MeanC,
  n2i = NStartExpt, sd2i = SD_E, m2i = MeanE,
  var.names = c("SMD", "vSMD"),
  data = english)

# Our MLMA model
english_MA1 <- rma.mv(
  yi = SMD, V = vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID),
  test = "t", data = english)

# Step 1: Fit the fixed effect model
english_MA2 <- rma.mv(
  yi = SMD, V = vSMD, data = english, test = "t")

english_MA3 <- rma(
  yi = SMD, vi = vSMD, data = english,
  test = "t", method = "FE")

# Step 2: Correct for dependency
english_MA2_1 <- robust(
  english_MA2, cluster = english$StudyNo)

# Step 3: Testing modified eggers
english_MA4 <- rma.mv(
  yi = SMD, V = vSMD, mod = ~vSMD,
  random = list(~1 | StudyNo, ~1 | EffectID),
  test = "t", data = english)

# Now plot the results
plot <- orchard_plot(
  english_MA1, group = "StudyNo",
  xlab = "Standardized Mean Difference")
plot2 <- pub_bias_plot(plot, english_MA2_1)
plot3 <- pub_bias_plot(
  plot, english_MA2_1, english_MA4)

r2_ml

Description

R2 (R-squared) for mixed (mulitlevel) models, based on Nakagawa & Schielzeth (2013).

Usage

r2_ml(model, data, boot = NULL)

Arguments

Value

A data frame containing all model results, including: mean effect size estimate, confidence and prediction intervals, with estimates converted back to r.

Author(s)

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

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

References

Nakagawa, S, and Schielzeth, H. 2013. A general and simple method for obtaining R2 from generalized linear mixed‐effects models. *Methods in Ecology and Evolution* 4(2): 133-142.

Examples

data(lim)
lim$vi <- (1/sqrt(lim$N - 3))^2
lim_MR <- metafor::rma.mv(
  yi = yi, V = vi, mods = ~ Phylum - 1,
  random = list(~1 | Article, ~1 | Datapoint),
  data = lim)
R2 <- r2_ml(lim_MR, data = lim)

ratio_i2

Description

I2 (I-squared) for mulilevel meta-analytic models based on Nakagawa & Santos (2012). Under multilevel models, we can have a multiple I2 (see also Senior et al. 2016).

Usage

ratio_i2(model)

Arguments

Value

A named numeric vector of I2 (I-squared) values expressed as percentages. The first element, I2_Total, is the total heterogeneity; each remaining element (named I2_<level> after a random-effect level of the model) is the heterogeneity attributable to that level.

Examples

library(metafor)
data(english)
english <- escalc(measure = "SMD", n1i = NStartControl,
sd1i = SD_C, m1i = MeanC, n2i = NStartExpt,
sd2i = SD_E, m2i = MeanE, var.names=c("SMD","vSMD"),data = english)
english_MA <- rma.mv(yi = SMD, V = vSMD,
random = list( ~ 1 | StudyNo, ~ 1 | EffectID), data = english)
ratio_i2(english_MA)

submerge

Description

Merge two model results tables (orchard objects).

Usage

submerge(object1, object2, ..., mix = FALSE)

Arguments

Value

Returns a data frame.

Author(s)

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

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

Freeman-Tukey (Double Arcsine) Transformation for proportions

Description

Freeman-Tukey (Double Arcsine) Transformation for proportions

Usage

transf_ift(x, n)

Arguments

Value

Back transformed proportion.

Inverse Freeman-Tukey (Double Arcsine) Transformation for proportions

Description

Inverse Freeman-Tukey (Double Arcsine) Transformation for proportions

Usage

transf_inv_ft(x, n)

Arguments

Value

Back transformed proportion.

Inverse Logit Transformation

Description

Inverse Logit Transformation

Usage

transf_invlogit(x)

Arguments

Value

The inverse logit of x, computed as exp(x) / (1 + exp(x)).

Percentage Transformation

Description

Percentage Transformation

Usage

transf_percent(x)

Arguments

Value

The percentage transformation, computed as exp(x) * 100.

Percentage Relative Change Transformation

Description

Percentage Relative Change Transformation

Usage

transf_percentr(x)

Arguments

Value

The percentage relative change transformation, computed as (exp(x) - 1) * 100.

Hyperbolic Tangent Transformation

Description

Hyperbolic Tangent Transformation

Usage

transf_tanh(x)

Arguments

Value

The hyperbolic tangent of x.

Apply a Transformation to Vector

Description

This function applies a specified transformation to a numeric vector.

Usage

transform_data(
  x,
  n = NULL,
  transfm = c("none", "tanh", "invlogit", "percentr", "percent", "inv_ft")
)

Arguments

Value

A numeric vector with the applied transformation.

Transform effect sizes in an orchard object

Description

Applies a transformation to the effect sizes and their confidence/prediction intervals from a model result object returned by mod_results.

Usage

transform_mod_results(results, transfm, n_transfm)

Arguments

Value

A modified list object of class orchard, where the effect size estimates and their intervals in both mod_table and data are transformed accordingly.

weighted_var

Description

Calculate weighted variance

Usage

weighted_var(x, weights)

Arguments

Value

Returns a vector with a single weighted variance

Author(s)

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

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