*! version 1.2.2 27jul2009
help stpm2 (SJ9-2: st0165)

Title

stpm2 -- Flexible parametric survival models

Syntax

stpm2 [varlist] [if] [in], scale(scalename) [options]

Model
scale(scalename) specify scale on which survival model is to be fit

df(#) specify degrees of freedom for baseline hazard function

knots(numlist) specify knot locations for baseline hazard

tvc(varlist) specify varlist of time-dependent effects

dftvc(df_list) specify degrees of freedom for each time-dependent effect

knotstvc(numlist) specify knot locations for time-dependent effects

knscale(scale) specify scale for user-defined knots; default scale is time)

bknots(knotslist) specify boundary knots

noorthog do not use orthogonal transformation of spline variables

bhazard(varname) invoke relative survival models where varname holds expected mortality rate (hazard) at time of death

noconstant suppress constant term

stratify(varlist) for backward compatibility with stpm

theta(est|#) for backward compatibility with stpm

Reporting
alleq report all equations used by ml

eform report exponentiated coefficients

keepcons do not drop constraints used in ml routine

level(#) set confidence level; default is level(95)

showcons list constraints in output

Max options
constheta(#) constrain value of theta

inittheta(#) specify initial value of theta

lininit obtain initial values by first fitting a linear function of ln(time); seldom used

maximize_options control maximization process; seldom used

You must stset your data before using stpm2; see [ST] stset.

Description

stpm2 fits flexible parametric survival models (Royston-Parmar models). stpm2
can be used with single- or multiple-record or single- or multiple-failure st data.
Survival models can be fit on the log cumulative hazard scale, the log cumulative
odds scale, the standard normal deviate (probit) scale, or on a scale defined by the
value of theta using the Aranda-Ordaz family of link functions.

stpm2 can fit the same models as can stpm, but stpm2 is more flexible in that it does
not force the knots for time-dependent effects to be the same as those used
for the baseline distribution function. Also, stpm2 can fit relative survival
models by use of the bhazard() option. Postestimation commands have been extended
over what is available in stpm. stpm2 is noticeably faster than stpm.

See [ST] streg for other (standard) parametric survival models.

Options

Model

scale(scalename) specifies on which scale the survival model is to be
fit.

scale(hazard) fits a model on the log cumulative hazard scale,
i.e., the scale of ln[-ln]. If no time-dependent effects are specified,
the resulting model has proportional hazards.

scale(odds) fits a model on the log cumulative odds scale,
i.e., ln[{1 - S(t)}/S(t)]. If no time-dependent effects
are specified, then this is a proportional-odds model.

scale(normal) fits a model on the normal equivalent deviate
scale, i.e., a probit link for the survival function invnorm{1 - S(t)}.

scale(theta) fits a model on a scale defined by the value of theta
for the Aranda-Ordaz family of link functions, i.e.,
ln[/theta]. theta = 1 corresponds to a
proportional-odds model, and theta = 0 corresponds to a proportional
cumulative-hazard model.

df(#) specifies the degrees of freedom (df) for the restricted cubic
spline function used for the baseline hazard rate. # must be between 1
and 10, but a value between 1 and 5 is usually sufficient.
The knots() option is not applicable if the df()
option is specified. The knots are placed at the following centiles of the
distribution of the uncensored log survival times:

df knots Centile positions

1 0 (no knots)
2 1 50
3 2 33 67
4 3 25 50 75
5 4 20 40 60 80
6 5 17 33 50 67 83
7 6 14 29 43 57 71 86
8 7 12.5 25 37.5 50 62.5 75 87.5
9 8 11.1 22.2 33.3 44.4 55.6 66.7 77.8 88.9
10 9 10 20 30 40 50 60 70 80 90

These are internal knots and there are also boundary knots
placed at the minimum and maximum of the distribution of uncensored survival
times.

knots(numlist) specifies knot locations for the baseline distribution
function, as opposed to the default locations set by df(). The locations of the knots are placed on the scale defined by knscale().
However, the scale used by the restricted cubic spline function is always
log time. Default knot positions are determined by the df() option.

tvc(varlist) specifies the names of the variables that are time dependent.
Time-dependent effects are fit using restricted cubic splines.
The df is specified using the dftvc() option.

dftvc(df_list) specifies the df for time-dependent
effects. The potential df is between 1 and 10. With 1 df, a linear effect of log time is fit. If there is more than one
time-dependent effect and a different df is required for each
time-dependent effect, then the following syntax can be used:
dftvc(x1:3 x2:2 1), where x1 has 3 df, x2 has 2 df, and any
remaining time-dependent effects have 1 df.

knotstvc(numlist) specifies the location of the internal knots for
any time-dependent effects. If different knots are required for different
time-dependent effects, then this option can be specified as follows:
knotstvc(x1 1 2 3 x2 1.5 3.5).

knscale(scale) sets the scale on which user-defined knots are
specified. knscale(time) denotes the original time scale,
knscale(log) denotes the log time scale, and knscale(centile)
specifies that the knots are taken to be centile positions in the distribution
of the uncensored log survival times. The default is knscale(time). The default is knscale(time).

bknots(knotslist) is a two-element list giving
the boundary knots. By default, these are located at the minimum and maximum
of the uncensored survival times. They are specified on the scale defined
by knscale().

noorthog suppresses orthogonal transformation of spline variables.

bhazard(varname) is used when fitting relative survival models.
varname gives the expected mortality rate at the time of death or censoring.
stpm2 gives an error message when there are missing values of
varname, because this usually indicates that an error has occurred when
merging the expected mortality rates.

noconstant;
see [R] estimation options.

stratify(varlist) is provided for backward compatibility with stpm.
Members of varlist are modeled with time-dependent effects. See
the tvc() and dftvc() options for stpm2's way of
specifying time-dependent effects.

theta(est|#) is provided for backward compatibility with
stpm. est requests that theta be estimated, whereas #
fixes theta to #. See constheta() and inittheta() for
stpm2's way of specifying theta.

Reporting

alleq reports all equations used by ml. The models are fit using
various constraints for parameters associated with the derivatives of the
spline functions. These parameters are generally not of interest and thus
are not shown by default. Also, an extra equation is used when fitting
delayed-entry models; again, this is not shown by default.

eform reports the exponentiated coefficients. For models on the log
cumulative-hazard scale, scale(hazard), this gives hazard ratios if
the covariate is not time dependent. Similarly, for models on the log
cumulative-odds scale, scale(odds), this option will give odds ratios
for non-time-dependent effects.

keepcons prevents the constraints imposed by stpm2 on the
derivatives of the spline function when fitting delayed-entry models from
being dropped. By default, the constraints are dropped.

level(#) specifies the confidence level, as a percentage, for confidence
intervals. The default is level(95) or as set by set level.

showcons lists the output the constraints used by stpm2 for the derivatives of the spline function and when fitting delayed-entry models; the default is to not list them.

Max options

constheta(#) constrains the value of theta; i.e., it is treated as a known
constant.

inittheta(#) specifies an initial value for theta in the Aranda-Ordaz
family of link functions.

lininit obtains initial values by fitting only the first spline
basis function (i.e., a linear function of log survival time).
This option is seldom needed.

maximize_options: difficult, technique(algorithm_spec),
iterate(#), [no]log, trace, gradient,
showstep, hessian, shownrtolerance, tolerance(#),
ltolerance(#), gtolerance(#), nrtolerance(#),
nonrtolerance, from(init_specs); see [R] maximize. These
options are seldom used, but the difficult option may be useful if there
are convergence problems when fitting models that use the Aranda-Ordaz family of link
functions.

Remarks

Let t denote time. stpm2 works by first calculating the survival function
after fitting a Cox proportional hazards model. The procedure is
illustrated for proportional hazards models, specified by the
scale(hazard) option. S(t) is converted to an estimate of the log cumulative hazard
function, Z(t), by the formula

Z(t) = ln[-ln]

This estimate of Z(t) is then smoothed on ln(t) by using regression splines with
knots placed at certain quantiles of the distribution of t. The knot positions
are chosen automatically if the spline complexity is specified by the df()
option, or manually by way of the knots() option. (The knots
are placed on values of ln(t), not t.) Denote the predicted values of the log cumulative
hazard function by Z_hat(t). The density function, f(t), is

f(t) = -dS(t)/dt = dS/dZ_hat dZ_hat/dt = S(t) exp(Z_hat) dZ_hat(t)/dt

dZ_hat(t)/dt is computed from the regression coefficients of the fitted spline
function. The estimated survival function is calculated as

S_hat(t) = exp{-exp Z_hat(t)}

The hazard function is calculated as f(t)/S_hat(t).

If varlist is specified, the baseline survival function (i.e., at zero values
of the covariates) is used instead of the survival function of the raw
observations. With df(1), a Weibull model is fit.

With scale(normal), smoothing is of the normal quantile function,
invnorm{1 - S(t)}, instead of the log cumulative-hazard function. With
df(1), a lognormal model is fit.

With scale(odds), smoothing is of the log odds-of-failure function,
ln[{1 - S(t)}/S(t)], instead of the log cumulative-hazard function. With
df(1), a loglogistic model is fit.

Estimation is performed by maximum likelihood. Optimization uses the
default technique, nr (meaning Stata's version of Newton-Raphson
iteration).

Examples

Setup

webuse brcancer

stset rectime, failure(censrec = 1)

Proportional hazards model

stpm2 hormon, scale(hazard) df(4) eform

Proportional odds model

stpm2 hormon, scale(odds) df(4) eform

Time-dependent effects on cumulative hazard scale

stpm2 hormon, scale(hazard) df(4) tvc(hormon) dftvc(3)

User-defined knots at centiles of uncensored event times

stpm2 hormon, scale(hazard) knots(20 50 80) knscale(centile)

Author

Paul C. Lambert

Centre for Biostatistics and Genetic Epidemiology

Department of Health Sciences

University of Leicester, UK

paul.lambert@le.ac.uk

Also see

Article: Stata Journal, volume 9, number 2: st0165

Online: stpm2_postestimation; [ST] stset, stpm (if
installed)