-------------------------------------------------------------------------------
help for mvmeta_make                                                  Ian White
-------------------------------------------------------------------------------

Prepare data for multivariate meta-analysis


Description

    mvmeta_make is a utility to produce data in the correct format for 
    mvmeta.


Syntax

        mvmeta_make regression_command [if] [in] [weight] , by(by_variable)
                 saving(savefile) [replace append names(bname Vname) keepmat
                 usevars(string) useconstant esave(namelist) nodetails pause
                 ppfix(none|check|all) augwt(#) noauglist
                 ppcmd(regcmd[,options]) hard regression_options]

    This command performs regression-command for each level of by_variable
    and stores the results in savefile in the format required by mvmeta.


Options

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

    saving(savefile) is compulsory: the regression results are saved to this
        file.

    replace specifies that savefile may already exist.

    append specifies that savefile already exists and the results should be
        appended to it.

    names(bname Vname) specifies that estimated coefficients for variable x
        are to be stored in variable bnamex, and the estimated covariance
        between coefficients bnamey and bnamey is to be stored in variable
        Vnamexy. Defaults are y and S.

    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 bnamei and Vnamei respectively, where bname and Vname are
        the names specified by names.

    usevars(varlist) identifies the variables whose regression coefficients
        are of interest. The default is all variables in the model, excluding
        the constant.

    useconstant specifies that the constant is also of interest.

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

    nodetails suppresses the results of running regression_command on each
        study.

    pause pauses output after the analysis of each study, provided that pause
        on has been set.

    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.

    augwt(#) 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.  augment(0) is the same as ppfix(none)
        and specifies that no augmentation is to be performed.

    noauglist suppresses listing of the augmented observations.

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

    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.

    regression_options are any options allowed for regression_command.


Perfect Prediction

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.

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.

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.

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

The regression model is then re-run including the weighted added observations.

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

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

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.


Example

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

    . 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:

    . use FSCstage1, clear

    . mvmeta b V


See also

mvmeta, metan, metareg.