*! version 1.0.0 ?????2018

Syntax for predict

Syntax for predictions following a merlin model

predict
newvarname
[if] [in] [,
statistic
options]

The default is to make predictions based only on the fixed portion of the
model.

Syntax for obtaining estimated latent variables and their standard errors

predict
newvarsspec
[if] [in]
,
[reffects reses]

where newvarsspec is stub* or newvarlist.

statistic

Main
mu expected value of depvar; the default

eta expected value of complex predictor

density density function

survival survivor function

totalsurvival all-cause survivor function

cif cumulative incidence function

hazard hazard function

chazard cumulative hazard function

logchazard log cumulative hazard function

rmst restricted mean survival time, within (0,t]

timelost time lost due to an event, within (0,t]

totaltimelost total time lost due to all events, within (0,t]

userfunction(func_name) user-defined Mata function

mudifference difference in expected values of depvar

etadifference difference in expected value of complex predictor

hdifference difference in hazard functions

sdifference difference in survival functions

cifdifference difference in cumulative incidence functions

rmstdifference difference in restricted mean survival functions

muratio ratio of expected values of depvar

etaratio ratio of expected value of complex predictor

hratio ratio of hazard functions

sratio ratio of survival functions

cifratio ratio of cumulative incidence functions

rmstratio ratio of restricted mean survival functions

reffects empirical Bayes means of latent variables

reses standard errors of empirical Bayes estimates

options

Main
fixedonly compute statistic based only on the fixed portion of the model; the default

marginal compute statistic marginally with respect to the latent variables

standardise compute statistic marginally with respect to the independent variables

