umbrella: Conduct the calculations for an umbrella review

Description Usage Arguments Details Value References See Also Examples


This function performs various calculations needed for an umbrella review.


  method.var = "REML",
  mult.level = FALSE,
  r = 0.5,
  true_effect = "largest",
  seed = NA,
  verbose = TRUE



a well-formatted dataset.


the estimator used to quantify the between-study variance in the random-effects meta-analysis. Default is the Restricted Likelihood Maximum ("REML") estimator. Alternatively, DerSimonian and Laird "DL", Hartung-Knapp-Sidik-Jonkman "hksj" (applies a Hartung-Knapp-Sidik-Jonkman adjustment on the results of a "DL" estimator), maximum-likelihood "ML" or Paule-Mandel "PM" estimators can be used.


a logical variable indicating the presence of multiple effect sizes per study in at least one factor of the umbrella review. Default is FALSE (i.e., each study of all factors include only one effect size). If mult.level = TRUE is specified, the Borenstein's methods are used to generate only one effect size per study. See metaumbrella-package for more information.


a correlation coefficient indicating the strength of the association between multiple outcomes (or time-points) within the same study. The r value is applied to all studies with a "outcomes" value in the reverse_es column that have no indication of correlation in the well-formatted dataset. Default is 0.5.


the method to estimate the true effect in the test for excess of significance. It must be "largest", "pooled" or a numeric value (see details). Default is "largest".


an integer value used as an argument by the set.seed() function. Only used for the Ioannidis' test for excess of significance with ratios (i.e., “OR”, “RR”, “IRR” or their logarithm) as effect size measures.


a logical variable indicating whether text outputs and messages should be generated. We recommend turning this option to FALSE only after having carefully read all the generated messages.


This function automatically performs calculations allowing to stratify evidence according to various criteria. For each factor included in a well-formatted dataset, this function automatically:

A specificity of this function is that it does not include arguments to specify the name of the columns of the dataset used as input. Instead, the function requires users to build a dataset that meets fixed rules. Details on how building this well-formatted dataset are given in the metaumbrella-package section of this manual and a vignette is specifically dedicated to this topic. Moreover, examples of well-formatted datasets are available as data distributed along with the package (see df.OR, df.OR.multi, df.SMD, df.RR, df.HR, df.IRR).

When estimating the test for excess of significance, the umbrella() function must assume a best approximation of the true effect. The true_effect argument can be used to select the method that will be applied to estimate this approximation of the true effect.


The umbrella() function returns an object of class “umbrella”, which is a list containing information required for stratifying the evidence. This list contains, for each factor included in the umbrella review:

measure the measure of the effect used to perform the calculations.
x the data used to conduct the meta-analysis. Note that these data may be
slightly different from the raw data introduced.
x_multi the original data when there is a multivariate structure.
Note that these data may be slightly different from the raw data introduced.
x_shared a dataframe allowing to visualize adjustments made when a shared_nexp
or shared_controls correction is requested
(see metaumbrella-package for more information).
n the overall number of studies, cases and controls.
method.var the estimator used for fitting the random effects meta-analyses
random pooled effect size, p-value and 95% confidence interval and prediction
interval of the random-effects meta-analysis.
fixed pooled effect size, p-value and 95% confidence interval and prediction
interval of the fixed-effect meta-analysis.
largest 95% confidence interval of the largest study.
heterogeneity tau^2, I^2 and Q test.
egger estimate and p-value of the Egger's test for publication bias.
esb results of the Ioannidis' test for excess of significance bias. See
esb.test() for more information.
riskofbias percentage of participants in studies at low risk of bias.
amstar AMSTAR score obtained by the meta-analysis.
evidence evidence class according to some criteria.

The functions print and summary may be used to print the details or a summary of the results.


Fusar-Poli, P., Radua, J. (2018). Ten simple rules for conducting umbrella reviews. Evidence-Based Mental Health, 21, 95–100.
Radua, J., Ramella-Cravaro, V., Ioannidis, J.P.A., Reichenberg, A., Phiphopthatsanee, N., Amir, T., Yenn Thoo, H., Oliver, D., Davies, C., Morgan, C., McGuire, P., Murray, R.M., Fusar-Poli, P. (2018) What causes psychosis? An umbrella review of risk and protective factors. World Psychiatry, 17, 49–66.

See Also

metaumbrella-package for the formatting of well-formatted datasets
add.evidence() for stratifying the evidence in an umbrella review
forest() for drawing a forest plot of the factors included in an umbrella review
subset.umbrella() for retrieving a subset of the factors included in an umbrella review
union.umbrella() for combining the factors included in two umbrella reviews


### Perform an umbrella review with random-effects meta-analyses
### with a Hartung-Knapp-Sidik-Jonkman estimator
umb <- umbrella(df.IRR, method.var = "hksj")

### obtain the results of the calculations in a dataframe

### manually inspect the results of the umbrella review calculations for the 'Smoking' factor
### included in the dataset.

### Perform a meta-analysis with multilevel data, assuming a correlation of 0.8
### between all outcomes of the same study
umb.multi <- umbrella(df.OR.multi, mult.level = TRUE, r = 0.8)

### obtain a stratification of the evidence according to the Ioannidis classification
add.evidence(umb.multi, criteria = "Ioannidis")

metaumbrella documentation built on Jan. 7, 2022, 5:08 p.m.