{smcl}
{* 8aug2008, Ian White}
{hline}
help for {hi:mvmeta}{right:Ian White}
{hline}

{title:Multivariate random-effects meta-analysis}


{title:Description}

{p 4 4 2}
{cmd:mvmeta} performs multivariate random-effects meta-analysis on a data-set of point estimates, variances and (optionally) covariances.


{title:Syntax}

{p 8 17 2}
{cmd:mvmeta} b V
{ifin}
[{cmd:,} 
{cmd:reml|ml|mm|fixed}
{cmdab:v:ars(}{it:varlist}{cmd:)}
{cmd:corr(}{it:expression}{cmd:)}
{cmd:start(}{it:expression}{cmd:)}
{cmdab:shows:tart}
{cmdab:showc:hol}
{cmdab:keep:mat(}{it:bname Vname}{cmd:)}
{* cmdab:tr:ace}
{* cmdab:rep:ort}
{cmdab:nounc:ertainv}
{cmd:eform(}{it:name}{cmd:)}
{cmd:bscorr}
{cmd:bscov}
{cmd:missest(#)}
{cmd:missvar(#)}
{it:maximize_options}
]

{p 4 4 2}
where the data are arranged with one line per study: the point estimates are held in variables b*, the variance of bx is held in variable Vxx, and the covariance of bx and by is held in variable Vxy. 
If you have individual participant data, you can use {helpb mvmeta_make} to produce a datset of the required format.


{title:Options}

{phang}
{cmd:reml} specifies that restricted maximum likelihood is to be used for estimation (the default).

{phang}
{cmd:ml} specifies that maximum likelihood is to be used for estimation.
This is likely to underestimate the variance, so restricted maximum likelihood is usually preferred.

{phang}
{cmd:mm} specifies that the multivariate method of moments procedure (Jackson et al, Biostatistics, submitted) is to be used for estimation. This is a multivariate generalisation of the procedure of DerSimonian and Laird (1986) and is faster than the likelihood-based methods.

{phang}
{cmd:fixed} specifies that the fixed-effect model is to be used for estimation.

{phang}
{cmd:vars(}{it:varlist}{cmd:)} specifies which variables are to be used. By default, all variables named b* are used, but any variable named b is ignored.
Note that {cmd:vars(}b1 b2 b3{cmd:)} and {cmd:vars(}b3 b2 b1{cmd:)} specify the same model but a different parameterisation.

{phang}
{cmd:corr(}{it:expression}{cmd:)} specifies the value of all within-study correlations. This means that covariance variables {it:V}xy need not exist. (For any that do exist, {cmd:corr()} is ignored.)

{phang}
{cmd:start(}{it:matrix}|{it:matrix expression}|{cmd:mm}{cmd:)} specifies a starting value for the between-studies variance, except that 
{cmd:start(}{cmd:mm}{cmd:)} specifies that the starting value is computed by the {cmd:mm} method. 
If {cmd:start()} is not specified, the starting value is the weighted between-study variance of the estimates, not allowing for the within-study variances. 
This ensures it is greater than zero: the iterative procedure never moves away from zero. {cmd:start(0)} uses a starting value of 0.001 times the default. 
The starting value for the between-studies mean is the fixed effects estimate.

{phang}
{cmd:showstart} reports the starting values used.

{phang}
{cmd:showchol} reports the estimated values of the basic parameters underlying the between-studies 
variance matrix (the Cholesky decomposition).

{phang}
{cmd:keepmat(}{it:bname Vname}{cmd:)} saves the study-specific estimates and variance matrices for study i 
as {it:bname}i and {it:Vname}i.
{* {cmd:trace} sets {cmd:ml}'s {cmd:trace} option.}
{* {cmd:report} calls {cmd:ml report} before starting maximisation.}

{phang}
{cmd:nouncertainv} also computes alternative (smaller) standard errors that ignore
the uncertainty in the estimated variance-covariance matrix, and therefore
agree with results produced by procedures such as SAS PROC MIXED (without the
ddfm=kr option) and {helpb metareg}. (Note however that confidence intervals do not
agree because {cmd:mvmeta} uses a Normal approximation whereas the other procedures
approximate the degrees of freedom of a t distribution.)

{phang}
{cmd:eform(}{it:name}{cmd:)} exponentiates the reported mean parameters and reports them as {it:name}.

{phang}
{cmd:bscorr} reports the between-studies variance-covariance matrix as the standard deviations and correlation matrix.
This is the default if {cmd:bscov} is not specified.

{phang}
{cmd:bscov} reports the between-studies variance-covariance matrix without transformation.

{phang}
{cmd:missest(#)} specifies values to be used for missing point estimates; the default is 0. 
This is of minor importance because the variance of these values is specified to be very large.

{phang}
{cmd:missvar(#)} is used in specifying the very large variance of missing point estimates. 
For a specific variable, the variance used is the largest observed variance multiplied by the specified value. The default is 1E4. This value is unlikely to need to be changed.

{phang}
{it:maximize_options} are any options allowed by {cmd:ml maximize}: see {helpb ml}.



{title:Studies in which some quantities are unestimated}

{p 0 0 0}
{cmd:mvmeta} handles studies in which some quantities are missing by replacing the point estimate by an arbitrary value and the estimated variance by a large value. 
{cmd:mvmeta} ignores variances and covariances specified for missing point estimates. 
Conversely, it expects non-missing variances and covariances to accompany non-missing point estimates.
{helpb mvmeta_make} automatically fills in missing values using the augmentation algorithm described above. 
In either case, the particular choice of large value should have minimal effect on the parameter estimates, but will affect the value of the maximised log-likelihod.


{title:Examples}

First stage, starting with individual participant data ({cmd:fg} has levels 1-5):

{phang}{cmd:. xi: mvmeta_make stcox ages i.fg, strata(sex tr) nohr saving(FSCstage1) replace by(cohort) usevars(i.fg) names(b V) esave(N)}

Second stage:

{phang}{cmd:. use FSCstage1, clear}

{phang}{cmd:. mvmeta b V}


{title:Details}

{p 0 0 0}
The reml and ml methods use Newton-Raphson maximisation of the likelihood or restricted likelihood using 
{helpb ml}. The between-studies variance matrix is parameterised via its Cholesky decomposition in 
order to ensure that it is non-negative definite.

{p 0 0 0}
{cmd:mvmeta} requires the additional program mvmeta_l.ado.


{title:See also}

{helpb mvmeta_make}, {helpb metan}, {helpb metareg}.
