*! version 0.1.0 ?????2017

Title

stmerlin -- convenience wrapper for estimating a parametric and semi-parametric survival model with
merlin, optionally including multiple timescales

Syntax

stmerlin [indepsyntax] [if] [in] , distribution(model)
[, options
display_options]

where indepsyntax is a merlin linear predictor, which can be anything from
a simple varlist, to directly specifying spline or fractional polynomial functions of continuous covariates.

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

options

distribution(addrcs) hazard scale spline model

distribution(exponential) exponential model

distribution(cox) Cox model

distribution(gompertz) Gompertz model

distribution(ggamma) generalised gamma

distribution(lognormal) log normal

distribution(loglogistic) log logistic

distribution(pwexponential) piecewise-exponential model

distribution(rp) Royston-Parmar model

distribution(rcs) Log-hazard scale spline model

distribution(weibull) Weibull model

noconstant omit the constant term

df(#) degrees of freedom for the baseline function with rp or rcs models; see details

knots(knots_list) knot locations for the baseline function with rp or rcs models; see details

tvc(varlist) time-dependent effects

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

tvctime use splines of time rather than log time for time-dependent effects

noorthog turns off the default orthogonalisation of any spline terms

bhazard(varname) expected event rate at event times, invokes a relative survival model

chintpoints(#) set the number of integration points to calculate the cumulative hazard function

time#(mt_opts) define two to five additional timescales modelled with restricted cubic
splines, specified with time2(mt_opts),
with a maximum of time5(mt_opts)

multiple timescale options

offset(varname) defines the offset to be added to _t to define the additional timescale

moffset(varname) defines the offset to be taken away ("minused") from _t to define the additional timescale

df(#) degrees of freedom for timescale spline function

knots(knots_list) knot locations for the timescale spline function

time use splines of time rather than log time for
the timescale

tvc(varlist) time-dependent effects on the additional timescale

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

tvctime use splines of time rather than log time for time-dependent effects

noorthog turns off the default orthogonalisation of any spline terms

display options

eform display exponentiated coefficients

showmerlin display the underlying merlin model syntax

Description

stmerlin fits survival models, including a range of parametric distributions, flexible spline-based models, and the
Cox model, possibly including multiple timescales. It is a convenience wrapper of the more powerful merlin command,
but with a much more user-friendly syntax. Time-dependent effects can be specified using restricted cubic splines through options,
or in alternative ways using merlin's linear predictor syntax. For predictions available post-estimation, see
stmerlin postestimation.

The merlin command fits an extremely broad class of mixed effects regression models for linear, non-linear and
user-defined outcomes. For full details and many tutorials, take a look at the accompanying website:
reddooranalytics.se/products/merlin

Options

distribution(model) specifies the distributional family. They include:

distribution(addrcs) fits a spline-based flexible parametric survival model, using restricted cubic splines of
log time, to model the baseline hazard function.

distribution(exponential) fits an exponential model.

distribution(cox) fits a Cox model using maximum partial likelihood, assuming the Breslow method for
handling ties.

distribution(gompertz) fits a Gompertz model.

distribution(ggamma) fits a generalised gamma accelerated failure time model.

distribution(lognormal) fits a log normal accelerated failure time model.

distribution(loglogistic) fits a log logistic accelerated failure time model.

distribution(pwexponential) fits a piecewise-exponential model; requires the knots() option.

distribution(rp) fits a Royston-Parmar flexible parametric survival model, using restricted cubic splines of
log time, to model the log baseline cumulative hazard function.

distribution(rcs) fits a spline-based flexible parametric survival model, using restricted cubic splines of
log time, to model the log baseline hazard function.

distribution(weibull) fits a Weibull model, in a hazards metric.

noconstant suppresses the constant (intercept) term in the linear predictor.

df(#) degrees of freedom for the baseline log [cumulative] hazard function, i.e. number of restricted cubic
spline terms when using distribution(rp) or distribution(rcs). Internal knots are placed at centiles of the
event times. Boundary knots are placed at the minimum and maximum event times.

knots(knots_list) either:

defines the knot locations for the spline functions used to model the baseline
log [cumulative] hazard function when using distribution(rp) or distribution(rcs). Must include boundary
knots. Knots should be specified in increasing order.

defines the knot locations (cut-points) of the baseline function for distribution(pwexponential). Knots should
be specified in increasing order.

tvc(varlist) specifies the variables that have time-dependent effects. Time-dependent effects are fitted
using restricted cubic splines of time or log time (the default). The degrees of freedom are specified using the
dftvc() option. Note, tvc()s are not supported with generalised gamma, log normal or log logistic models.

dftvc(numlist) degrees of freedom for the time-dependent effects specified in tvc(). If only one number is
specified, then the same degrees of freedom are applied to all tvc()s, otherwise, a number must be specified for each.

tvctime specified that restricted cubic splines of time are used to model time-dependent effects, rather than
the default of log time.

noorthog suppresses orthogonal transformation of spline variables.

bhazard(varname) invokes a relative survival (excess hazard) model, by specifying the expected event rate in the reference
population at the observed event times.

chintpoints(#) defines the number of Gauss-Legendre integration (quadrature) points used to calculate analytically intractable
cumulative hazard functions. Default is chintpoints(30)

Multiple timescales

offset(varname) defines the offset to be added to _t to define the additional timescale. If time since diagnosis
was the main timescale, and you wish to add attained age as a second timescale, the offset() would contain age at diagnosis.

moffset(varname) defines the offset to be taken away ("minused") from _t to define the additional timescale, i.e. to
reset the clock.

df(#) degrees of freedom for the additional timescale function, i.e. number of restricted cubic
spline terms. Internal knots are placed at centiles of the event times. Boundary knots are placed at the minimum and maximum event times.

knots(knots_list) defines the knot locations for the spline functions used to model the additional timescale. Must include
boundary knots. Knots should be specified in increasing order.

time specifies that restricted cubic splines of time are used to model the additional timescale, rather than the default of log time.

tvc(varlist) specifies the variables that have time-dependent effects on the additional timescale. Time-dependent effects
are fitted using restricted cubic splines of time or log time (the default). The degrees of freedom are specified using the
dftvc() option. Note, tvc()s are not supported with generalised gamma, log normal or log logistic models.

dftvc(numlist) degrees of freedom for the time-dependent effects specified in tvc(). If only one number is
specified, then the same degrees of freedom are applied to all tvc()s, otherwise, a number must be specified for each.

tvctime specified that restricted cubic splines of time are used to model time-dependent effects on the additional timescale,
rather than the default of log time.

noorthog suppresses orthogonal transformation of spline variables (additional timescale and any time-dependent effects).

Display

eform displays exponentiated coefficients for the main linear predictor.

showmerlin displays the full merlin model syntax.

Examples

Fit a Royston-Parmar flexible parametric model:

. webuse brcancer,clear
. stset rectime, failure(censrec) scale(365)
. stmerlin hormon, distribution(rp) df(3)

Fit a Cox proportional hazards model:

. stmerlin hormon, distribution(cox)

Fit a Cox model with a time-dependent effect using splines:

. stmerlin hormon, distribution(cox) tvc(hormon) dftvc(3)

Fit a Cox proportional hazards model with a non-linear effect of age:

. stmerlin hormon rcs(age, df(3)), distribution(cox)

Author

Michael J. Crowther

Red Door Analytics AB

Stockholm, Sweden

michael@reddooranalytics.se