*! version 1.0.0

Title

survsim -- Simulate survival data from a parametric distribution,
a user-defined distribution, from a fitted merlin model, from a cause-specific
hazards competing risks model, or from a general multi-state model

Syntax

Syntax for simulating survival times from a parametric distribution:

survsim newvarname1 [newvarname2] , distribution(string) [options]

See help survsim for more on simulating survival times in other settings.

Options

distribution(exponential) exponential survival distribution

distribution(gompertz) Gompertz survival distribution

distribution(weibull) Weibull survival distribution

lambdas(numlist) scale parameters

gammas(numlist) shape parameters

covariates(varname # [# ...] ...) baseline covariates

tde(varname # [# ...] ...) time-dependent effects

maxtime(#|varname) right censoring time(s); either a common number or a varname

ltruncated(#|varname) left truncation time(s) (delayed entry); either a common number or a varname

2-component mixture
mixture simulate survival times from a 2-component mixture model

pmix(real) mixture parameter, default is 0.5

nodes(#) number of Gauss-Legendre quadrature nodes, default 30; see details

Description

survsim simulates survival data from a parametric distribution, a user-defined distribution, from a fitted
merlin model, from a cause-specific hazards competing risks model, or from a Markov multi-state model.
This help file centres on the parametric distribution setting.

Survival times can be simulated from standard parametric distributions including the exponential, Gompertz and Weibull,
and 2-component mixtures of them. Baseline covariates can be included, with specified associated log hazard ratios.
Non-proportional hazards can also be included with all models; under an exponential or Weibull model covariates are interacted
with log time, under a Gompertz model covariates are interacted with time. See
Crowther and Lambert (2012) for more details.

newvarname1 specifies the new variable name to contain the generated survival times. newvarname2 is required when
the maxtime() option is specified which defines the time(s) of right censoring.

Options

distribution(string) specifies the parametric survival distribution to use, including exponential,
gompertz or weibull. All listed distributions are parameterised in the proportional hazards metric.

lambdas(numlist) defines the scale parameters in the exponential/Weibull/Gompertz distribution(s). The number of
values required depends on the model choice. Default is a single number corresponding to a standard parametric distribution.
Under a mixture model 2 values are required.

gammas(numlist) defines the shape parameters of the Weibull/Gompertz parametric distribution(s). Number of
entries must be equal to that of lambdas.

covariates(varname # ...) defines baseline covariates to be included in the linear predictor of the
survival model, along with the value of the corresponding coefficient. For example, a treatent variable coded 0/1 can be
included, with a log hazard ratio of 0.5, by covariates(treat 0.5). Variable treat must be in the dataset before
survsim is called.

tde(varname # ...) creates non-proportional hazards by interacting covariates with log time for an
exponential or Weibull model, or time under a Gompertz model or mixture model. Values should be entered as
tde(trt 0.5), for example. Multiple time-dependent effects can be specified, but they will all be interacted with
the same function of time.

maxtime(#|varname) specifies the right censoring time(s). Either a common maximum follow-up time # can be
specified for all observations, or observation specific censoring times can be specified by using a varname.

ltruncated(#|varname) specifies the left truncated/delayed entry time(s). Either a common time # can be
specified for all observations, or observation specific left truncation times can be specified by using a varname.

Mixture model

mixture specifies that survival times are simulated from a 2-component mixture model, with mixture component
distributions defined by distribution(). lambdas() and gammas() must be of length 2.

pmix(#) defines the mixture parameter. Default is 0.5.

nodes(#) defines the number of Gauss-Legendre quadrature points used to evaluate the cumulative hazard function
when mixture and tde() are specified together. To simulate survival times from such a mixture model, a combination
of numerical integration and root-finding is used. The default is nodes(30).

Remarks

When simulating from a mixture model, covariate effects are additive on the log hazard scale, and are applied to the overall
hazard function, rather than each mixture component.

When simulating from a mixture model with time-dependent effects, numerical integration is used to evaluate the
cumulative hazard function, within iterations of Brent's univariate root finder. As with all model frameworks which use
numerical integration, it is important to assess the stability of the simulated survival times with an increasing number
of integration points, through use of the nodes() option. Any survsim call that requires Brent's method is
executed under a tolerance of 1e-08, to ensure accurracy of the simulated survival times.

Always set seed, to ensure reproducibility.

Examples

Generate times from a Weibull model including a binary treatment variable, with log hazard ratio = -0.5, and censoring
after 5 years:

. set obs 1000

. gen trt = rbinomial(1,0.5)

. survsim stime1 died1, distribution(weibull) lambdas(0.1) gammas(1.5) covariates(trt -0.5) maxtime(5)

. stset stime1, failure(died1 = 1)

. streg trt, distribution(weibull) nohr

Generate times from a Gompertz model:

. survsim stime2, distribution(gompertz) lambdas(0.1) gammas(0.05)

Generate times from a 2-component mixture Weibull model:

. survsim stime3 died3, mixture distribution(weibull) lambdas(0.1 0.05) gammas(1 1.5) pmix(0.5) maxtime(5)

Generate times from a Weibull model with diminishing treatment effect:

. survsim stime5, distribution(weibull) lambdas(0.1) gammas(1.5) covariates(trt -0.5) tde(trt 0.05)

For more examples please see Crowther and Lambert (2013).

Author

Michael J. Crowther

Red Door Analytics

E-mail: michael@reddooranalytics.se

Please report any errors you may find.

References

Bender R, Augustin T and Blettner M. Generating survival times to simulate Cox proportional hazards models. Statistics in Medicine 2005;24:1713-1723.

Crowther MJ and Lambert PC. Simulating complex survival data. The Stata Journal 2012;12(4):674-687.

Crowther MJ and Lambert PC. Simulating biologically plausible complex survival data. Statistics in Medicine 2013;32(23):4118-4134.

Jann, B. 2005. moremata: Stata module (Mata) to provide various functions. Available from http://ideas.repec.org/c/boc/bocode/s455001.html.