*! version 1.4 19Feb2016
help strcs
also see: strcs_postestimation

Title

strcs -- Flexible parametric survival models on the log hazard scale

Syntax

strcs [varlist] [if] [in] [, options]

Knot selection options
bknots(numlist) boundary knots for baseline

bknotstvc(knots list) boundary knots for time-dependent effects

df(#) degrees of freedom for baseline hazard function

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

knots(numlist) internal knot locations for baseline hazard

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

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

tvc(varlist) varlist of time varying effects

Estimation options
bhazard(varname) invokes relative survival models where varname
holds the expected mortality rate (hazard) at the time of death

bhtime smooth the baseline hazard over time (default is log time)

noconstant suppress constant term

nodes(#) specify the number of nodes used in Gauss-Legendre quadrature numerical
integration of the hazard function (default is 30)

noorthog do not use orthogonal transformation of splines variables

offset(varname) specifies a variable whose coefficient is constrained to be 1

reverse calculate the splines in reverse order

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

nohr do not report hazard ratios

verbose verbose output details the process of the strcs program

Maximization options
from(matrix) initial coefficient values stored in a matrix

inith(varlist) initial hazard values

maximize_options control the maximization process; seldom used

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

fweights, iweights, and pweights may be specified using stset; [ST] stset.

Description

strcs fits flexible parametric survival models (Royston-Parmar models) on the log hazard scale. strcs can be used with single- or multiple-record or
single- or multiple-failure st data.

See [ST] stpm2 for flexible parametric survival models on the log cumulative hazard scale.

Options

Knot selection options

bknots(knots_list) knots_list is a two-element numlist 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().

bknotstvc(knots_list) knots_list gives the boundary knots for
any time-dependent effects. By default these are the same as for the bknots
option. They are specified on the scale defined by knscale().

For example,

bknotstvc(x1 0.01 10 x2 0.01 8)

df(#) specifies the degrees of freedom for the restricted
cubic spline function used for the baseline function; the number of degrees of
freedom does not include the constant term. # must be between
1 and 10. The knots() option is not applicable if the df() option
is specified. The knots are placed at equally spaced centiles of the distribution
of the uncensored log survival times. For example, for df(5) knots are
placed at the 20th, 40th, 60th and 80th centiles of the distribution of the
uncensored log survival times. Note that these are interior knots and
there are also boundary knots placed at the minimum and maximum of the distribution
of uncensored survival times.

dftvc(df_list) gives the degrees of freedom for time-dependent effects
in df_list. With 1 degree of freedom a linear effect is fitted.
If there is more than one time-dependent effect and different degrees of freedom
are requested for each time-dependent effect then the following syntax applies:

dftvc(x1:3 x2:2 1)

This will use 3 degrees of freedom for x1, 2 degrees of freedom for
x2 and 1 degree of freedom for all remaining time-dependent effects.

knots(# [# ...]) specifies internal knot locations for the baseline distribution
function, as opposed to the default locations set by df(). Note that
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 unless the bhtime option is specified. Default knot positions are determined by the df() option.

knotstvc(knots_list) defines numlist knots_list as the location
of the interior knots for time-dependent effects. If different knots
are required for different time-dependent effects the option is
specified, for example, 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) the
log time scale and knscale(centile) specifies that the knots
are taken to be centile positions in the distribution of the uncensored
survival times, or log survival times depending on whether the bhtime option
is specified. The default is knscale(time).

tvc(varlist) gives the name of the variables that are time-dependent.
Time-dependent effects are fitted using restricted cubic splines.
The degrees of freedom are specified using the dftvc() option.

Estimation options

bhazard(varname) invokes a relative survival model where varname holds the expected
mortality rate (hazard) at the time of death/censoring.

bhtime smoothes the estimated log hazard function over time using restricted cubic splines.
By default, smoothing is over log time.

noconstant;
see [ST] estimation options.

nodes(#) specifies the number of nodes to be used in Gauss-Legendre quadrature
numerical integration when calculating the estimated cumulative hazard function
from the estimated hazard function. The default number of nodes is 30. Changing the
number of nodes may be useful if there are convergence problems. Too few nodes
may result in a poor approximation involved in the numerical integration. Analyses should
be performed to ensure the results are not sensitive to the number of nodes.

noorthog suppresses orthogonal transformation of spline variables.

offset specifies a variable whose coefficient is constrained to be 1.

reverse specifies that the splines be calculated backwards. See Andersson
et al. for details of the approach.

Reporting

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

nohr reports the coefficients instead of hazard ratios.

verbose verbose output details the process of the strcs program.

Maximization options

from(matrix) defines the matrix containing initial coefficient estimates to be used in maximum
likelihood estimation. By default strcs estimates initial hazard estimates by fitting a model
on the log cumulative hazard scale using the stpm2 command.

inith(varlist) defines initial hazard estimates to be used in maximum likelihood
estimation. By default strcs estimates initial hazard estimates by fitting a model on the
log cumulative hazard scale using the stpm2 command.

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.

Remarks

Let t denote time. strcs works by first fitting a flexible parametric survival
model on the log cumulative hazard scale using the stpm2 command. The predicted hazard
from this model is used to estimate initial values of the log hazard with specified
covariates. These initial values are used within the maximum likelihood estimation.

The log hazard estimate, ln(h_hat(t)), is smoothed on ln(t), or t if bhtime is
specified, using restricted cubic 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 cumulative hazard function, H(t), is required in order to maximise the likelihood and
fit the model. The cumulative hazard function can be estimated by integrating the
hazard estimate. The hazard cannot be integrated analytically due to its complexity, thus it
must be integrated numerically. Integration is performed as a two-part process to reduce
computational time. The hazards prior to the first, and after the last knots can be integrated
analytically; numerical integration is only performed between the first and the last knots by
Gauss-Legendre quadrature. The number of nodes used within Gauss-Legendre quadrature can be
specified using the nodes(#) option.

The survival function is calculated as

S_hat(t) = exp(-exp H_hat(t)).

With df(1) a Weibull model is fitted.

Estimation is performed by maximum likelihood. Optimisation 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

strcs hormon, df(4)

Time-dependent effects on the log hazard scale

strcs hormon, df(4) tvc(hormon) dftvc(3)

User defined knots at centiles of uncensored event times

strcs hormon, knots(20 50 80) knscale(centile)

Stored results

strcs stores the following in e():

Scalars

e(rank) rank of e(V)

e(N) number of observations

e(ic) number of iterations

e(k) number of parameters

e(k_eq) number of equations in e(b)

e(k_dv) number of dependent variables

e(converged) number of observations

e(rc) return code

e(ll) log likelihood

e(k_eq_model) number of equations in overall model test

e(dfbase) degrees of freedom specified for baseline hazard function

e(df_varname) degrees of freedom specified for the time-dependent effect of varname

e(minknot) value of minimum knot

e(maxknot) value of maximum knot

e(nodes) number of nodes used in numerical integration

e(dev) deviance

e(AIC) Akaike information criterion

e(BIC) Bayesian information criterion

Macros

e(cmdline) command as typed

e(cmd) strcs

e(predict) strcs_pred

e(varlist) variables included in the model

e(depvar) _d _t

e(rcsterms_base) name of spline terms used to model the baseline hazard function

e(bhknots) value of the knots used to model the baseline hazard function

e(exp_bhknots) exponential of the knots used to model the baseline hazard function

e(tvc) variables with time-dependent effects

e(rcsterms_varname) name of spline terms used to model the time-dependent effect for varname

e(tvcknots_varname) value of the knots for the time-dependent effect of varname

e(exp_tvcknots_varname) exponential of the knots fot the time-dependent effect of varname

e(bhazard) name of the expected hazard rate used if a relative survival model is fitted

e(bhtime) bhtime if time is modelled rather than the default of log time

e(noconstant) noconstant if constant term was supressed

e(orthog) orthog if splines were orthogonalized

e(reverse) reverse if splones are calculated in reverse order

e(opt) type of optimization

e(vce) vcetype specified in vce()

e(user) name of likelihood-evaluator program

e(ml_method) type of ml method

e(technique) maximization technique

e(which) max or min; whether optimizer is to perform maximization or minimization

e(properties) b V

Matrices

e(b) coefficient vector

e(V) variance-covariance matrix of estimators

e(Cns) constraints matrix

e(R_bh) orthogonlization matrix

e(ilog) iteration log

e(gradient) gradient vector

e(R_varname) orthogonalization matrix for splines of time-dependent effect varname

Functions

e(sample) marks estimation sample

Author

Hannah Bower,Karolinska Institutet, Stockholm, Sweden.
(hannah.bower@ki.se)

Paul Lambert, University of Leicester, UK.
(paul.lambert@leicester.ac.uk)

Michael Crowther, University of Leicester, UK and Karolinska Institutet, Stockholm, Sweden.
(michael.crowther@le.ac.uk)

References

T. M-L. Andersson, P.W Dickman, S. Eloranta and P. C. Lambert. Estimating and modelling
cure in population-based cancer studies within the framework of flexible parametric survival
models. BMC Medical Research Methodology 2011;11:96.

M. J. Crowther and P. C. Lambert. A general framework for parametric survival analysis.
Statistics in Medicine 2014;33:5280-5297.

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

Also see

Online: [ST] strcs_postestimation;