*! version 1.0.0

Title

msset -- data preparation for multi-state and competing risks analysis

Syntax

msset [if] [in] , id(varname) states(varlist) times(varlist) [options]

id(varname) identification variable

states(varlist) indicator variables for each state

times(varlist) time variables for each state

transmatrix(matname) transition matrix

covariates(varlist) variables to expand into transition specific covariates

Description

msset is a data preparation tool for multi-state and competing risks analysis. It turns a dataset from wide format (one observation per subject)
into long format (one line for each transition that a subject is at risk). All other variables are expanded appropriately.

The user can provide a transition matrix using transmatrix(), which must be an upper triangular matrix, with transitions numbered as an increasing sequence of integers from
1,...,K. If transmatrix() is left empty, a complete upper triangular transition matrix is constructed, assuming all possible transitions, with the number of states
equal to the number of variables specified in states(). All subjects are assumed to start in state _from = 1, at time _start = 0.

A warning is displayed if the next transition cannot be uniquely identified, i.e. multiple events occur with the same smallest event time, in which
case the state with the smallest transition number is chosen, with the other states changed to censored.

msset creates the following variables:

_from starting state
_to receiving state
_trans transition number
_start starting time for each transition
_stop stopping time for each transition
_status status variable, indicating a transition (coded 1) or censoring (coded 0)
_flag indicator variable to show observations where changes to the original data have been made

msset is part of the multistate package.

Options

id(varname) defines the identification variable. Each observation should be identified by a unique integer.

states(varlist) specifies the event indicator variables corresponding to each state.

times(varlist) specifies the time variables for each state, i.e. the times at which each state was entered, or censored. The variables should
be ordered to correspond to the states specified in states().

transmatrix(matname) specifies a user-defined transition matrix. This must be an upper triangular matrix (with diagonal and lower triangle elements
coded missing). Transition must be numbered as an increasing sequence of integers from 1,...,K. If transmatrix() is left empty, a complete transition
matrix is constructed, assuming all possible transitions, with the number of states equal to the number of variables specified in states(). All
subjects are assumed to start in state _from = 1, at time _start = 0.

covariates(varlist) expands covariates into transition-specific variables, by forming an interaction between each covariate
and the _trans# variables. For use when wanting to specify transition-specific covariate effects when fitting a model to the stacked data.

Example 1:

This dataset contains information on 2982 patients with breast cancer. Baseline is defined as time of surgery, and patients can experience
relapse, relapse then death, or death with no relapse. Time of relapse is stored in rf, with event indicator rfi, and time of death
is stored in os, with event indicator osi.

Load example dataset:

. use http://fmwww.bc.edu/repec/bocode/m/multistate_example

msset the data:

. msset, id(pid) states(rfi osi) times(rf os)

Saved results

msset returns the following in r():

Matrices:

r(Nnextstates) number of possible next states from starting state (row number)

r(transmatrix) transition matrix

r(freqmatrix) frequencies of transitions

Author

Michael J. Crowther

Red Door Analytics

Stockholm, Sweden

E-mail: michael@reddooranalytics.se

Please report any errors you may find.

References

Crowther MJ and Lambert PC. Parametric multi-state survival models: flexible modelling allowing transition-specific distributions with application to estimating clinically useful measures of effect differences (Submitted).

de Wreede LC, Fiocco M and Putter H. mstate: An R Package for the Analysis of Competing Risks and Multi-State Models. Journal of Statistical Software 2011;38:1-30.

Putter H, Fiocco M and Geskus RB. Tutorial in biostatistics: competing risks and multi-state models. Statistics in Medicine 2007;26:2389-2430.