*! v4.0.2 21apr2022

Title

mvmeta_make -- Prepare data for multivariate meta-analysis

Description

mvmeta_make is a utility to produce data in a suitable format for
multivariate meta-analysis.
It performs regression_command for each combination of levels of byvarlist.
It then stores the results in the format required by mvmeta.

Syntax

Classic syntax:

mvmeta_make
regression_command
[if] [in]
[weight],
by(byvarlist)
[mvmeta_make_options
regression_options]

Prefix syntax:

mvmeta_make,
by(byvarlist)
[mvmeta_make_options]: regression_command
[if] [in]
[weight],
[regression_options]

where mvmeta_make_options are

[saving(savefile)
replace
append
clear
usevars(string)
useconstant
useeqs(eqlist|*)
learnif(exp)
usecoefs(coeflist)
esave(namelist)
counts(string)
collapse(collapse_exp)
names(bname Vname)
infix(string)
longnames
keepmat
nodetails
pause
ppfix(none|check|all)
augwt(#)
noauglist
ppcmd(regcmd[,options])
hard
regression_options]

and regression_options are any options allowed for regression_command.

Options: by-variable

by(byvarlist) is not optional. It identifies the studies, in each of which the regression
command will be performed.

Options: saved file

Either saving(savefile) or clear or both must be specified.

saving(savefile) specifies that the regression results are saved to savefile.

replace specifies that savefile may already exist and should be overwritten.

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

clear specifies that the regression results are loaded into memory.

Options: what results are stored

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.

useeqs(eqlist|*) specifies equations in a multiple-equation model
whose regression coefficients are also of interest.
See Which coefficients are used? for details.

learnif(exp) specifies a subgroup
in which the equation names and coefficients can be learned.
The default is to use the whole data set, which can be slow.

usecoefs(coef1 [coef2 ...])
specifies the coefficients to be used, in the format [eqname]coefname or coefname.
This option replaces usevars(), useconstant, useeqs() and learnif().

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.
For logistic regression, esave(N_fail) outputs the number of events
even though e(N_fail) does not exist.

counts(string) is a partial alternative to esave().
string can be one or more of records subjects and failures.
It adds the specified variables to the saved data.

collapse(collapse_exp) adds data summaries to the regression output.
The data summaries are formed by running
collapse collapse_exp, by(byvarlist): see collapse.

Options: how results are stored

names(bname Vname) specifies that estimated coefficients for variable x
are to be stored in variables whose names are prefixed by bnamex,
and the estimated covariances are to be stored in variables whose names are
prefixed by Vname.
Defaults are y and S.
When a single equation is used, the coefficient of x is bnamex1
and its covariance with the coeficient of x2 is Vnamex1x2.
When multiple equations are used, the coefficient of x in equation eq1 is bnameeq1x1
and its covariance with the coeficient of x2 in equation eq2 is Vnameeq1x1eq2x2.
But see infix(string) and longname below.

infix(string) inserts string into the variable names.
For example, infix(_) changes bnamex1 to bname_x1 and Vnameeq1x1eq2x2
to Vname_eq1_x1_eq2_x2.

longnames specifies that variables storing coefficients are to be named
as described under "When multiple equations are used" in names() above.

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.

Options: output

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.

Options: perfect prediction behaviour

See Perfect Prediction for details.

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.
augwt(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.

Options: estimation

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.

Options specific to regression command

regression_options are any options allowed for regression_command.
In particular, baseoutcome() is required when regression_command is
mlogit: see mlogit.

Which coefficients are used?

In simple calls,
the default behaviour of mvmeta_make is to use all
the regression coefficients except the constant.
usevars() restricts attention to a subset of coefficients
and useconstant additionally uses the constant.

The above behaviour applies to single-equation regression commands;
and all equations of mlogit and mvreg;
and the first equation of all other multiple-equation regression commands;

The other equations can be used via the useeqs() option, which specifies
the names of the other equations to be used.
All coefficients in the specified equations (including the constant) are used.

mvmeta_make starts by learning the equation names
and (with useeqs()) the coefficient names.
By default it does this by fitting the regression command to the whole data set.
You can speed it up by specifying the learnif() option:
for example, learnif(study==3) specifies that the equation names and coefficients
can be learned by fitting the regression command to study 3.
You can avoid this step altogether by specifying usecoefs().

Perfect prediction

Perfect prediction is a problem which may occur in regression models for categorical or survival data
and may lead to misleading results being output.
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 with a set of low-weight data points to avoid perfect prediction.
Augmentation is not available when robust standard errors are requested,
because robust standard errors do not respect the low weights.

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 w*p 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.
ppfix(all) is also needed in a mlogit model if the base level of the outcome
(speecified in baseoutcome()) does not occur in some studies.

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

Returned results

mvmeta_make is an e-class command. It returns e(cmd), e(cmdline) and e(sample) only.

Changes since publication in Stata Journal

Version 0.10 was published in White (2009).
The main changes since then are:

Augmentation now works for clogit (the augmented values are placed into new groups).

Multiple-equation commands are now supported (v0.20).

mvmeta_make is now eclass.

esave() has new options N_sub (number of subjects) and N_fail (number of events)
with logistic regression.

Various bug fixes.

by() now allows a variable list (v0.21).

Prefix syntax created (v0.22). This allows mvmeta_make to be used with commands such as mixed and mi estimate. See examples 2 and 3 below.

Limitations

mvmeta_make does not allow factor variables. Use xi.

Example

Example 1. Analysis of individual participant data using the classic syntax.
The data are from the Fibrinogen Studies Collaboration (White, 2009); they are not publicly available.
The exposure of interest is fifth of fibrinogen stored in variable fg with 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)

Note that strata(sex tr) and nohr are options for stcox while the other options are for mvmeta_make.
The command would give exactly the same results using the prefix syntax:

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

The results would be then meta-analysed in the second stage:

. use fscstage1, clear

. mvmeta b V

Example 2. Analysis of multiply imputed data using the prefix syntax.

. use mvmeta_make_testdata_mi, clear

. mvmeta_make, by(study) clear usecons details: mi estimate, post: reg y x

Here for illustrative purposes we chose to store the constant as well as the coefficient of x.

Note that mi estimate only works correctly with mvmeta_make if each study contains the same number of imputed datasets.
This is a feature of mi estimate.
If each study has been imputed separately then they may have different numbers of imputed datasets:
if so, you will need to create multiple combined datasets, each containing studies with the same number of imputed datasets, and run mvmeta_make on each combined dataset separately, using the append option after the first run.

Example 3. Analysis of repeated measures data using the prefix syntax.
We have data from a randomised trial with outcomes at times 1 and 2.
We are interested in the treatment effects at each time, so we create variables z1 and z2 as treatment indicators at times 1 and 2, and use their coefficients.

. use testdata_mixed, clear

. gen z1 = 0

. replace z1 = z if time==1

. gen z2 = 0

. replace z2 = z if time==2

. mvmeta_make, by(study) clear usecoefs([y]z1 [y]z2): mixed y time z1 z2 || id:, nocons res(uns, t(time)) reml

This example uses the res(uns, t(time)) option of to specify an unstructured variance-covariance matrix, which avoids making assumptions that would bias the standard errors if wrong.
This option causes mixed to fail if run on the whole data set, so we use the usecoefs([y]z1 [y]z2) option to specify which coefficients we want: note that the equation names must be specified.
An alternative would be usevars(z1 z2) learnif(study==1).

References

White IR. Multivariate random-effects meta-analysis.
Stata Journal 2009; 9: 40-56.
http://www.stata-journal.com/article.html?article=st0156

Author and updates

Ian White, MRC Clinical Trials Unit at UCL, London, UK.
Email ian.white@ucl.ac.uk.

You can get the latest version of this package by visiting https://github.com/UCL/mvmeta
or within Stata by running
net from https://raw.githubusercontent.com/UCL/mvmeta/master/package/.