*!Paul C. Lambert 21Nov2016
help stpm2_standsurv
also see: stpm2 stpm2_postestimation

Title

stpm2_standsurv -- Post-estimation tool to estimate standardised survival curves and contrasts

Syntax

stpm2_standsurv [, options]

at1()...atn() fix specific covariate values for each cause

atvars() the new variable names (or stub) for each atn() option

atreference() the reference atn() option (default 1)

centile(numlist) centiles of the standardised survival function

centileupper(#) upper starting value when calculating centiles

centvar() the new variable to denote centiles

ci calculates confidence intervals for each atn() option and for contrasts

contrast() perform contrast between covariate patterns defined by atn() options

contrastvars() the new variable names (or stub) for each contrast

failure calculate standardised failure function (1-S(t))

hazard calculate hazard function of standardised survival curve

indweights(varname) variable containing weights (for external standardisation)

lincom linear combination of at options

level(#) sets confidence level (default 95)

mestimation use M-estimation for standard errors & confidence intervals

nodes(#) number of nodes for numerical integration (default 30)

rmst calculate restricted mean survival time

se calculates standard errors for each atn() option and for contrasts

timevar() time variable used for predictions (default _t)

transform() transformation to calculate standard errors when obtaining confidence intervals

userfunction() user defined function

userfunctionvar() the new variable names (or stub) for each user defined function

Description

stpm2_standsurv can be used after stpm2 to obtain standardised (average) survival curves and
contrasts between standardised curves. It is similar to the meansurv option of stpm2's predict command,
but allows multiple at options and contrasts (differences or ratios of standardised survival curves). It is
substantially faster than performing contrasts using predictnl with meansurv as partial derivatives are calculated analytically. It can use either the delta-method
or M-estimation (Stefanski and Boos 2002) to calculated standard errors and hence confidence intervals.

In addition, stpm2_standsurv will calculate various functions of the standardised survival curves. These are the hazard function, the restricted mean survival time
(area under the survival curve), and centiles of the standardised curve. Contrasts can be made between any of these measures (differences, ratios or percentage differences).
The delta-method is the default for obtaining standard errors with the exception of obtaining centiles (and their contrasts) where only
M-estimation can be used.

Options

at1(varname # [varname # ..])..atn(varname # [varname # ..])
specifies covariates to fix at specific values when averaging survival curves.
For example, if x denotes a binary covariate and you want to standardise
over all other variables in the model then using at1(x 0) at2(x 1) will give
two standardised survival functions, one where x=0 and one where x=1.

Using at1(.) will calculated the standardized quanity with all observations set to their observed values.

It can be sometimes be useful to set certain variables to take the values of a different covariate. This can be done using at1(x1 = x2) for examlpe. This can be useful when there are interactions:
consider a model with treat age treat_age as covariates where treat_age is an interaction with age. When standardising for when treat=0 and treat=1, the at() options should be
at1(treat 0 treat_age 0) and at1(treat 1 treat_age = age)

atvars(stub | newvarnames) gives the new variables to create. This can be
specified as a varlist equal to the number of at() options or a stub
where new variables are named stub1 - stubn. If this
option is not specified, the names default to _at1 to _atn.

atreference(#) the atn() option that defines the reference category.
By default this is at1().

centile(numlist) calculates centiles of the standardised survival curve
for the centiles given in numlist. The centile values are given in a
new variable, _centvar, or that defined using the centvar() option.

centileupper(#) upper starting value when calculating centiles of the
standardised survival curve. The default is twice the maximum survival time.

centileupper(newvarname) name of new varaible giving values of centiles.
The default is _centvar.

ci calculates a level(#)% confidence interval for each standardised
survival function or contrast. The confidence limits are stored using the
suffix _lci and _uci.

contrast(contrastname) calculates contrasts between standardised survival
curves. Options are difference and ratio. There will be n-1
new variables created, where n is the number of at() options.

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.
The names default to _contrast1 to _contrastn-1.

failure calculates the standardised failure function rather than
the standardised survival function.

hazard calculates the hazard function of the standardised survival
function. Note that this is not the mean of the predicted hazard functions,
but a weighted mean with weights S(t). The weights are time-dependent.

lincom(#...#) calculates a linear combination of atn options. As an example, if
there were two at options then lincom(1 -1) would calculate the difference in the
standardized estimate. This would be the same as using the contrast(difference) option.

mestimation requests that standard errors are obtained using M-estimation (Stefanski and Boos 2002) rather than the delta-method.
When calculating centiles of standardized curves it is only possible to use M-estmation.

nodes(#) number of nodes when performing numerical integration to
calculate the restricted mean survival time.

rmst calculates the restricted mean survival time. These are calculated at
the time points give in variable given in the timevar() option.

se calculates the standard error for each standardised
function or contrast. This is stored using the suffix _se.

timevar(varname) defines the variable used as time in the predictions. The
option is useful for large datasets where, for plotting purposes, predictions
are needed only for (say) 200 observations. Note that predictions are averaged
over the whole sample, not just those where timevar is not missing. It is
recommended that timevar() is used, as otherwise an estimate of the survival
function is obtained at each value of _t for all subjects.
Default varname is _t.

trans(name) transformation to apply when calculating standard errors to
obtain confidence intervals for the standardised curves. The default is
log(-log S(t)). Other possible names are none, log, logit.

userfunction(name) give a Mata function that calculates transformations the standardized functions. This enables flexibility to calculate
a wide range of potential functions. An example of a Mata function to calculate a difference between two standardized function is shown below

mata:

function user_eg(at) {

return(at[2] - at[1])

}

end

stpm2_standsurv, at1(x1 0) at2(x1 1) timevar(tt) ci userfunction(user_eg)

userfunctionvar(newvarname) gives the new variable to create when
using the userfunction() option. The name defaults to _userfunc.

Example

For some more detailed examples see https://pclambert.net/software/stpm2_standsurv/

Load example dataset:

. webuse brcancer, clear

stset the data:

. stset rectime, f(censrec==1) scale(365.24)

Fit stpm2 model:

. stpm2 hormon x5 x1 x3 x6 x7, scale(hazard) df(4) tvc(hormon x5 x3) dftvc(3)

Generate variable that defines timepoints to predict at. The following creates 50 equally spaced time points between 0.05 and 5 years:

. range timevar 0 5 50

Obtain standardised curves for hormon=0 and hormon=1.
In each case the survival curves are the average of the 686
survival curves using the observed covariate values except for hormon.

. stpm2_standsurv, atvars(S0a S1a) at1(hormon 0) at2(hormon 1) timevar(timevar) ci

Plot standardised curves:

. line S0a S1a timevar

Obtain standardised curves for hormon=0 and hormon=1, but apply the covariate distribution amongst those with hormon=1.

. stpm2_standsurv if hormon==1, atvars(S0b S1b) at1(hormon 0) at2(hormon 1) timevar(timevar) ci

Plot standardised curves:

. line S0b S1b timevar

Obtain standardised curves for hormon=0 and hormon=1, and calculate difference in standardised survival curves and 95 confidence interval.

. stpm2_standsurv, atvars(S0c S1c) at1(hormon 0) at2(hormon 1) timevar(timevar) ci contrast(difference) contrastvar(Sdiffc)

Plot difference in standardised curves and 95% confidence interval:

. line Sdiffc* timevar

Acknowledgements

The idea to implemnt centiles of the standardized survival curve aroise through discussions with David Drukker at the Nordic Stata User Group meetings in Oslo and Stockholm.
Thanks to Michael Crowther for strong encouragement to use structures and pointers to help generalise this command.

Also see

Online: [ST] stpm2, [ST] stpm2_postestimation

References

Stefanski L.A. and Boos, DD. The calculus of M-estimation. The American Statistician 2002;56;29-38.