outcome(#) specify observed response variable (default 1)

causes(numlist) specify which merlin submodels contribute to the statistic

at(at_spec) specify covariate values for prediction

zeros set all covariates to zero

at1(at_spec) specify covariate values for prediction; for use with difference and ratio predictions

at2(at_spec) specify covariate values for prediction; for use with difference and ratio predictions

ci calculate confidence intervals

reps(#) number of bootstrap samples for cis; see details

timevar(varname) calculate predictions at specified time-points

ltruncated(varname) calculate conditional predictions

Integration
intpoints(#) use # integration points to compute marginal predictions

chintpoints(#) use # integration points when computing cumulative hazard functions

Description

predict is a standard postestimation command of Stata.
This entry concerns use of predict after merlin.

predict after merlin creates new variables containing
observation-by-observation values of estimated observed response variables,
linear predictions of observed response variables, or other such functions.

Options

Statistic

mu, the default, calculates the expected value of the outcomes.

eta calculates the fitted linear prediction.

density calculates the density function. This prediction is computed
using the current values of the observed variables, including the dependent
variable.

survival calculates the survival function. If you have fitted a competing risks model, then this will represent
cause-specific survival. If you have fitted a relative survival model, then this will represent the relative
survival function.

totalsurvival calculates the all-cause survival function at time t, where t is the time at which predictions are made.
In a single event survival model, this is the same as survival.
In a competing risks merlin model, all survival models in the fitted merlin model are assumed to
be cause-specific event time models contributing to the calculation. If this is not the case, you can tell predict which
of the models are cause-specific hazard models by using the causes() option.

cif calculates the cumulative incidence function at time t, where t is the time at which predictions are made.
In a single event survival model, this is 1 - survival.
In a competing risks merlin model, all survival models in the fitted merlin model are assumed to
be cause-specific event time models contributing to the calculation. If this is not the case, you can tell predict which
of the models are cause-specific hazard models by using the causes() option.

hazard calculates the hazard function at time t, where t is the time at which predictions are made.

chazard calculates the cumulative hazard function at time t, where t is the time at which predictions are made.

logchazard calculates the log of the cumulative hazard function at time t, where t is the time at which predictions are made.

rmst calculates the restricted mean survival time, which is the integral of the survival function within the interval
(0,t], where t is the time at which predictions are made. If multiple survival
models have been specified in your merlin model, then it will assume all of them are cause-specific competing risks models,
and include them in the calculation. If this is not the case, you can override which models are included by using the causes()
option. rmst = t - totaltimelost.

timelost calculates the time lost due to a particular event occuring, within the interval (0,t].
In a single event survival model, this is the integral of the cif between (0,t].
If multple survival models are specified in the merlin model then by default all are assumed to be cause-specific
event time models contributing to the calculation. This can be overridden using the causes() option.

totaltimelost calculates the total time lost due to any event occuring, within the interval (0,t].
In a single event survival model, this is the integral of the cif between (0,t], and will be equivalent
to timelost. If multiple survival models are specified in the merlin model then by default all are
assumed to be cause-specific event time models contributing to the calculation. This can be overridden using
the causes() option. totaltimelost is the sum of the timelost due to all causes.

userfunction(func_name) calculates a user-defined prediction, based on a Mata function passed to predict. See
merlin user-defined functions for more info.

mudifference calculates the difference in the expected value of the outcomes,
across the covariate patterns specified in at1() and at2().

etadifference calculates the difference in the expected value of the complex predictor,
across the covariate patterns specified in at1() and at2().

hdifference calculates the difference in hazard function at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

sdifference calculates the difference in survival function at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

cifdifference calculates the difference in cumulative incidence function at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

rmstdifference calculates the difference in restricted mean survival time at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

muratio calculates the ratio of the expected value of the outcomes,
across the covariate patterns specified in at1() and at2().

etaratio calculates the ratio of the expected value of the complex predictor,
across the covariate patterns specified in at1() and at2().

hratio calculates the ratio of hazard functions at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

sratio calculates the ratio of survival functions at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

cifratio calculates the ratio of cumulative incidence functions at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

rmstratio calculates the ratio of restricted mean survival times at time t, where t is the time at which predictions are made,
across the covariate patterns specified in at1() and at2().

reffects calculates empirical Bayes estimates (posterior means) of the
random effects. You must specify q new variables, where q is the number of random-effects terms
in the model (or level). However, it is much easier to just specify
stub* and let Stata name the variables stub1,
stub2, ..., stubq for you.

reses
calculates the standard errors of the empirical Bayes etsimates of the random effects. You must specify q new variables,
where q is the number of random-effects terms in the model (or level). However, it is much easier to
just specify stub* and let Stata name the variables
stub1, stub2, ..., stubq for you.

The reffects and reses options often generate multiple new
variables at once. When this occurs, the random effects (or standard
errors) contained in the generated variables correspond to the order in which
the variance components are listed in the output of merlin.

Options

causes(numlist) is for use when calculating predictions from a competing risks merlin model. By default,
cif, rmst, timelost and totaltimelost assume that all survival models included in the merlin
model are cause-specific hazard models contributing to the calculation. If this is not the case, then you can specify which
models (indexed using the order they appear in your merlin model, e.g. causes(1 2)), by using the causes()
option.

fixedonly specifies that the predicted statistic be computed
based only on the fixed portion of the model. This is the default.

marginal specifies that the predicted statistic be computed
marginally with respect to the latent variables.

Although this is not the default, marginal predictions are often very useful
in applied analysis. They produce what are commonly called
population-averaged estimates.

For models with continuous latent variables, the statistic is calculated
by integrating the prediction function with respect to all the latent
variables over their entire support.

standardise specifies that the predicted statistic be computed
marginally with respect to the independent variables. This is implemented by calculating the statistic
at all observed covariate patterns, and taking the average. Can be used in combination with at(), or at1() and
at2() to obtain causal estimands/contrasts.

outcome(#) specifies that predictions for
outcome # be calculated.

at(varname # [ varname # ...]) requests that the covariates specified by
the listed varname(s) be set to the listed # values. For example,
at(trt 1 age 50) would evaluate predictions at trt = 1 and
age = 50. This is a useful way to obtain out of sample predictions. Other covariates in your model, but
not included in at() will be set to their observed values, i.e. the values in your dataset. Note that if at()
is used together with zeros, all covariates not listed in at() are set to zero. See also zeros.

zeros sets all covariates to zero. See also at(). Note, any response variables will be skipped, i.e. not set
to zero, so if a response variable for one model is included as a covariate in another - it will not be set to zero. Also note
that it at1() and at2() are specified, then zeros applies to both.

at1(varname # [ varname # ...]) does the same as at() but for use in conjunction with ?difference or
?ratio predictions.

at2(varname # [ varname # ...]) does the same as at() but for use in conjunction with ?difference or
?ratio predictions.

ci specifies that confidence intervals are calculated for the predicted statistic. The multivariate delta
method (i.e. predictnl) is used for all calculations, except when a family(cox) model has been fitted,
in which case boostrapping is used. The calculated confidence intervals are generated in newvarname_lci
and newvarname_uci.

reps(#) specifies the number of bootstrap samples to use when calculating confidence intervals for a prediction
from a family(cox) model. Default is reps(100).

timevar(varname) calculate predictions at specified time-points.
For survival models, the default is to calculate predictions at the evemt/censoring times.
For a merlin model where a timevar() was specified, then the default will use the original
timevar(). This option overides it.

ltruncated(varname) calculates left-truncated, conditional predictions, e.g., S(t|t0), where t0 is defined by the times in
ltruncated(). Only allowed with survival or cif.

Integration

intpoints(#) specifies the number of integration points used to
compute marginal predictions; the default is the value from estimation.

chintpoints(#) defines the number of Gauss-Legendre integreation (quadrature) points used to calculate analytically intractable
cumulative hazard functions; the default is the value from estimation.

Remarks

Out-of-sample prediction is allowed for all predict options.

Example 1

Setup

. use http://fmwww.bc.edu/repec/bocode/s/stjm_pbc_example_data, clear

Linear mixed effects model with merlin

. merlin (logb time age trt time#M1[id]@1 M2[id]@1, family(gaussian))

Predict the expected value of logb marginalised over the random effects

. predict ev1, eta marginal

Example 2

Fit a Royston-Parmar flexible parametric model:

. webuse brcancer,clear

. stset rectime, failure(censrec) scale(365)

. merlin (_t hormon, family(rp, df(3) failure(_d)))

Predict the survival function

. predict s1, survival

Predict the conditonal survival function at user-defined times

. range tvar 5 10 100

. gen t0 = 5

. predict s2, survival timevar(tvar) ltruncated(t0)

Author

Michael J. Crowther

Red Door Analytics

Stockholm, Sweden

michael@reddooranalytics.se

References

Crowther MJ. Extended multivariate generalised linear and non-linear mixed effects models.
https://arxiv.org/abs/1710.02223

Crowther MJ. merlin - a unified framework for data analysis and methods development in Stata. Stata Journal 2020;20(4):763-784.

Crowther MJ. Multilevel mixed effects parametric survival analysis: Estimation, simulation and application. Stata Journal 2019;19(4):931-949.

Crowther MJ, Lambert PC. Parametric multi-state survival models: flexible modelling allowing transition-specific distributions with
application to estimating clinically useful measures of effect differences. Statistics in Medicine 2017;36(29):4719-4742.

Weibull CE, Lambert PC, Eloranta S, Andersson TM-L, Dickman PW, Crowther MJ. A multi-state model incorporating
estimation of excess hazards and multiple time scales. Statistics in Medicine 2021;40(9):2139-2154.