help for ice, uvisPatrick Royston

Title

ice -- Multiple imputation by the MICE system of chained equations

Syntax

ice
[mainvarlist]
[if] [in]
[weight]
[, major_options less_used_options]

uvis
cmd
{yvar|llvar ulvar}
xvars
[if] [in]
[weight]
[, options]

ice major_options
clear clears the original data from memory and loads the imputed dataset into memory

dryrun reports the prediction equations - no imputations are done

eq(eqlist) defines customised prediction equations

m(#) defines the number of imputations

match(varlist) predictive mean matching for each member of varlist

passive(passivelist) passive imputation

saving(filename [,replace]) imputed and non-imputed variables
are stored to filename

stepwise constructs prediction equations by stepwise variable selection

swopts(stepwise_options) options for stepwise

ice stepwise_options
forward perform forward-stepwise selection

group(group_list) create groups of variables for joint testing for addition or removal

lock(varlist) Variables to be kept in all models

pe(#) significance level for addition to a model

pr(#) significance level for removal from a model

show show each stepwise regression

ice less_used_options
allmissing imputes in observations with all values in mainvarlist missing

boot(varlist) estimates regression coefficients
for varlist in a bootstrap sample

by(varlist) imputation within the levels implied by varlist

cc(varlist) prevents imputation of missing data in observations
in which varlist has a missing value

cmd(cmdlist) defines regression command(s) to be used for imputation

conditional(condlist) conditional imputation

cycles(#) determines number of cycles of regression switching

debug assistance to debug individual regressions

dropmissing omits from the output all observations
not in the estimation sample

eqdrop(eqdroplist) removes variables from prediction equations

genmiss(string) creates missingness indicator variable(s)

id(varname) creates varname containing
the original sort order of the data

initialonly impute by random sampling from distribution of non-missing values

interval(intlist) imputes interval-censored variables

matchpool(#) size of pool of potential matches for predictive mean matching

monotone assumes pattern of missingness is monotone, and
creates relevant prediction equations

noconstant suppresses the regression constant

nopp suppresses special treatment of perfect prediction

noshoweq suppresses presentation of prediction equations

noverbose suppresses messages showing the progress of the imputations

nowarning suppresses warning messages

on(varlist) imputes each member of mainvarlist univariately

orderasis enters the variables in the order given

persist ignore errors when trying to impute "difficult" variables and/or models

restrict([varname] [if]) fit
models on a specified subsample, impute missing data for entire estimation sample

seed(#) sets random number seed

substitute(sublist) substitutes dummy variables for
multilevel categorical variables

trace(trace_filename) monitors convergence of the imputation algorithm

uvis options
gen(newvarname) creates variable containing imputations. Not optional

boot estimates regression coefficients in a bootstrap sample

by(varlist) imputation within the levels implied by varlist

lrd imputes using local residual draws

match does predictive mean matching

matchpool(#) size of pool of potential matches for predictive mean matching

matchtype(#) sets the method for identifying closest matches

nopp suppresses special treatment of perfect prediction

noverbose suppresses information about the imputation process

replace overwrites newvarname if it exists

restrict([varname] [if]) fit
models on a specified subsample, impute missing data for entire estimation sample

seed(#) sets random number seed

where cmd (with uvis) may be
intreg,
logistic,
logit,
mlogit,
nbreg,
ologit,
or
regress. llvar ulvar are required with intreg.

An element of mainvarlist for ice takes one of two forms:
varname or [i.|m.|o.]varname.
Details are given in
Special features for imputing categorical variables.
If mainvarlist is omitted, variables and chained equations are input from
special global macros; see the eq() and stepwise options for
details.

All weight-types are supported.

Stata 11 users: Please see mi ice, which does all that ice
does and a little bit more, and is conveniently integrated into the new
mi system.

Description

ice imputes missing values
in mainvarlist by using switching regression, an iterative multivariable
regression technique. The abbreviation MICE means multiple imputation by
chained equations, and was apparently coined by Stef van Buuren. ice
implements MICE for Stata. Sets of imputed and non-imputed variables are
stored to a new file called filename. Any number of complete imputations
may be created. The original data are stored in filename as
"imputation number 0" and the new variable _mj is set to 0 for these
observations.

uvis (univariate imputation sampling) imputes
missing values in the single variable yvar based on multiple regression
on xvars. uvis is called repeatedly by ice
in a regression switching mode to perform multivariate imputation.

The missing observations are assumed to be "missing at random" (MAR) or
"missing completely at random" (MCAR), according to the jargon.
See for example van Buuren et al
(1999) for an explanation of these concepts.

Please note that ice and uvis require Stata 8.0 or higher.
There have been incompatibility issues with Stata 7 or lower.

Special features for imputing categorical variables

The prefixes i., m. and o. for a variable in
ice's mainvarlist are a convenience feature designed
to simplify specification of the imputation model for categorical
variables with three or more levels. You should hardly ever need to
use Stata's xi dummy variable and interaction creator directly with
ice commands, since dummy variables and more are adequately
handled by using the i., m. and o. prefixes.

The prefix i. in i.varname may be used only when
varname has no missing data. It applies xi to
i.varname to create the corresponding dummy variables.
If varname has missing data, imputation is required; either
the m. or the o. prefix (see below) should be used with
such variables. See
Pitfalls in using the i. prefix
for further information.

Use of m.varname or o.varname substitutes i. for
m. or o. and applies
xi: to i.varname, at the same time
telling ice to impute missing values of varname
using the mlogit or ologit commands,
respectively. Use of the m. or o. prefixes also ensures that the corresponding
dummy variables are used as predictors in imputation models for other
variables (see substitute())
and are 'passively' imputed (see passive()).
Suppose that x is a multilevel categorical variable.
Then ice o.x varlist, options is expanded to
xi: ice x i.x varlist, substitute(x:i.x) cmd(x:ologit) options.
Similary, ice m.x varlist, options is expanded to
xi: ice x i.x varlist, substitute(x:i.x) cmd(x:mlogit) options.

The resulting 'expanded' version of the ice command
is stored in the $F9 global macro. It can be retrieved if desired by
pressing the F9 key.

Note that the i., m. and o. prefixes are also valid with binary
variables, although much less likely to be useful since one would not wish
to impute a binary variable using either mlogit or ologit.

Options

ice (major options)

clear clears the original data from memory and loads the imputed dataset.
Unless the saving() option is also specified, the data in memory are
not permanently saved; this must then be done manually using the save
or saveold commands.

dryrun causes ice to report the prediction equations
it has constructed from the various inputs, but no imputations
are done and no files are created. The option name ("dryrun")
may be abbreviated as dry. It is not mandatory to specify
an output file with saving(filename) for a dry run.
Sometimes the prediction equation set-up needs to be carefully
checked before running what may be a lengthy imputation process.
Note that stepwise selection of prediction equations (stepwise
option) still works when dryrun has been specified.

eq(eqlist) allows one to define prediction
equations for any subset of variables in mainvarlist. The eq()
option, particularly when used with passive(), allows
great flexibility in the possible imputation schemes. Note that eq()
takes precedence over all default definitions and assumptions about
the way a given variable in mainvarlist is to be imputed.
If the passive() and substitute() options are not invoked,
the default set of equations is that each variable in mainvarlist
with any missing data is imputed from all other variables in mainvarlist.

When eq() is specified, the syntax of eqlist is
varname1:varlist1
[,varname2:varlist2 ...] where each
varname# (or varlist#)
is a member (or subset) of mainvarlist. Variable names
prefixed by i. are allowed, provided that the names
were prefixed by i., m. or o. in mainvarlist.
They are translated to the corresponding dummy variables created
by xi:.

A 'blank' (null, constant-only) equation is specified as _cons,
for example, eq(x4 x5:_cons). Such equations are reported in the table
of prediction equations as "[Empty equation]". The prediction
model for variables with empty equations is simply _cons.

If mainvarlist is omitted, ice takes mainvarlist
from the global macro $ice_main and the equations, regression
commands and predicted variables from global macros $ice_eq#,
$ice_cmd# and $ice_x#, respectively, for
# = 1, ..., $ice_neq. The number
of equations is stored in $ice_neq. These macros are created
automatically when ice's stepwise option is used (see details
under stepwise). They may also be user-defined. The macros may be
inspected in Stata by using the command macro list ice_*.

m(#) defines # as the number of imputations required
(minimum 1, no upper limit). The default # is 1.

match[(varlist)] instructs that each member of
varlist be imputed with the match option of uvis.
This provides predictive mean matching for each member of varlist.
If (varlist) is omitted then all relevant variables are
imputed with the match option of uvis. The default, if
match() is not specified, is to draw from the posterior
predictive distribution of each variable requiring imputation.

passive(passivelist) allows the use of "passive" imputation
of variables that depend on other variables, some of which are imputed.
The syntax of passivelist is varname:exp
[\varname:exp ...]. Notice the requirement to use
"\" as a separator between items in passivelist, rather than the usual comma;
the reason is that a comma may be a valid part of an expression.
The option is most easily explained by example. Suppose x1 is a categorical variable
with 3 levels, and that two dummy variables x1a, x1b have been created by the commands

. generate byte x1a=(x1==2)

. generate byte x1b=(x1==3)

Now suppose
that x1 is to be imputed by the mlogit command, and is to be treated
as the two dummy variables x1a and x1b when predicting other variables.
Use of mlogit is achieved by the option cmd(x1:mlogit).
When x1 is imputed, we want x1a and x1b to be updated with new values
which depend on the imputed values of x1.
This may be achieved by specifying passive(x1a:x1==2 \ x1b:x1==3). It
is necessary also to remove x1 from the list of predictors when variables
other than x1 are being imputed, and this is done by using the
substitute() option; in the present example, you would specify
substitute(x1:x1a x1b).

Note that although in this example x1a will take the (possibly
unintended) value of 0 when x1 is missing, ice is careful to
ensure that x1a (and x1b) inherit the missingness of x1, and are
passively imputed following active imputation of missing values
of x1. If this were not done, incorrect results could occur. The
responsibility of the user is to create x1a and x1b before running
ice such that their missing values are identical
to those of x1.

A second example is multiplicative interactions between variables, for
example, between x1 and x2 (e.g. x12=x1*x2); this could be entered as
passive(x12:x1*x2). It would cause the interaction term
x12 to be omitted when either x1 or x2 was being imputed, since it would
make no sense to impute x1 from its interaction with x2.
substitute() is not needed here.

It should be stressed that variables to be imputed passively
must already exist and must be included in mainvarlist, otherwise they
are not recognised. Passive variables may be defined in terms
of variables in mainvarlist and variables not in mainvarlist,
although it would of course make no sense not to involve at least one
variable in mainvarlist.

saving(filename [,replace]) saves the imputation to
filename. replace allows filename to be overwritten
with new data. replace may not be abbreviated.

stepwise constructs prediction equations by stepwise variable selection
among members of mainvarlist. There are 3 steps to the process. First,
ice creates a dataset with 1 imputation using a randomly drawn subset
of values from the distribution of each variable with missing values. (This is
the standard initialisation step for ice, and is invoked automatically
by the initialonly option.) Next, ice runs stepwise to
select variables for each prediction equation. Binary dummy variables
are treated appropriately. By default, forward selection at a 5% significance
level is used; see the swopts() option for other possibilities. Finally,
ice retrieves the reduced equations and performs imputation with
them as usual.

Using stepwise also causes ice to store mainvarlist, the
selected equations, variables and commands in global macros called
$ice_*, as described under the eq() option.

swopts(stepwise_options) allows the following stepwise_options
for use with stepwise:
forward, group(group_list), lock(varlist),
pe(#), pr(#) and show. Note that only
pe(#), pr(#) and forward are standard options of Stata's
stepwise command; the remainder are used to group variables for
joint testing for inclusion or exclusion from the models, to construct a
list of variables formatted for use with stepwise's lockterm1
option, and to show the output from stepwise. Further details of
individual options are given below under ice (stepwise options).

Specifying neither pe(#) nor pr(#) is equivalent to specifying
pe(0.05), i.e. the default method is forward selection of variables
significant at the 5% level.

Note that variables in mainvarlist that have the prefix i.,
indicating that they are categorical, are to be represented by their
dummy variables and have no missing data, should retain their
i. prefix when they are included in the group() or
lock() options.

ice (stepwise options)

forward specifies the forward-stepwise method and may be specified
only when both pr() and pe() are also specified. Specifying
both pr() and pe() without forward results in
backward-stepwise selection. Specifying only pr() results in backward
selection, and specifying only pe() results in forward selection.

group(group_list) specifies variables always to be tested jointly for
inclusion or exclusion from models. An element of group_list
is a varlist, and elements are separated by commas, for example
group(x1 i.x2, y1 y2). Such groups of variables (or, in the case
of categorical variables prefixed with i., their implied dummy variables)
are surrounded by parentheses when presented to stepwise for analysis.

lock(varlist) specifies variables to be kept in all models. Such
variables are surrounded by parentheses when presented to stepwise
for analysis. The lockterm1 option of stepwise is applied to them.

pe(#) specifies the significance level for addition to the model;
terms with p < pe() are eligible for addition.

pr(#) specifies the significance level for removal from the model;
terms with p >= pr() are eligible for removal.

show displays the output from stepwise for each regression
analysis to develop the prediction equations used by ice.

ice (less used options)

allmissing imputes missing values in observations in which all
variables in mainvarlist are missing. The default is to leave such values
as missing.

boot[(varlist)] instructs that each member of varlist,
a subset of mainvarlist, be imputed with the boot option of uvis
activated. If (varlist) is omitted then all members of mainvarlist
with missing observations are imputed using the boot option of uvis.

by(varlist) performs multiple imputation separately for all combinations of
variables in varlist. Observations with missing values for any
members of varlist are excluded. May be combined with restrict().

cc(varlist) prevents imputation of missing data in mainvarlist for
cases in which any member of varlist has a missing value. "cc" signifies
"complete case". Note that members of varlist are used for imputation if they appear
in mainvarlist, but not otherwise. Use of this option is equivalent to entering
if ~missing(var1) & ~missing(var2) ..., where
var1, var2, ... denote the members of varlist.

cmd(cmdlist) defines the regression commands to be used
for each variable in mainvarlist, when it becomes the dependent variable in the
switching regression procedure used by uvis
(see Algorithm used by uvis).
The first item in cmdlist may be a command such as regress
or may have the syntax varlist:cmd, specifying that command cmd
applies to all the variables in varlist. Subsequent items in cmdlist
must follow the latter syntax, and each item should be followed by a comma.

The default cmd for a variable is logit when there are two distinct values,
mlogit when there ar 3-5 and regress otherwise.

Example: cmd(regress) specifies that all variables are
to be imputed by regress, over-riding the defaults

Example: cmd(x1 x2:logit, x3:regress) specifies that x1 and
x2 are to be imputed by logit, x3 by regress and all others
by their default choices

Advanced use: If a cmd is implicitly defined for a variable by a o.
or m. prefix and the cmd() option is used explicitly for that
same variable then the explicit use takes precedence over the implicit use. For
example, the combination ... o.x1, cmd(x1:regress) would impute
x1 with regress rather than with the implicit ologit. Used
with match(x1), this would give a reasonable alternative to ordinal
logistic regression for imputing an ordered categorical variable x1.

conditional(condlist) invokes conditional imputation. Each item of
condlist has the form varlist: condition. Items are
separated by backslash (\). The idea is that members of varlist
are only informative when condition is true, and that they take some
pre-determined value when condition is false.

Important: This option was not correctly implemented in versions of ice_
before 1.2.2 – use which ice_ to check your version.

Conditional imputation requires that
(i) when any variable included in condition is missing, all variables in
varlist are missing, and (ii) when condition is false, each variable
in varlist takes only one value (the pre-determined value, which
might be 0 or a unique "not-applicable" code such as 99).

In detail, members of varlist
are imputed in the usual way for the subset of observations for which
if condition is true (i.e. condition evaluates to a
non-zero quantity). For the subset of observations for which
if condition is false, the pre-determined value is identified
from the data for each member of varlist and is used to impute any
missing values for that variable. An example is given below.

condition is a Stata expression constructed so that if
condition can be evaluated for the current dataset. Variables
appearing in condition may be members of mainvarlist or merely
variables in the dataset. The only other situation in ice in
which variables that do not appear in mainvarlist may be used is
described under the passive() option.

Consider a simple example, a dataset comprising three incomplete variables
age, female, and pregnant, where female is 1 for females, 0
for males, and pregnant is 1 for pregnant, 0 for not pregnant. Since males
can't be pregnant, we wish to impute missing values of pregnant using only
data from females. If we impute someone with missing gender as male, we
want their pregnancy status always to be imputed as non-pregnant.
If males are simply coded as non-pregnant then the pre-determined value
is the value of pregnant denoting non-pregnant, i.e. 0; if instead males
are coded as pregnant=99 then the pre-determined value is 99. In either
case, we implement the conditional imputation as follows:

. ice age pregnant female, conditional(pregnant: female==1) clear

Here, the prediction equation for age is pregnant female, that
for female is age and that for pregnant is age if female==1.
Observations of pregnant for originally missing observations of
female now imputed as male (i.e. female = 0) are assigned
the value 0 by ice.

We can have dependent conditional imputation. For example,
suppose a fertility test fertile, taking the value 1 for fertile and 0
for infertile, was available just for females. We might code this as follows:

. ice age pregnant female fertile, conditional(pregnant: female==1 & fertile==1 \ fertile: female==1) clear

which reflects that only fertile females can become pregnant, and only females
have a fertility test.

cycles(#) determines the number of cycles of regression switching to be
carried out. Default # is 10.

debug provides assistance for debugging individual regressions.
As ice runs, it
prints out, for each imputation and cycle, the name of the regression
command, the variable being imputed and R2, the explained variation of the
model (Nagelkerke method). At the same time, the values from the last
cycle only are stored in a new file called _ice_debug.dta, in the
current working directory. A plot of R2 against cycle number may indicate
abnormalities; for example if R2 shows instability, the corresponding model
may have some features that need improving. The option is useful also for
detecting regression models that explain a negligible amount of variation;
such models are candidates for deletion.

Because only the final cycle is stored, for debugging purposes it may be
most sensible to use the debug option with, say, cycles(100) and
m(1).

dropmissing is a feature designed to save memory when using
the file of imputed data created by ice. It omits from filename all
observations which are not in the estimation sample, that is for which either
(i) they are filtered out by if or in, or a non-positive
weight, or
(ii) the values of all variables in mainvarlist are missing.
This option provides a "clean" analysis file of imputations, with
no missing values. Note that the observations not in the
estimation sample are omitted also from
the original data, stored as imputation #0 in filename.

eqdrop(eqdroplist) deletes variables from prediction equations.
The syntax of eqdroplist is varname1:varlist1
[,varname2:varlist2 ...] where each
varname# (or varlist#) is a member (or subset) of mainvarlist.
One can only remove predictors from equations for variables with missing
values (although trying to remove predictors from non-existent equations
is not a fatal error - an information message is issued). Variable names
prefixed by i. are allowed, provided that the names
were prefixed by i., m. or o. in mainvarlist.
They are translated to the corresponding dummy variables created
by xi:.

genmiss(string) creates an indicator variable for the
missingness of data in any variable in mainvarlist for which at least one value
has been imputed. The indicator variable is
set to missing for observations excluded by if, in, etc.
The indicator variable for xvar is named stringxvar.
The information on missingness is implicit in the original
data, which is stored as "imputation 0".

id(newvarname) creates a variable called newvarname containing
the original sort order of the data. Default newvarname: _mi.

interval(intlist) imputes interval-censored variables.
An interval-censored value is one which is known to lie in an interval [a,b]
where a and b are finite and a <= b, or in (-infinity,b] or in [a,infinity).
When either terminal is infinite we have left or right censoring, respectively.
intlist has the syntax varname:llvar ulvar
[, varname:llvar ulvar ...],
where each varname is an interval-censored variable, each
llvar contains the lower bound (a) for varname and each
ulvar contains the upper bound (b) for varname (or a missing
value to represent plus or minus infinity).
The supplied values of varname are irrelevant since they will be
replaced anyway; it is only required that varname exist. Observations
with llvar missing and ulvar present are left-censored
for varname. Observations with llvar present and ulvar
missing are right-censored for varname. Observations with
llvar = ulvar are complete, and no imputation is done for
them. Observations with both llvar and ulvar missing
are imputed assuming an uncensored normal distribution.
See Interval censoring for further information.

initialonly imputes by random sampling from the distribution of
the non-missing values of each variable which has missing value(s).
This is the initialisation step of the MICE algorithm (see Remarks).
This option may be used to get a 'quick and dirty' set of multiple
imputations with which to explore initial impressions of the analysis
model, or to investigate possible prediction equations for
subsequent multiple imputation using the MICE method. The prediction
equations that are displayed are the ones that would be used by
default in a full MICE imputation run; with the initialonly option,
they are ignored when imputations are produced.

matchpool(#) modifies the implementation of the
match() and lrd options. match performs predictive mean
matching in which a pool of potential
matches is constructed and one member of this pool is sampled (with equal
probabilities). # specifies the size of this pool. The default is 10.
Please note that older versions of ice used # = 1 and later 3.
Users are cautioned against using # = 1.

monotone assumes the members of mainvarlist have a
monotone missingness pattern, that is, ice defines the prediction equations
appropriately. For variables x1, ..., xk the imputation equations
would be x1 on [nothing], x2 on x1, x3 on x1 x2, ... , xk
on x1 x2 ... x(k-1). When the missingness really is monotonic, only
one cycle of MICE is required, so the default here is cycles(1).
There is no advantage in specifying more than one cycle.

With the monotone option,
ice reports a 'non-monotonicity score'. This is defined
as 100 * (sum of numerators) / (sum of denominators), where the sums
are taken over all adjacent pairs of variables in mainvarlist.
Consider two variables, x1 and x2. The numerator for x1 and x2, i.e the
non-monotonicity, is the number of observations in the estimation sample
for which x1 is missing and x2 is observed. If the numerator is
positive, x1 and x2 show a non-monotonic pattern. The denominator
for x1 and x2 is the the number of observations in the estimation sample
for which x2 is observed.

ice takes a relaxed view of runs in which the non-monotonicity
score is positive. It warns the user but goes ahead with the imputation
anyway - it assumes that the user knows what they are doing.

noshoweq suppresses the presentation of the prediction equations.

noconstant suppresses the regression constant in all regressions.

nopp suppresses treatment of the perfect prediction bug
(see Avoiding the perfect prediction bug).

noverbose suppresses display of the imputation number (as #)
and cycle number within imputations (as .) which show
the progress of the imputations.

nowarning suppresses warning messages.

on(varlist) changes the operation of ice in a major way.
With this option, uvis imputes each member of mainvarlist univariately
on varlist. This provides a convenient way of producing multiple imputations
when imputation for each variable in mainvarlist is to be done univariately
on a set of complete predictors.

orderasis enters the variables in mainvarlist into the MICE
algorithm in the order given. The default is to order them according
to the number of missing values: the variable with least missingness
gets imputed first, and so on.

persist causes ice to ignore errors raised by uvis when trying
to impute a "difficult" variable, or impute with a model that is difficult to fit
to the data to hand. Trying to impute a "difficult" variable using the
ologit or mlogit command is the most common cause of failure.
By default, ice stops with an error message. With persist,
ice continues to the next variable to be imputed,
not updating the variable that raised an error. Often, by the play of chance, the
"difficult" variable is successfully updated in a subsequent cycle, and no damage
is done to the imputation process.

If the error for a given variable appears in every cycle, you should consider
changing the prediction equation for that variable, since its imputed values
are unlikely to be appropriate.

We do not recommend the routine use of persist. Only use it when
it appears that there is sporadic failure to fit an imputation model.

restrict([varname] [if]) specifies that imputation models
be computed using the subsample identified by varname and if.

The subsample is defined by the observations for which varname!=0 that
also meet the if conditions. Typically, varname=1 defines the
subsample and varname=0 indicates observations not belonging to the
subsample. For observations whose subsample status is uncertain, varname
should be set to a missing value; such observations are dropped from the
subsample.

By default ice fits imputation models and imputes missing
values using the sample of observations identified in the [if] [in] options.
The restrict() option identifies a subset of this sample to be used
for model estimation. Imputation is restricted to the
sample identified in the [if] [in] options. Thus, predictions and their
associated imputations are made 'out-of-sample' with respect to the subsample
defined by restrict().

Be careful to avoid
restrictions that prevent prediction for all the relevant
observations. For example, models that involve mlogit
will fail to predict 'everywhere' if the restrict() option excludes
any of the levels of the target variable, as in the following example.
school is a four-level categorical variable coded 0, 1, 2, 3:

. gen byte ok = (school > 0) if !missing(school)

. ice school house age sex bcg, clear restrict(ok)

By default, school is imputed using mlogit.
Predictions cannot be made for observations with school==0.
ice will halt with error #303 (equation not found).

seed(#) sets the random number seed to #. In order
to reproduce a set of imputations, the same random number seed should be used.
See Reproducibility of results from uvis and ice
for further comments.
Default #: 0, meaning no seed is set by the program; depending
on the status of Stata's random number seed, different
sets of imputations should be obtained on each run.

substitute(sublist) is typically used with the
passive() option to represent multilevel categorical variables
as dummy variables in models for predicting other variables. See
passive() for more details. The syntax of sublist
is varname:dummyvarlist [,varname:dummyvarlist ...]
where varname is the name of a variable to be substituted and
dummyvarlist is the list of dummy variables representing it.

Note, however, the following important convenience feature:
substitute() may be used without corresponding expressions
in passive() to recreate dummy variables automatically.
If the values of variables in dummyvarlist are NOT defined
through expressions involving varname in the passive() option,
then the variables in dummyvarlist are calculated according to the
actual range of values of varname. For example, suppose the options
passive(x1a:x1==2 \ x1b:x1==3)
and substitute(x1:x1a x1b) were specified. Provided that all
the non-missing values of x1 were 2 when x1a==1 and all
the non-missing values of x1 were 3 when x1b==1, then
passive(x1a:x1==2 \ x1b:x1==3) is implied by substitute(x1:x1a x1b)
and can be omitted. The rule applied by substitute(x:dummy1 [dummy2...])
for defining dummy variables dummy1, dummy2, ... is as follows:

1. Determine the range of values [xmin, xmax] of x for which dummy1 > 0.

2a. If xmin < xmax, define dummy1 to be 1 if xmin <= x <= xmax and 0 otherwise.

2b. If xmin = xmax, define dummy1 to be 1 if x = xmin and 0 otherwise.

3. Repeat steps 1 and 2a,b for dummy2, dummy3, ... as necessary.

With many such categorical variables this feature can save a lot of typing.

trace(trace_filename) monitors the convergence of the imputation
algorithm. For each original variable with missing values, the mean of the
imputed values is stored as a variable in trace_filename, together
with the cycle number at which that
mean was calculated. The results are stored only for the final imputation.
For diagnostic purposes, it is sensible to run trace()
with m(1) and a large number of cycles, such as cycles(100).
When the run is complete, it is helpful to load trace_filename
into memory and plot the mean for each imputed
variable against the cycle number. If necessary, smoothing may be applied
to clarify any apparent pattern. Convergence is judged to have occurred
when the pattern of the imputed means is random.
It is usually obvious from the appearance
of the plot how many cycles are needed for convergence.

uvis

boot invokes a bootstrap method for creating imputed values
(see bootstrap).

by(varlist) performs imputation separately for all combinations of
variables in varlist. Observations with missing values for any
members of varlist are excluded. May be combined with restrict().

gen(newvar) is not optional. newvar contains original
(non-missing) and imputed (originally missing) values of yvar.

lrd creates imputations by local residual draws. This method is related
to predictive mean matching, but the residual is borrowed from one of the
closest non-missing observations, rather than the observed value.

match creates imputations by predictive mean matching. The default is to
draw imputations at random from the posterior distribution of the
missing values of yvar, conditional on the observed values and the members
of xvars. See match for further details.

matchpool(#) - see matchpool for details.

matchtype(#) defines how the uncertainty is represented in choosing the
closest matches for the match and lrd methods. Type 1 matches the
predictive mean for observed values to a draw of the predictive mean for missing
values. Type 2 uses a draw of the prediction for observed and missing values. Type 3
uses a different draw for observed and missing values. Type 1 is recommended.

noconstant suppresses the regression constant in all regressions.

noverbose suppresses non-error messages while uvis is running.

replace permits newvar (see gen(newvar))
to be overwritten with new data. replace may not be abbreviated.

restrict([varname] [if]) specifies that the imputation
model be computed using the subsample identified by varname and if.

The subsample is defined by the observations for which varname!=0 that
also meet the if conditions. Typically, varname=1 defines the
subsample and varname=0 indicates observations not belonging to the
subsample. For observations whose subsample status is uncertain, varname
should be set to a missing value; such observations are dropped from the
subsample.

By default uvis fits the imputation model using the
sample of observations identified in the [if] [in] options.
The restrict() option identifies a subset of this sample.

seed(#) sets the random number seed to #.
See Reproducibility of results from uvis and ice
for comments on how to ensure reproducible imputations
by using the seed() option.
Default #: 0, meaning no seed is set by the program.

Remarks

Algorithm used by uvis

When cmd is regress,
uvis imputes yvar from xvars according to the following algorithm
(see van Buuren et al (1999) section 3.2 for further technical details):

1. Estimate the vector of coefficients (beta) and the residual variance
by regressing the non-missing values of yvar on the current "completed"
version of xvars. Predict the fitted values etaobs at the
non-missing observations of yvar.

2. Draw at random a value (sigma_star) from the posterior distribution of the residual
standard deviation.

3. Draw at random a value (beta_star) from the posterior distribution of beta,
conditional on sigma_star, thus allowing for uncertainty in beta.

4. Use beta_star to predict the fitted values etamis
at the missing observations of yvar.

5. The imputed values are predicted directly from beta_star, sigma_star and the
covariates. For imputation by linear regression,
this step assumes that yvar is Normally distributed, given the covariates.
For other types of imputation, samples are drawn from the appropriate
distribution.

With the match option, step 5 is replaced by the following.
For each missing observation of yvar with prediction etamis,
find the k non-missing observations (where k is the number in
matchpool(#)) of yvar whose prediction
(etaobs) on observed data is closest to etamis. One of the closest
non-missing observations yobs is selected at random and used to impute the
missing value of yvar.

With the lrd option, the closest matches are selected using match. Again,
one of the k closest non-missing observations is selected at random. The
imputed value for a missing observation is etamis + (yobs - etaobs).

The default draw method is not robust to departures from Normality and
may produce implausible imputations. For example, if the original distribution
is skew and positive-valued, the imputed distribution will not necessarily
have the appropriate amount of skewness, nor will all the imputed values
necessarily be positive. Log transformation of positive variables may greatly
improve the appropriateness of the imputations.

The alternative match method is recommended only for continuous variables
when the Normality assumption is clearly untenable, even approximately.
It is not necessary, nor is it implemented, for binary, ordered categorical or
nominal variables. match may work well when the distribution of a
continuous variable is very non-Normal, but it may sometimes result in biased
imputations.

With the boot option, steps 2-4 are replaced by a bootstrap estimation of
beta_star and sigma_star, obtained by regressing yvar on xvars
after taking a bootstrap sample
of the non-missing observations. This has the advantage of robustness since the
distribution of beta is no longer assumed to be multivariate normal.

Note that uvis will not impute observations for which a value
of a variable in xvars is missing. However, all original
(missing or non-missing) observations of yvar will be copied
into newvarname
in such cases. This is a change from the first release
of uvis (with mvis). Previously, newvarname would
be set to missing whenever a value
of a variable in xvars was missing,
irrespective of the value of yvar.

Missing data for ordered (or unordered) categorical covariates should
be imputed by using the ologit (or mlogit) command. match
is neither required nor implemented in these cases.

ice carries out multivariate imputation in mainvarlist using regression
switching (van Buuren et al 1999) as follows:

1. Ignore any observations for which mainvarlist has only missing values, or
if the cc(varlist) option has been specified, for
which any member of varlist has a missing value.

2. For each variable in mainvarlist with any missing data, randomly order that
variable and replicate the observed values across the missing cases. This
step initialises the iterative procedure by ensuing that no relevant values
are missing.

3. For each variable in mainvarlist in turn, impute missing values by applying
uvis with the remaining variables as covariates.

4. Repeat step 3 cycles() times, replacing the imputed values with updated
values at the end of each cycle.

A single imputation sample is created for each variable with any relevant
missing values.

Van Buuren recommends cycles(20) but goes on to say that 10 or even 5
iterations are probably sufficient. We have chosen a compromise default of 10.

"Multiple imputation" (MI) implies the creation and analysis of several
imputed datasets. To do this, one would run ice with m set
to a suitable number, for example 5. To obtain final estimates
of the parameters of interest and their standard errors,
one would fit a model in
each imputation and carry out the appropriate post-MI averaging procedure
on the results from the m separate imputations. A suitable
estimation tool for this purpose is mim.

Handling the outcome variable

To avoid bias, the outcome variable must always be included in the
list of variables to be used for imputation. In survival analysis,
in particular, it is essential to include the censoring indicator
as well as the survival time. van Buuren et al (1999) recommend a
log transformation of the survival time, apparently a heuristic
choice. We have shown (White & Royston 2008)
that for a single binary predictor and a proportional hazards analysis model,
the correct imputation model comprises the baseline
cumulative hazard, the censoring indicator and
the binary predictor. The theory remains approximately valid for a normally
distributed predictor with a weak effect. More complex cases have not
yet been investigated, but at least some guidance is now available.

Handling binary variables

Binary variables present no difficulty. By default, in the MICE
procedure, when such a variable is the response, it is
predicted from other variables by using logistic regression;
when it is a covariate, it is modelled in the only way possible,
effectively as a single dummy variable.

Ensure that binary variables are coded 0/1.
Although, in theory, one could use ologit or mlogit
to model them, in practice there is no advantage in
doing so. Furthermore, do not use the i. prefix with binary variables,
since there is a speed penalty in doing so.

Handling categorical variables

Categorical variables with 3 or more levels may in principle be
treated in different ways. By default, in ice variables
with 3-5 levels are modelled using multinomial logistic regression
(mlogit command) when the response, and as a single linear term
when a covariate. The same behaviour occurs with the ordered logistic model
(ologit command). Our recommended strategy is to use the m.
or o. prefixes for variables to be imputed using unordered or ordered
logistic regression. This approach removes the need to define the
substitute() and passive() options, both of which can be
tedious and error-prone to type.

You should be aware that
unless the dataset is large, use of the mlogit command may produce
unstable estimates if the number of levels is too large, and
may compromise the accuracy of the imputations. It is hard to
predict when this will occur.

Interval censoring

Values of a variable y that are interval censored are imputed under the
assumption that y is normally distributed with unknown mean and variance.
The method, which is fast and efficient, is essentially as described
for right-censored variables in section 3.3 of Royston (2001).
A minor extension to allow left or interval censoring is employed.
For example, if A < y < B and A and B are both finite, the imputed
value for y will follow a truncated normal distribution with bounds
A and B, variance parameter estimated from the data and mean given by the
linear predictor for the imputation model for y. Stata's intreg command
is used to estimate the mean and variance of y. When A and B are both
missing (infinite), imputation of y simply assumes the normal
distribution just mentioned, but without bounds.

If you wish to impose range limits on the imputed values, the lower and upper
bound variables may be set accordingly. For example, to impute right-censored
(e.g. survival) data, you would set llvar equal to all
the observed times to event, whether censored or not, and ulvar to all
the uncensored event times and missing for the censored times.
This would cause the right-censored values to be imputed without restriction.
If you wanted to bound the imputed values above, say by 10,
you would specify ulvar to be 10 (rather than missing) for all
the censored observations.

Avoiding the perfect prediction bug

Perfect prediction may arise in logistic, ologit or
mlogit regression models when a (usually categorical) predictor
variable perfectly predicts success or failure in the outcome variable.
In ice, perfect prediction may occur without the user's knowledge
because a large number of regression models are run silently. Perfect
prediction may lead to entirely inappropriate imputations. To avoid
this, uvis checks for perfect prediction; if it is detected,
uvis temporarily augments the data with a small number of extra observations
with low weight, in such a way as to remove the perfect prediction.
A message is displayed noting the variable that has the
perfect prediction issue, and that the problem has been dealt with.
Such treatment of the perfect prediction bug
may be switched off, if desired, by using the nopp option.

Errors and diagnostics

ice may occasionally detect an anomaly when running
uvis with a particular variable as response and a particular
regression command. ice will then stop and report the uvis
command it was running and the error number returned.
Also, ice saves to a file called _ice_dump.dta
in the working directory a snapshot of the data it was using
when the error occurred, while also reporting the uvis
command it was executing. Sometimes the problem
lies in a regression of a binary or categorical variable where the
estimation procedure fails to converge; this is usually caused by
sparse cell occupancy of the response variable. If you obtain this
error you should either omit the offending variable from the
imputation, or seek to combine a sparse category with another category.

Another possibility is that, again due to a defect in a particular
regression command in the chained equations structure, the number
of values imputed for a particular variable is less than expected.
This is a serious error and again may arise from estimation problems
involving a binary or categorical variable. In this situation, ice
again saves to a file called _ice_dump.dta in the working directory
a snapshot of the data it was using in the attempted estimation,
while reporting the uvis command it was executing.
You can then investigate what may have gone
wrong with the command by loading the data in _ice_dump.dta and
re-running the offending regression command.

Reproducibility of results from uvis and ice

Use of the option seed(#) ensures that a set of
imputed values is reproduced identically for a given value of #.
This is true for both uvis and ice.

Please report to the author any instances where use of ice or uvis
with a fixed seed does not produce the same set of imputed values.

Pitfalls in using the i. prefix

ice commands that include i.varname in mainvarlist
need to be handled with awareness. If varname has no missing data
in the estimation sample, expected results are obtained. If varname
does have missing values in the estimation sample, an error message
is given and ice stops. The "estimation sample" here is the set of
observations for which at least one variable in mainvarlist
has non-missing value(s).

The presence of i. evokes xi, which expands i.varname
in the usual way to create _Ivarname_# dummy
variables. Since varname has no missing data, the
dummy variables are included in the prediction equations for other variables in
mainvarlist, as required.

If i.varname were allowed to have missing data in the
estimation sample,
xi expansion would occur as before, but each of the
_Ivarname_# dummy variables would become a
response variable in a prediction equation and would be predicted
individually (using logistic regression). Worse, the prediction
equation for each dummy variable would include the other dummy
variables from i.varname. That is clearly nonsense.

The advice, as always, is (a) to use dryrun before 'production'
runs if the ice command is at all complex, and then
(b) carefully to check that ice's table of
prediction equations is both sensible and what you expected.

Further notes

ice saves all the variables in the current data to the output,
whether or not they are involved in the imputation procedure.
This can make the resulting dataset very large. It may
therefore be sensible to drop variables not subsequently needed
for modelling before running ice.

ice determines the order of imputing variables in the cycle
of chained equations according to the amount of missing data.
Variables with the least missingness are imputed first. Variables
with the same amount of missingness are processed in an arbitrary
order, but always in the same order.
Note that if ice is run twice using identical variables
(at least two of which have the same amount of missingness) and the same
random number seed, but with the variables with equal missingness
in a different order, slightly different imputations will be
generated. The differences will be purely random and will not produce
bias in subsequent parameter estimates. If the boot() option
is applied to all variables, the order of variables no longer affects
the results.

An important application of MI is to investigate possible models, for example
prognostic models, in which selection of influential variables is required
(Clark & Altman 2003). For example, the stability of the final model across the
imputation samples is of interest. This area of enquiry is in its infancy.

See also Van Buuren's website http://www.multiple-imputation.com for further
information and software sources.

Examples

. uvis regress y x1 x2 x3, gen(ym)

. uvis logit y x1 x2 x3, gen(y) by(x4) restrict(x5) replace noverbose

. uvis intreg ll ul x1 x2 x3, gen(y)

. ice x1 x2 x3, saving(imputed) m(5)

. ice x1 x2 x3, dropmissing monotone clear m(5)

. ice x1 x2 i.x3, clear m(5)

[Note that x3 must have no missing values in the estimation sample]

. ice x1 x2 x3, saving(imputed) m(5) cycles(20) cc(x4 x5)

. ice m.x1 m.x2 o.x3 x4 x5, saving(imputed) m(10) boot(x1 x2 x3) match(x4 x5) id(pid) seed(101) genmiss(M_)

. gen x23 = x2 * x3

. ice o.x1 x2 x3 x23 z1 z2, saving(imputed) m(5) passive(x23:x2*x3) conditional(z1: if z2==0)

. ice y1 y2 y3 x1 x2 x3 x4, saving(imputed) m(5) eq(y1:x1 x2 y2, y2:y1 x3 x4, y3:y1 y2) match(y3)

. ice y1 y2 y3 x1 x2 o.x3 i.x4, saving(imputed) m(5) stepwise swopts(pe(.10) pr(.15) group(x1 x2, y1 i.x4)lock(y2 x3)) match(x3)

. ice x1-x99, clear debug m(1) cycles(100)

. ice x1 x2 x3, saving(imputed) m(5) cmd(x1:ologit) eqdrop(x2:x3, x1:x2)

. ice x1 x2 x3, saving(imputed) m(5) cmd(x1:ologit) match(x2) dropmissing

. ice x1 ll2 ul2 x2 ll3 ul3 x3, saving(imputed) m(5) interval(x2:ll2 ul2, x3:ll3 ul3)

Author

Patrick Royston, MRC Clinical Trials Unit, London.

pr@ctu.mrc.ac.uk

Further reading

van Buuren S., H. C. Boshuizen and D. L. Knook. 1999. Multiple imputation of
missing blood pressure covariates in survival analysis.
Statistics in Medicine 18:681-694.
Also see http://www.multiple-imputation.com.

Carlin J. B., N. Li, P. Greenwood, and C. Coffey. 2003. Tools for analyzing
multiple imputed datasets. Stata Journal 3(3):226-244.

Clark T. G. and D. G. Altman. 2003. Developing a prognostic model
in the presence of missing data: an ovarian cancer case-study.
Journal of Clinical Epidemiology 5628-37.

Royston P. 2001. The lognormal distribution as a model for survival
time in cancer, with an emphasis on prognostic factors.
Statistica Neelandica 55:89-104.

Royston P. 2004. Multiple imputation of missing values.
Stata Journal 4(3):227-241.

Royston P. 2005a. Multiple imputation of missing values: update.
Stata Journal 5: 188-201.

Royston P. 2005b. Multiple imputation of missing values: update of ice.
Stata Journal 5: 527-536.

Royston P. 2007. Multiple imputation of missing values: further
update of ice, with an emphasis on interval censoring.
Stata Journal 7: 445-464.

White I. R. and P. Royston. 2009. Imputing missing covariate values for the Cox
model. Statistics in Medicine 28: 1982-1998.

White I. R., R. Daniel and P. Royston. 2010. Avoiding bias due to perfect
prediction in multiple imputation of incomplete categorical variables.
Computational Statistics and Data Analysis 54: 2267-2275.

Acknowledgements

Ian White has made substantial contributions to the understanding and
practical use of multiple imputation, and to the programming of
ice and uvis. Ian wrote the guts of the draw() option;
the idea and code for coping with perfect prediction are essentially all his.
I am extremely grateful to him for his ongoing commitment to this project.

I am grateful also to Gillian Raab for pointing out certain issues with the prediction
matching approach, particularly that it is only useful with continuous variables.
As a result, the default imputation method has been
changed from matching to drawing from the predictive distribution. Gillian also
suggested imputing the variables in reverse order of the amount of missingness,
and selecting the imputed value at random from the set determined by the available
matching predictions. Both suggestions have been implemented.

Also see

On-line: help for mim (if installed), mi ice (if installed, Stata 11 only).