mvmeta (version 1.0.3)

mvmetaSim: Simulating Responses for mvmeta Models

Description

These functions simulate sets of multivariate or univariate responses for a group of studies, in terms of their mean (expected) values and within and between-study (co)variances. These sets of outcomes can be used in meta-analytical models for simulation purposes.

Usage

mvmetaSim(y, S, Psi, sd, cor, nsim=1, seed=NULL, posdeftol)
# S3 method for mvmeta
simulate(object, nsim=1, seed=NULL, …)

Arguments

y

a $m$-dimensional vector (for simulating univariate responses) or $m\times k$ matrix (for simulating multivariate responses) of mean (expected) outcomes.

S

series of within-study (co)variance matrices of the outcomes for each one of the $m$ studies. Accepted formats are a $m$-dimensional list of $k\times k$ matrices; a tri-dimensional $k\times k\times m$ array; or a $m\times k(k+1)/2$ matrix or data frame where each row represents the vectorized entries of the lower triangle of the related (co)variance matrix, taken by column (see xpndMat).

Psi

the between-study (co)variance matrices of the outcomes. Accepted formats are a $k\times k$ matrix or a $k(k+1)/2$-dimensional vector, representing the vectorized entries of the lower triangle of the related (co)variance matrix, taken by column (see xpndMat).

sd

a $k$-dimensional vector of between-study standard deviations.

cor

between-study correlations. Either a scalar, a vector or a matrix. See inputcov.

nsim

number of simulation sets.

seed

an object specifying if and how the random number generator should be initialized.

posdeftol

tolerance (relative to largest variance) for numerical lack of positive-definiteness. Default to the square root of the machine precision.

object

an object of class "mvmeta".

…

further arguments passed to or from other methods.

Value

If nsim=1, a matrix or vector of simulated $k$ outcomes for the $m$ studies. If more simulation sets are required (nsim higher than 1), a list of matrices or vectors.

Details

The set(s) of responses can be simulated either from a fitted model, using the method function simulate for objects of class "mvmeta", or directly through the function mvmetaSim. In the former case, the fitted values from the model are used as mean (expected) outcomes, together with the within and estimated between-study (co)variance. In the latter option, this information need to be provided by the user in the correct dimensions and forms.

In mvmetaSim, the between-study (co)variance matrix can be inputted directly through Psi, or given in the form $\mathit{D}\mathit{R}\mathit{D}$, with a diagonal matrix $\mathit{D}$ of standard deviations and correlation matrix $\mathit{R}$. These values are provided through sd and cor. See inputcov for details.

The functions simulate the responses for each study separately from a marginal multivariate normal distribution with mean equal to the expected values and (co)variance equal to the sum of the within and between-study components. The computation is identical to that implemented in the function mvrnorm of the package MASS, involving a eigen decomposition of the marginal (co)variance matrix. Numerical negative definiteness is allowed with a tolerance specified by posdeftol, and positive semi-definiteness is then forced by truncating the eigenvalues at zero.

References

Sera F, Armstrong B, Blangiardo M, Gasparrini A (2019). An extended mixed-effects framework for meta-analysis.Statistics in Medicine. 2019;38(29):5429-5444. [Freely available here].

See Also

See simulate for the general method function. See inputcov for inputting correlations. See mvmeta-package for an overview of the package and modelling framework.

Examples

# NOT RUN {
# RUN A MODEL
model <- mvmeta(cbind(PD,AL)~pubyear,S=berkey98[5:7],data=berkey98)

# SIMULATE A NEW SET OF OUTCOMES
simulate(model)

# SIMULATE FROM SCRATCH: 3 OUTCOMES, 8 STUDIES
(y <- matrix(0,8,3))
(S <- inputcov(matrix(runif(8*3,0.1,2),8,3,dimnames=list(NULL,
  c("V1","V2","V3"))),cor=c(0,0.5,0.7)))
(Psi <- inputcov(1:3,cor=0.3))
mvmetaSim(y,S,Psi)

# ALTERNATIVELY, DEFINE Psi THROUGH STANDARD DEVIATIONS AND CORRELATION 0.2
mvmetaSim(y,S,sd=1:3,cor=0.3)

# 2 SIMULATION SETS
mvmetaSim(y,S,Psi,nsim=2)
# }