*! version 1.0.0 28feb2017

Title

stcapture -- Estimate and store survival function(s) and hazard ratios in clinical trials

Syntax

stcapture [trtvar] [if] [in] ,
required_options
[optional_options]

required_options

nperiod(#) number of "periods" at ends of which survival probabilities are to be estimated

optional_options

df(#) degrees of freedom for baseline spline function in
flexible parametric survival model

dftvc(#) degrees of freedom for spline function for
time-dependent treatment effect in flexible parametric model

dp(#) decimal places of precision for storing estimated values

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

tscale(#) scaling factor between units of analysis time and "periods"
(1 analysis-time unit = # periods)

Important note: Before stcapture can be used, stpm2
(Lambert and Royston 2009) must first
be installed from the Statistical Software Components (SSC) archive. See
ssc.

Description

stcapture computes survival probabilities (and if trtvar is supplied)
time-dependent hazard ratios as estimated in a flexible parametric model fit
by stpm2 to the dataset in memory. The estimates and other relevant quantities
are stored in r() scalars and macros.

stcapture may be used as a preamble to the ART system of sample size and
power estimation in trials (Royston and Babiker 2002, Barthel, Royston and Babiker 2005,
Barthel, Babiker, Royston and Parmar 2006). ART is a tool to explore different
trial designs in the light of predefined survival probabilities and proportional
hazards or non-proportional hazards.The current version of the ART package
may be installed from the SSC archive using the command ssc install art.

Options

nperiod(#) is not optional. The parameter # specifies the number of
"periods" at the end-points of which survival probabilities and hazard ratios
are to be estimated and output. Periods are integer numbers of time-intervals
whose length is determined by the reciprocal of # in the
tscale(#) option. Example: if analysis time in the dataset is in years
and nperiod(12) tscale(4) is specified, then each period is 1/4 year
= 3 months long and survival probabilities are estimated at
1/4, 2/4, ..., 12/4 = 3 years, i.e. at 3, 6, ..., 36 months.

df(#) specifies the degrees of freedom for baseline spline function in
the flexible parametric survival model to be used to estimate survival
functions. Default # is 5.

dftvc(#) specifies the degrees of freedom for spline function(s) for
time-dependent treatment effect(s) in the flexible parametric model. If #
is set to 1 or more, a time-dependent treatment effect is included, that is
increasingly complex as # increases. If # is set to 0 or less,
no time-dependency of the treatment effect is included, that is,
proportionality of the treatment effect(s) on the chosen scale is imposed.
For scale(hazard) models (the default), the result with # = 0 is a
proportional hazards model. Default # is 5, meaning a potentially complex
pattern of non-proportional hazards is fitted.

dp(#) specifies the number of decimal places of accuracy required for
stored survival probabilities and hazard ratios. Default # is 3.

scale(scalename) specifies the scale on which the flexible parametric model
is to be fitted. Default scalename is hazard.

tscale(#) defines the scale factor between analysis-time units and
"periods" whereby one unit of analysis time equals # periods in length.
Example: if analysis time is in years tscale(2) is specified, each period
is one half a unit of analysis time (i.e. six months) in length. Note that
# may be 1, <1 or >1, but it is often 1, or >1 to "magnify" analysis time
and give greater detail of the survival function etc. Default # is 1.

Examples

. webuse brcancer

. stset rectime, failure(censrec) scale(365.24)

. stcapture hormon, nperiod(12) tscale(2) df(3) dftvc(1) dp(3)

. return list

Stored

In all cases, stcapture stores results in r(), as follows.

Scalars

r(nperiod) number of periods used

r(nobs) number of observations in estimation sample

r(tscale) time-scale factor

r(periods) list of integer periods used

In addition, if trtvar is not provided:

Macros

r(surv) survival probabilities at end of each period in entire estimation sample

Alternatively in addition, if trtvar is provided, with arms (groups, levels)
implicitly coded 0 and 1, 0 denoting the control arm:

Macros

r(surv0) survival probabilities in 'arm 0' at each time-point

r(surv1) survival probabilities in 'arm 1' at each time-point

r(hr) hazard ratios at each time-point

References

P. Royston and A. Babiker. 2002. A menu-driven facility for complex sample size
calculation in randomised controlled trials with a survival or a binary outcome.
Stata Journal 2: 151-163.

F.-M. S. Barthel, P. Royston and A. Babiker. 2005. A menu-driven facility for
complex sample size calculation in randomized controlled trials with a survival
or binary outcome: update. Stata Journal 5: 123-129.

F.-M. S. Barthel, A. Babiker, P. Royston and M. K. B. Parmar. 2006.
Evaluation of sample size and power for multi-arm survival trials allowing for
non-uniform accrual, non-proportional hazards, loss to follow-up and cross-over.
Statistics in Medicine 25: 2521-2542.

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

Author

Patrick Royston

MRC Clinical Trials Unit at UCL, London WC2B 6NH, UK.

Email: Patrick Royston

Also see

Online: help for stpm2