*! version 1.0.0 2022-5-13

Syntax for predict

Syntax for predictions following a stpm3 model

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

When using the timevar() option, the default is to save predictions to a new frame.
In most cases it is best to use the timevar() option.
See stpm3 predictions guide for details.

Single models:

statistic

centile(options) centiles

crudeprob crude probabilities

cumhazard cumulative hazard function

failure failure function

hazard hazard function

lnhazard ln(hazard) function

rmft restricted mean failure time

rmst restricted mean survival time

survival survival function

xb the full linear predictor

xbnotime the linear predictor (without the effect of time)

Competing risk models:

statistic

cif cumulative incidence function

hazard total hazard function

survival total survival function

options

Main
at1()...atn() covariate values to predict at

atref(#) reference atn option for contrasts

ci calculate confidence intervals

contrast(contrasttype) calculate contrast(s) between at() options

contrastvars(varlist) new variables to be created for contrasts

cpnames(namelist) change names of suffix for crude probability predictions

crmodels(modellist) names of models for competing risk predictions

crnames(namelist) change names of suffix for competing risk predictions

expsurv(options) use expected rates in predictions

frame(framename) frame name for predictions

level(#) sets confidence level (default 95)

merge merge predictions into current dataset rather than a frame

nogen do not generate at() options variables

odeoptions(ode options) ode options for numerical integration

per(#) multiply predictions by #

se calculate standard errors

setbaseline set covariates to their baseline values (or zero)

timevar(varname|# [#]) calculate predictions at specified times

verbose verbose output details

zeros set covariates to zero

Description

predict after stpm3 creates new variables containing predictions with optional standard errors or
confidence intervals.

Using predict with the crmodels() option gives various competing risks measures.
See stpm3_competing_risks.

By default stpm3 adds predictions to a new data frame when using the timevar() option.
The default name for the frame is stpm3_pred, but this can be changed using the
frame() option. It is also possible to add predictions to an existing frame.
If you use the timevar() option, but prefer having predictions in the current dataset, then use the merge option.

When you do not specify the timevar() option then timevar(_t) and merge is assumed.
This means predictions are created in the current dataset.
You can still choose to save results to a frame using the frame() option.

Using the contrast() option enables contrasts between different predictions.
For example, if the prediction type is hazard then you can obtain hazard ratios
using contrast(ratio) when using a minimum of 2 at() options.
Altenatively, using contrast(difference) with the survival option
will give differences in survival functions.

This predict command will give you predictions and contrasts for specific
covariate patterns. If you want marginal predictions then you will need to use the
standsurv command.

Options

Statistic

centile(numlist | varname, options) #th centile of failure distribution.
You can specify this as a numlist, eg centile(25(25)50) will give estimates of
the lower quartile, median and upper quartile of the distribution of failure times.
Centiles are estimated iteratively using Brent's root finder.
There are some suboptions,

centvar(varname) name of variable giving centiles (default centile)

high(#) upper endpoint of the search interval (default 100)

low(#) upper endpoint of the search interval (1e-8)

maxiter(#) maximum number of iterations (default 100).

tol(#) tolerence (default 1e-6).

cif calculates cause-specific cumulative incidence functions in competing risks models.
You must use the crmodels() when using the cif option.

cpnames give the names of the suffixes for crude probability predictions.
The default names are d and o (disease and other).

crnames give the names of the suffixes for competing risks predictions
when using the cif option. The default names are the names of the models
specified in the crmodels() option.

crudeprob calculates crude probabilities for relative survival models.

cumhazard calculates the cumulative hazard function.

failure calculates the failure function, i.e. 1-S(t).

hazard calculates the hazard function.

rmft calculates the restricted mean failure time, i.e the area under the failure function.

rmst calculates the restricted mean survival time, i.e the area under the survival curve.

survival calculates the survival function.

xb calculates the linear predictor. Note this is the full model which includes their
effect of time.

xbnobaseline a synonym for xbnotime

xbnotime calculates the linear predictor for the first equation only.
Note this exclude the effects of time (including any time-dependent effects).
This can be useful to obtain the prognostic index in a prognostic model
(with proportional hazards).

The predictions are at times specified by the timevar() option.

Options

at1(varname # [varname # ..], suboptions)..atn(varname # [varname # ..], suboptions)
specifies covariates to fix at specific values when obtaining predictions.
Note that predictions are conditional on a specified covariate pattern
and all covariates must take a value,
but this may be made easier using the setbaseline or obsvalues options.

There are some suboptions. These are,

atif(expression) restrict predictions to a subset of observations defined by expression.
You will rarely, if ever, want to do this and generally you should use the main if qualifier.

attimevar(varname | # [#], options) specifies or calculates
a specific time variable for each at() option.
This could be useful if you wanted, for example, predictions of survival at 1, 5 and 10 years.
Most of the time it is better to avoid having different time variables in the same frame,
so use the main timevar() option unless you have a good reason not to.

obsvalues sets all covariates not listed in the at() options to their observed values.

setbaseline See main setbaseline option.

toffset(# ..) This option can be used in a competing risks when
you want to offset the time variable by a certain amount. It is most
commonly used in a competing risks setting when the models use different
time scales. For example, cause 1 is time since diagnosis and cause 2 is
attained age. Then using toffset(0 50) would use the original
time scale for cause 1 and predict for a 50 year old for cause 2.

zeros A synonym for setbaseline.

See stpm3 predictions guide for examples.

atreference(#) defines which at() option is the reference category.
By default this is at1(). This is only applicable when making contrasts.
When the contrast is a ratio then the reference is the denominator.
When the contrast is a difference then the reference is the negative term.

ci specifies that confidence intervals are calculated for the predicted statistic.
The upper and lower bounds are generated in newvarname_lci
and newvarname_uci.

contrast(contrastname) calculates contrasts between different predictions
that have been specified using the at() options.
Options are difference and ratio. There will be n-1
new variables created, where n is the number of at() options.
The names default to _contrastk_j where k is the contrast
between atk and atj where the reference can be set using
atreference(). Alternatively, use the contrastsvars() option
to define the names of the contrast variables.

contrastvars(stub | newvarnames) gives the new variables to create when
using the contrast() option. This can be specified as a varlist or a stub,
whereby new variables are named stub1 - stubn-1.

expsurv(suboptions) indicates that expected survial should be calculated
and then combined with the model based (relative) survival estimates to give
all cause survival and other measures. There are a number of suboptions, which are,

agediag(# | varname) gives either a single value, a list of n numbers,
where n is the number of at() options, or a variable
giving the age at diagnosis in years for the predictions.
Note that when using integer age is is assumed that individuals were diagnosed
on their birthday.

datediag(date | varname) gives either a date value or the variable giving
the date at diagnosis for subjects when making predictions.
If you do not have exact dates then you still need to specify this option.
For example, if you had dates in months and years you could use

. gen datediag = mdy(diagmonth,1,diagyear)

to assume all subjects were diagnosed on the 1st of the month.

If you want to use a date value then this can be entered using the "YMD" format.
For example,

datediag(2015-1-1)

exprmstnodes(#) gives the number of nodes used to calculate rmst for
expected survival using Gauss-Legendre quadrature.
The default is 30.

expvars(stub | newvarnames) gives the names of the new variables to be
created for expected survival (survival option), expected hazard (hazard option),
expected life expectency (rmst option)
or the crude probability of death due to other causes
crudeprob option. If not specified these variables will
not be stored. The names can be specified as a varlist equal to the number
of at() options or a stub where new variables are named stub1 -
stubn.

oldexpsurv calculate expected survival / rmst in the old way using ODEs.
Now expected rmst is calculated using Gauss-Legendre quadrature.
Note this is only for expected survival / rmst.

pmage(varname) gives the age variable in the population mortality file.

pmmaxage(varname) gives the maximum age in the population mortality file.
When calculating attained age to merge in the expected mortality rates any record
that is over this maximum will be set to this maximum. The default value is 99.

pmmaxyear(varname) gives the maximum year in the population mortality file.
This is potentially useful when extrapolating. When calculating attained year
to merge in the expected mortality rates any record that is over this maximum
will be set to this maximum.

pmother(other) gives the name of other variables in the population
mortality file. For example, this is usually sex, but can also be region,
deprivation etc.

pmrate(rate) gives the name of the rate variable in the population mortality file.

pmyear(varname) gives the calendar year variable in the population
mortality file.

split(varname) gives the split times when calculating expected survival.
The default is one year.

using(filename) filename of population mortality file.

frame(framename, options) specifies the name of the frame to store the predictions.
The default name is stpm2_pred. Options are,

copy(varlist) copy varlist into framename.

merge merge predictions into frame framename. This will extract the
time variable from the framename automatically.

mergecreate is a convenience option when writing predictions in a loop.
If the frame does not exist it will be created.
If the frame does exists then the timevar() option will be ignored
and predictions merged into framename.

replace replace the existing frame framename if it exists.

merge merge predictions into current dataset rather than a new frame.
This is useful if you want to plot predictions againt covariates in your dataset.

See stpm3 predictions guide for examples.

nogen Does not generate variables for each at() option. This is only
relevent when using the contrast() option and you are not interested
in the predictions for each at option.

odeoptions(options) Various options for ordinary differential equations.
These are used for numerical integration, for example calculation of restricted
mean survival time (rmst) or the survival function prediction for models
on the log(hazard) scale. These options will rarely need changing.

level(#) sets the confidence level; default is level(95) or as set by set level.

abstol(#) absolute tolerance - default 1e-8.

error_control(#) error control when reducing step size - default (5/safety)^(1/pgrow).

initialh(#) initial step size - default 1e-8.

maxsteps(#) maxiumum number of steps - default 1000.

pgrow(#) power using when increasing step size. The default is -0.2.

pshrink(#) power using when decreasing step size. The default is -0.25.

reltol(#) relative tolerance - default 1e-5.

safety(#) safety factor - default 0.9.

tstart(#) lower bound of integration. The deafult is 1e-6.

verbose output details for each step.

per(#) multiplies predictions by #. For example, when predicting
survival per(100) will express results as a percentage rather than a
proportion, or when predicting hazard functions, per(1000) gives results
per 1000 person years (if your time scale is in years of course).

se calculates the standard error for each prediction.
This is stored using the suffix newvarname_se.

setbaseline sets each covariate included in the model to its reference level.
For factor variables this is the term exluded from the model.
For continuous variables the baseline is zero, which may not be sensible.
When using extended functions with the center() option the covariate
value is set to the value of the centering value.

timevar(varname | # [#], options) gives or specifies times at which predictions are required.

If a varname is specified then predictions will be at the values of times
defined in that variable.
If saving to a frame (the default) then any non missing values of this variable will be copied to the new frame.

Using # [#] will calculate a new variable defining the times to predict at.
If only a single value is given, predictions are all at the same time point,
otherwise a range is given.

If 2 values are given the predictions are at a range of values between the two time points.
The default number of observations is 100, but this can be changed using
the n() or step() options.

Options are as follows.
Note the options are only relevant when using two numbers in the timevalues() option.

gen(varname) name of the time variable created. The default is tt.

n(#) the number of values to predict at.

step(#) the step between values of time.

See stpm3 predictions guide for examples.

verbose more detailed output.

zeros This is a synonym for setbaseline.

Remarks

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

Examples

These are very simple examples. For more complex examples see
https://pclambert.net/software/stpm3/.

Load data

webuse brcancer

stset rectime, failure(censrec = 1)

Example 1: Proportional hazards model on log cumulative hazard scale

stpm3 i.hormon, scale(lncumhazard) df(4) eform

range tt 0 7 100

predict S0 S1, surv timevar(tt) at1(hormon 0) at2(hormon 1) ci contrast(difference)

frame stpm3_pred: line S0 S1 tt

Author

Paul C. Lambert

Biostatistics Research Group

Department of Population Health Sciences

University of Leicester

Leicester, UK

and

Department of Medical Epidemiology and Biostatistics

Karolinska Institutet

Stockholm, Sweden

paul.lambert@le.ac.uk

References

P. C. Lambert and P. Royston. Further development of flexible parametric
models for survival analysis. Stata Journal 2009;9:265-290

C. P. Nelson, P. C. Lambert, I. B. Squire and D. R. Jones.
Flexible parametric models for relative survival, with application
in coronary heart disease. Statistics in Medicine 2007;26:5486-5498

P. Royston and M. K. B. Parmar. Flexible proportional-hazards and
proportional-odds models for censored survival data, with application
to prognostic modelling and estimation of treatment effects.
Statistics in Medicine 2002;21:2175-2197.

P. Royston, P.C. Lambert. Flexible parametric survival analysis in Stata: Beyond the Cox model. StataPress, 2011