Simulate Method for 'rma' Objects

Function to simulate effect sizes or outcomes based on "rma" model objects.

# S3 method for class 'rma'
simulate(object, nsim=1, seed=NULL, olim, ...)

Arguments

object: an object of class "rma".
nsim: number of response vectors to simulate (defaults to 1).
seed: an object to specify if and how the random number generator should be initialized (‘seeded’). Either NULL or an integer that will be used in a call to set.seed before simulating the response vectors. If set, the value is saved as the "seed" attribute of the returned value. The default, NULL will not change the random generator state, and return .Random.seed as the "seed" attribute; see ‘Value’.
olim: argument to specify observation/outcome limits for the simulated values. If unspecified, no limits are used.
...: other arguments.

Details

The model specified via object must be a model fitted with either the rma.uni or rma.mv functions.

Value

A data frame with nsim columns with the simulated effect sizes or outcomes.

The data frame comes with an attribute "seed". If argument seed is NULL, the attribute is the value of .Random.seed before the simulation was started; otherwise it is the value of the seed argument with a "kind" attribute with value as.list(RNGkind()).

Note

If the outcome measure used for the analysis is bounded (e.g., correlations are bounded between -1 and +1, proportions are bounded between 0 and 1), one can use the olim argument to enforce those observation/outcome limits when simulating values (simulated values cannot exceed those bounds then).

Author

Wolfgang Viechtbauer (wvb@metafor-project.org, https://www.metafor-project.org).

References

Viechtbauer, W. (2010). Conducting meta-analyses in R with the metafor package. Journal of Statistical Software, 36(3), 1–48. https://doi.org/10.18637/jss.v036.i03

Examples

### copy BCG vaccine data into 'dat'
dat <- dat.bcg

### calculate log risk ratios and corresponding sampling variances
dat <- escalc(measure="RR", ai=tpos, bi=tneg, ci=cpos, di=cneg, data=dat)
dat
#> 
#>    trial               author year tpos  tneg cpos  cneg ablat      alloc      yi     vi 
#> 1      1              Aronson 1948    4   119   11   128    44     random -0.8893 0.3256 
#> 2      2     Ferguson & Simes 1949    6   300   29   274    55     random -1.5854 0.1946 
#> 3      3      Rosenthal et al 1960    3   228   11   209    42     random -1.3481 0.4154 
#> 4      4    Hart & Sutherland 1977   62 13536  248 12619    52     random -1.4416 0.0200 
#> 5      5 Frimodt-Moller et al 1973   33  5036   47  5761    13  alternate -0.2175 0.0512 
#> 6      6      Stein & Aronson 1953  180  1361  372  1079    44  alternate -0.7861 0.0069 
#> 7      7     Vandiviere et al 1973    8  2537   10   619    19     random -1.6209 0.2230 
#> 8      8           TPT Madras 1980  505 87886  499 87892    13     random  0.0120 0.0040 
#> 9      9     Coetzee & Berjak 1968   29  7470   45  7232    27     random -0.4694 0.0564 
#> 10    10      Rosenthal et al 1961   17  1699   65  1600    42 systematic -1.3713 0.0730 
#> 11    11       Comstock et al 1974  186 50448  141 27197    18 systematic -0.3394 0.0124 
#> 12    12   Comstock & Webster 1969    5  2493    3  2338    33 systematic  0.4459 0.5325 
#> 13    13       Comstock et al 1976   27 16886   29 17825    33 systematic -0.0173 0.0714 
#> 

### fit random-effects model
res <- rma(yi, vi, data=dat)
res
#> 
#> Random-Effects Model (k = 13; tau^2 estimator: REML)
#> 
#> tau^2 (estimated amount of total heterogeneity): 0.3132 (SE = 0.1664)
#> tau (square root of estimated tau^2 value):      0.5597
#> I^2 (total heterogeneity / total variability):   92.22%
#> H^2 (total variability / sampling variability):  12.86
#> 
#> Test for Heterogeneity:
#> Q(df = 12) = 152.2330, p-val < .0001
#> 
#> Model Results:
#> 
#> estimate      se     zval    pval    ci.lb    ci.ub      
#>  -0.7145  0.1798  -3.9744  <.0001  -1.0669  -0.3622  *** 
#> 
#> ---
#> Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
#> 

### simulate 5 sets of new outcomes based on the fitted model
newdat <- simulate(res, nsim=5, seed=1234)
newdat
#>         sim_1       sim_2       sim_3      sim_4      sim_5
#> 1  -1.6793004 -0.66301253 -0.25514894 -1.0869090 -1.6008315
#> 2  -0.5168313 -0.03077959 -1.44400787  0.3184048 -1.4378126
#> 3   0.2111329 -0.80867065 -0.72745421 -1.6267122 -0.8530777
#> 4  -2.0686591 -1.00952843 -1.25483770 -1.2083181 -0.3894909
#> 5  -0.4554698 -1.26462088 -0.04907549 -0.8839444  0.2802548
#> 6  -0.4281973 -1.18821837 -0.98363103 -1.2771469 -1.1521089
#> 7  -1.1354134  1.05457927 -1.23405397 -1.4237736  0.4614723
#> 8  -1.0224006 -0.63901259 -0.99684563 -1.3381844 -1.3666211
#> 9  -1.0577254 -1.01287484 -1.70503931 -1.4757537 -0.3153193
#> 10 -1.2676951 -0.98833493 -1.44021323 -1.0400940  0.8696776
#> 11 -0.9868483 -0.45226195 -1.95859894 -0.9980659 -0.7343688
#> 12 -1.6326947 -1.35250955 -1.94777167 -2.3754422 -1.3303583
#> 13 -1.1959650 -1.61270897 -0.89705339 -1.0755358 -0.7192488