*! version 1.0.0

Title

stpm3 -- Flexible parametric survival models

See "https://pclambert.net/software/stpm3/,
for some examples.

Syntax

stpm3 [extended varlist] [varlist] [if] [in]
[, options]

allknots(numlist) knot locations for baseline hazard

allknotstvc(numlist) knot locations for time-dependent effects

bhazard(varname) relative survival models with backgound rates varname

bknots(# #) location of boundary knots

bknotstvc(# #) location of boundary knots for time-dependent effects

degree(#) degree when using B-splines

df(#) degress of freedom for the baseline hazard

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

integoptsions(options) different options for numerical integration

knots(numlist) knot locations for baseline hazard

knotstvc(numlist) knot locations for time-dependent effects

mladoptsions(options) pass specifc options to mlad

offset(varname) include offset

noconstant suppress constant term

python Use python to estimate parameters (loghazard scale models)

scale(scalename) scale on which the survival model is
to be fitted

splinetype(splinetype) type of spline for modelling effect of time

ttrans(function) transformation of time

tvc([extended] varlist) variables with time-dependent effects

tvcoffset(list) time offset for time-dependent effects

Reporting
eform exponentiate coefficients

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

neq(#) number of equations to display.

verbose verbose output details

Estimation options
initmodel(modeltype) model used for initial values

initmodelloop loop over different inital model types

mlmethod(method) estimation method

nodes(#) number of nodes for Gauss-Legendre integration

maximize_options control the maximization process; seldom used

Description

stpm3 fits a a range of flexible parametric survival models using splines.
These include models on the following scales,
log cumulative hazard, log odds, probit and log hazard.

stpm3 fits similar models to stpm2. In addition, stpm3 is fully
compatible with factor variables, supports extended functions
and has improved postestimation functionality.

With the bhazard() option, stpm3 fits relative survival models.

Tutorials

For some tutorials and examples, see
https://pclambert.net/software/stpm3/.

Options

Model

allknots(# [# ...]) specifies knot locations for the baseline function,
as opposed to the default locations set by df().
This option lists all knots including boundary knots.
When specifying the knots, these are defined on the time scale by default.
When stpm3 uses a log transformation of time, the values inputted will
be log transformed. Alternatively, the knots can be specified on the log scale using
the lntime suboption or as percentiles of the distribution of event times
using the percentile suboption.

allknotstvc(numlist) or allknotstvc(varname # [#..#] ... varname # [#..#])
defines the knot locatations for time-dependent effects.
This option lists all knots including boundary knots.
The first syntax uses the same knots positions for all variables listed in tvc().
The second syntax allows different knot positions to be specified for each
variable included in tvc().

bhazard(varname) is used when fitting relative survival models.
varname gives the expected mortality rate (hazard) at the time of death/censoring.
stpm3 gives an error message when there are missing values of varname,
since usually this indicates an error has occurred when merging the
expected mortality rates with the time to death/censoring.

bknots(#1 #2, [options]) specifies the locacation of the boundary knots.
By default these are placed at the minimum and maximum events times.
Note that when specifying #1 and #2 these are defined on the time scale by default.
When stpm3 uses a log transformation of time, the values inputted will
be log transformed. Alternatively, #1 and #2 can be specified on the log scale using
the lntime suboption or as percentiles of the distribution of event times
using the percentile suboption.

bknotstvc(#1 #2) specifies the locacation of the boundary knots
for any variables defined in the tvc() option.
By default these are placed at the minimum and maximum events times.
Note it is not currently possible to define these to be different
for different variables specified in tvc().

degree(#) (for B-splines only) gives the degree of the B-spline function.
Default is degree(3).

df(#) specifies the degrees of freedom for the spline function used
for the baseline function.
When using df(#), knots are placed at evenly spread centiles of the
distribution of the uncensored log event times.
The number of internal knots will be # - 1.
With 1 degree of freedom,
no knots are involved and a linear or log-linear effect of time is imposed.

dftvc(#) or dftvc(varname # ... varname #) gives the degrees of freedom
for time-dependent effects.
If using the first syntax, dftvc(#), then the save degrees of fredom
are used for any covariates listed in the tvc() option.
If using the second syntax, separate degrees of freedon can be listed for
each covriate listed in the tvc() option.

knots(# [# ...]) specifies internal knot locations for the baseline function,
as opposed to the default locations set by df().
When specifying the knots, these are defined on the time scale by default.
When stpm3 uses a log transformation of time, the values inputted will
be log transformed. Alternatively, the knots can be specified on the log scale using
the lntime suboption or as percentiles of the distribution of event times
using the percentile suboption.

knotstvc(numlist) or knotstvc(varname # [#..#] ... varname # [#..#])
defines the internal knot locatations for time-dependent effects.
The first syntax uses the same knots positions for all variables listed in tvc().
The second syntax allows different knot positions to be specified for each
variable included in tvc().

integoptions(options) This controls numerical integration options when fitting
models on the log hazard scale.
When the spline functions are a function of log time the default method is
tanhsinh quadrature and when the spline functions are a function of
untransformed time Gauss-Legendre (gl) quadrature is the default.
Three part integration is the default for both tanh-sinh quadrature and
Gauss-Legendre quadrature, where analytical derivatives
are used before the lowest knot and after the highest knot, with numerical
integration used between the lowest and highest knots.
This can be overridden with the allnum option, where numerical integration
is used over the whole time scale.

mladoptions(options) Pass various options to mlad (see mlad). This was mainly
used when developing the python option, so will not be relevant for
most users.

offset(varname) This is not currently implemented and will result in an error.

noconstant excludes the constant from the model.

python will use Python to to do some of the more computationally intensive
methods for models on the loghazard scale. To use this option, you need to have
installed the mlad command from SSC as well as have installed Python
and some specific Python modules. See https://pclambert.net/software/mlad/
for more details.

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

scale(lncumhazard|logcumhazard) or scale(logcumhazard) fit a model on the log cumulative hazard scale,
i.e. ln(-ln S(t)), where S(t) is the
survival function.
If no time-dependent effects are specified,
the model has proportional hazards.
With 1 df this is equivalent to a Weibull model.

scale(lnhazard|loghazard) or scale(loghazard) fit a model on the log hazard scale,
i.e. ln[h(t)]. If no time-dependent effects are specified,
the model has proportional hazards.

scale(lnodds) or scale(logodds) fit a model on the log cumulative odds scale,
i.e. ln((1 - S(t))/S(t)). If no time-dependent effects
are specified the model has proportional odds.
With 1 df this is equivalent to a loglogistic model.

scale(probit) or scale(probit) fit a model on the
with a probit link function for the survival function, invnorm(1 - S(t))).
With 1 df this is equivalent to a lognormal model.

splinetype(splinetype) defines the type of spline used to model the effect of time.

splinetype(ns) specifies natural cubic splines. This is the default.

splinetype(bs) specifies B-splines. The degree() option specifies the degree of the B-spline.

splinetype(rcs) specified restricted cubic splines, which give the same predicted values as splinetype(ns). Since the spline basis functions are calculated in different ways the associated coefficents will differ.

ttrans(function) defines the function of time used as an argument for the spline function. The default function is log. ttrans(none)
uses untransformed time.

tvc(varlist) gives the names of the variables whose effects are
to be modelled as time-dependent.
Time-dependent effects are fitted using the same spline function type as the baseline.
The degrees of freedom are determined by dftvc().

tvcoffset(list) is not currently implemented.

Reporting

eform displays the exponentiated coefficients and corresponding standard errors
and confidence intervals for xb equation.

level(#) see
[R] Estimation options.

neq(#) number of equations to display.
In a model with covariates neq(1) omits the coefficients associated with
the spline parameters and neq(0) omits all coeficients and just
displays summary information.

verbose gives some details about the progress in the setup/estimation process.
This was useful when developing/debugging the command.

Maximization/Estimation

initmodel(modeltype) defines the model used to obtain initial values.
Options are cox (default), weibull, exp and stpm2.

initvaluesloop searches for initial values over several modeltypes.

see [R] Maximize for other maximization options.

Examples

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

You can click on the commands below to run the commands, but will need to
clear data from memory before using webuse

Load data and set time-scale to years (days/365.24)

webuse brcancer

stset rectime, failure(censrec = 1) scale(365.24)

Example 1: Proportional hazards model on log cumulative hazard scale

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

Example 2: Proportional hazards model on log hazard scale

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

Example 3: Proportional odds model

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

Example 4: log hazard model using quadratic B-splines

stpm3 i.hormon, scale(lnhazard) df(4) splinetype(bs) degree(2) eform

Example 5: log hazard model using natural splines with interaction with time

stpm3 i.hormon, scale(lnhazard) df(4) tvc(i.hormon) dftvc(3)

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