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

{title:Prepare data for multivariate meta-analysis}


{title:Description}

{p 4 4 2}
{cmd:mvmeta_make} is a utility to produce data in the correct format for
{helpb mvmeta}.


{title:Syntax}

{p 8 17 2}
{cmd:mvmeta_make}
{it:regression_command}
{ifin}
{weight}
{cmd:,}
{cmd:by(}{it:by_variable}{cmd:)}
{cmdab:sav:ing(}{it:savefile}{cmd:)}
[{cmd:replace}
{cmd:append}
{cmdab:name:s(}{it:bname Vname}{cmd:)}
{cmd:keepmat}
{cmdab:usev:ars(}{it:string}{cmd:)}
{cmdab:usec:onstant}
{cmd:esave(}{it:namelist}{cmd:)}
{cmdab:nodet:ails}
{cmd:pause}
{cmdab:ppf:ix(none|check|all)}
{cmdab:aug:wt(#)}
{cmdab:noaugl:ist}
{cmdab:ppc:md(}{it:regcmd}[{it:,options}]{cmd:)}
{cmd:hard}
{it:regression_options}]

{p 4 4 2}
This command performs {it:regression-command} for each level of {it:by_variable} and stores the results in {it:savefile} in the format required by {helpb mvmeta}.


{title:Options}

{phang}
{cmd:by(}{it:by_variable}{cmd:)} is compulsory: it identifies the studies, in each of which the regression
command will be performed.

{phang}
{cmd:saving(}{it:savefile}{cmd:)} is compulsory: the regression results are saved to this file.

{phang}
{cmd:replace} specifies that {it:savefile} may already exist.

{phang}
{cmd:append} specifies that {it:savefile} already exists and the results should be
appended to it.

{phang}
{cmd:names(}{it:bname Vname}{cmd:)} specifies that estimated coefficients for variable x are to
be stored in variable {it:bname}x, and the estimated covariance between coefficients {it:bname}y
and {it:bname}y is to be stored in variable {it:Vname}xy. Defaults are y and S.

{phang}
{cmd:keepmat} specifies that the results are also to be stored as matrices. The estimate
vector and covariance matrix for study i are stored as matrices {it:bname}i and {it:Vname}i
respectively, where {it:bname} and {it:Vname} are the names specified by {cmd:names}.

{phang}
{cmd:usevars(}{it:varlist}{cmd:)} identifies the variables whose regression coefficients are of
interest. The default is all variables in the model, excluding the constant.

{phang}
{cmd:useconstant} specifies that the constant is also of interest.

{phang}
{cmd:esave(}{it:namelist}{cmd:)} adds the specified e() statistics to the saved data.
For example, {cmd:esave(}N ll{cmd:)} saves e(N) and e(ll) as variables _e_N and _e_ll.

{phang}
{cmd:nodetails} suppresses the results of running {it:regression_command} on each study.

{phang}
{cmd:pause} pauses output after the analysis of each study, provided that {cmd:pause on} has been set.

{phang}
{cmd:ppfix(none|check|all)} specifies whether perfect prediction should be fixed in no studies, 
only in studies where it is detected (the default), or in all studies.

{phang}
{cmd:augwt(}{it:#}{cmd:)} determines the weight applied to added observations 
in a study in which perfect prediction is detected (see Perfect Prediction below).
The default is 0.01.
{cmd:augment(0)} is the same as {cmd:ppfix(none)} and specifies that no augmentation is to be performed.

{phang}
{cmd:noauglist} suppresses listing of the augmented observations.

{phang}
{cmd:ppcmd(}{it:regcmd}[{it:,options}]{cmd:)} specifies that perfect prediction should be fixed by using 
regression command {it:regcmd} with options {it:options}, instead of the default augmentation procedure.

{phang}
{cmd:hard} is useful when convergence may not be achieved in some studies. 
It captures the results of initial model fitting in each study, and treats any non-zero return code as a symptom of perfect prediction.

{phang}
{it:regression_options} are any options allowed for {it:regression_command}.


{title:Perfect Prediction}

{p 0 0 0}
Perfect prediction is a problem which may lead to highly misleading results being output.
It may occur in regression models for categorical or survival data.
In logistic regression, for example, perfect prediction occurs if there is a level of a categorical explanatory variable for which the observed values of the outcome are all zero;
in Cox regression, it occurs if there is a category in which no events are observed.

{p 0 0 0}
{cmd:mvmeta_make} checks for perfect prediction by checking (i) that all parameters are reported, and (ii) that there are no zeroes on the diagonal of the variance-covariance matrix of the parameter estimates.
If perfect prediction is detected, it augments the data to avoid perfect prediction.

{p 0 0 0}
The augmentation is performed at 2 design points for each covariate x, defined by letting x equal its study-specific mean plus or minus its study-specific standard deviation and fixing other covariates at their mean value.
The records added at each design point depend on the form of regression model.
For regression models with discrete outcomes, we add one observation with each outcome level.
For survival analyses, we add one event at time tmin/2 and one censoring at time tmax+tmin/2, where tmin and tmax are the earliest and latest follow-up times in the study. For a stratified model, the augmentation is performed for each stratum.

{p 0 0 0}
A total weight of wp is then shared equally between the added observations, where w is specified by the {cmd:augwt(#)} option and p is the number of model parameters
(treating the baseline hazard in a Cox model as a single parameter).

{p 0 0 0}
The regression model is then re-run including the weighted added observations.

{p 0 0 0}
When many studies have perfect prediction, it may be worth specifying the {cmd:ppfix(all)} option which bypasses the initial fit of the model without augmentation.

{p 0 0 0}
Alternatives to augmentation include penalised likelihood methods, which would be specified by the {cmd:ppcmd()} option.
These are implemented by {helpb plogit} and {helpb stpcox} which should in the near future be able to handle perfect prediction.

{p 0 0 0}
The output data set contains variables _ppfix which indicates whether the outputted results derive from a model in which perfect prediction was tackled,
and _ppremains which indicates whether perfect prediction was detected in this final model.


{title:Example}

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:See also}

{helpb mvmeta}, {helpb metan}, {helpb metareg}.
