*! version 1.7 16may2018

Title

smcfcs Multiple imputation of partially observed covariates and outcomes by substantive model compatible fully conditional specification (smcfcs)

Syntax

smcfcs smcmd smdepvar smindepvars, [ regress(varlist)
logit(varlist) poisson(varlist) nbreg(varlist) mlogit(varlist)
ologit(varlist) time(varname) enter(varname) failure(varname)
iterations(#) m(#) rjlimit(#) passive(string)
eq(string) rseed(string) chainonly savetrace(filename) noisily by(varlist) ]

Main
regress(varlist) partially observed continuous variables to be imputed

logit(varlist) partially observed binary variables to be imputed

poisson(varlist) partially observed Poisson variables to be imputed

nbreg(varlist) partially observed negative binomial variables to be imputed

mlogit(varlist) partially observed unordered categorical variables to be imputed

ologit(varlist) partially observed ordered categorical variables to be imputed

time(varname) for competing risks outcomes, the name of the variable indicating failure time

enter(varname) for competing risks outcomes, an optional variable indicating the time of delayed entry

failure(varname) for competing risks outcomes, the name of the variable indicating failure type

iterations(#) specify number of iterations to perform for each imputation; default is 10

m(#) specify number of imputations to generate; default is 5

rjlimit(#) specify limit for rejection sampler; default is 1000

passive(string) string expressions for evaluating derived covariates in the substantive model

eq(string) string expressions for custom prediction equations

rseed(string) set Stata's random seed

chainonly perform iterations of SMC-FCS (as specified by iteration option) without creating imputations

savetrace(filename) save estimates of substantive model parameters from each iteration in filename.dta

noisily runs smcfcs noisily

by(varlist) specifies that imputation be performed separately by groups defined by varlist

clear specifies that any multiply imputed data in memory be cleared.

exposure(varname) for Poisson substantive models, an optional variable indicating exposure time

smcmd smdepvar smindepvars specifies the substantive model
with which covariates are to be imputed compatibly with. Currently smcmd can be regress, logit,
stcox, compet, or poisson. In the case of stcox, the dataset should be stset
prior to running smcfcs, and no smdepvar should be specified. In the case of compet,
the data should not be stset, but instead the time and failure indicator variables should passed
using the time and failure options.

Description

smcfcs multiply imputes missing values of covariates using a modified version of the fully conditional specification (chained equations)
algorithm. Each partially observed covariate is imputed from an imputation model which is compatible with the specified substantive model.

Options

regress(varlist) specifies the names of the partially observed continuous variables (if any), which are to be imputed.

logit(varlist) specifies the names of the partially observed binary variables (if any), which are to be imputed.

poisson(varlist) specifies the names of the partially observed Poisson variables (if any), which are to be imputed.

nbreg(varlist) specifies the names of the partially observed negative binomial variables (if any), which are to be imputed.

mlogit(varlist) specifies the names of the partially observed unordered categorical variables (if any), which are to be imputed.

ologit(varlist) specifies the names of the partially observed ordered categorical variables (if any), which are to be imputed.

time(varname)} for competing risks outcomes, the name of the variable indicating failure time.

enter(varname) for competing risks outcomes, an optional variable indicating the time of delayed entry.

failure(varname) for competing risks outcomes, the name of the variable indicating failure type.

iterations(#) specifies the number of iterations to perform for each imputation; default is 10.

m(#) specifies number of imputations to generate; default is 5.

rjlimit(#) smcfcs uses rejection sampling to impute missing covariate values for variables which do not have a finite sample space. Rejection sampling involves repeatedly drawing from a distribution until a valid imputation is found. This option
specifies the maximum number of attempts that smcfcs will make to find a valid draw for imputed values. If valid values have not been found for one or more subjects by the limit the command continues,
using the last proposed draw for such subjects. The default limit is 1000.

passive(string) specifies a string of equations to update derived covariates (if any). Each expression within the string must be separated by a |. Derived covariates may appear either in the
substantive model, in covariate models, or both.

eq(string) specifies a string of linear predictor sets for partially observed variables. Each expression within the string must be separated by a |. Each expression should be of the form varname: varlist,
which specifies that the linear predictor of the covariate model for varname is given by varlist. If an expression is not specified for a given partially observed variable, the default is to impute using
a covariate model which includes any fully observed variables in the substantive model and all partially observed variables except the one being imputed.

rseed(string) sets Stata's random number seed to the given value.

chainonly perform iterations of SMC-FCS (as specified by iteration option) without creating imputations. Useful in conjunction with savetrace to assess convergence.

savetrace(filename) save estimates of substantive model parameters from each iteration in filename.dta. Useful for checking convergence of SMC-FCS.

noisily runs SMC-FCS noisily. Useful for diagnosing errors.

by(varlist) imputes separately within groups defined by varlist.

clear specifies that any previous imputations in the data be cleared. If imputations already exist, smcfcs will exit with an error unless the clear option is specified.

exposure(varname) for Poisson substantive models, the exposure time variable.

Remarks

smcfcs multiply imputes missing values in covariates based on the fully conditional specification (or chained equations) approach. The
user must specify a substantive model for how the outcome depends on the covariates. At present, linear (regress), logistic (logistic),
Cox proportional hazards (stcox) for time to event data, and competing risks substantive models are supported. For Cox models for single
time to event data, the data should be stset prior to running smcfcs. Right censoring and delayed entry (left truncation) are supported.

Each partially observed variable is then imputed from an imputation model
which is compatible with the specified substantive model. For continuous and binary outcomes, smcfcs will additionally impute any missing values
in the outcome, using the specified substantive model as the imputation model.

The substantive model can include independent variables whose values are (user defined) functions of the partially observed variables.
For example, the substantive model can contain non-linear terms, such as x^2 as independent variables, or
ratios (e.g. BMI = weight / height^2). In this case the passive option is used to specify how these derived
covariates are calculated, with equations separated by | symbols (see examples).

Currently smcfcs supports the imputation of continuous (linear regression), binary (logistic), count (Poisson or negative binomial regression),
unordered categorical (multinomial logistic regression) and ordered categorical (ordered logistic regression) variables. By default, partially
observed variables are imputed from a model which conditions on all of the other fully and partially observed variables. If
desired, this behaviour can be altered through use of the eq option. By default partially observed categorical variables are included
as factor variables when they serve as predictors in the imputation models of other variables. Main effects of variables can be included in
the substantive model using Stata's i. factor notation if desired. Interactions must however be included by first generating an interaction variable,
including this in the substantive model, and by passing the corresponding argument to the passive option to enable the interaction variable to be
updated by the program (see the example).

For competing risks outcomes, smcfcs assumes a Cox proportional hazards model for each cause of failure. For competing risks
outcomes you must pass variables to the time and failure options to indicate the corresponding variables. The failure variable should be
an integer valued variable, with 0 indicating censoring and 1,2,3 etc indicating failures due to each of the competing causes. In the case
of competing risks outcomes, smcfcs (at present) uses a common set of covariates in each Cox model.

Once the desired number of imputations have been generated, smcfcs imports the imputations to a Stata mi format (flong), and then fits the substantive model to
the imputations using Stata's mi estimate command. The mi estimate command can then be used to fit alternative models for the outcome, although
care should be taken to ensure that these are nested within the substantive model specified to generate the imputations.

The command will give a warning if valid draws are not obtained for one or more observations within the limit specified by the rjlimit(#) option. If you receive
this warning you should probably increase the limit until the warning no longer appears, although in (limited) simulations we have obtained good results even when
the warning has appeared for a small proportion of subjects.

The default number of iterations of 10 may not be sufficient for SMC-FCS to converge in a given setting. Users should check convergence of the algorithm by using
the chainonly and savetrace options, using a large number of iterations.

If the by option is specified, smcfcs imputes separately in groups defined by the corresponding varlist, and then combines these to
form a single set of imputations for the whole dataset. Ordinarily after generating the imputed datasets smcfcs fits the specified substantive model
to the imputed datasets. However, if imputation has been performed separately by groups, smcfcs does not do this - in this situation the user must
fit an appropriate model in the combined dataset. Note that if a variable is specified in by, it must not be included as a covariate in the substantive model
specified when calling smcfcs. In this case however one can still fit a substantive model to the imputed datasets which does include the variable.

Further details regarding the algorithm used by smcfcs can be found in the article referenced below.

Examples

Create multiple imputations of continuous x1 and x2, assuming y follows a linear regression with x1, x1^2, x2 and x2^2 as covariates

smcfcs reg y x1 x1sq x2 x2sq, reg(x1 x2) passive(x1sq = x1^2 | x2sq = x2^2)

Create multiple imputations of continuous x1 and x2, assuming y follows a linear regression with x1, x2 and x1*x2 as covariates

gen x1x2=x1*x2

smcfcs reg y x1 x2 x1x2, reg(x1 x2) passive(x1x2=x1*x2)

Create multiple imputations of wgt and ht, assuming the outcome y follows a logistic model with bmi (wt / ht^2) as covariate

smcfcs logistic y bmi, reg(wgt ht) passive(bmi = wt / ht^2)

Create multiple imputations of x1 (binary) and x2 (continuous), assuming a Cox model with x1 and x2 as linear terms

smcfcs stcox x1 x2, reg(x2) logit(x1)

Competing risks outcomes. Create multiple imputations of x1 (binary) and x2 (continuous), assuming a Cox model for each competing risk
with x1 and x2 as linear terms in both

smcfcs compet x1 x2, reg(x2) logit(x1) time(t) failure(d)

References

Jonathan W. Bartlett, Shaun R. Seaman, Ian R. White, James R. Carpenter. Multiple imputation of covariates by fully conditional specification: accommodating the substantive model.
Statistical Methods in Medical Research, 24:462-487, 2015

Jonathan W. Bartlett, Tim P. Morris. Multiple imputation of covariates by substantive model compatible fully conditional specification.
The Stata Journal, 15:437-456, 2015

Authors

Jonathan Bartlett, AstraZeneca, UK

jwb133@googlemail.com

www.thestatsgeek.com
www.missingdata.org.uk

Tim Morris, MRC Clinical Trials Unit at UCL, UK

tim.morris@ucl.ac.uk

Also see

mi impute
mi impute chained
mi estimate