*! version 0.2.0

Title

msboxes -- Simple plot to summarise states and transitions in a multi-state model

Syntax

msboxes [, options]

boxheight(#) height of boxes

boxwidth(#) width of boxes

id(varname) name of subject ID variable

grid add a grid to the plot

statenames(string) List of names of states

transnames(string) List of names of transitions

transmat name of transition matrix

yrange(numlist) range of y-axis

xrange(numlist) range of x-axis

ysize(#) y size of plot

xsize(#) x size of plot

yvalues(numlist) y values of the centre of each box

xvalues(numlist) x values of the centre of each box

freqat(varname) time points at which to calculate frequencies in each state; see details

scale(#) scales the time variable specified in freqat()

interactive create a JSON file for interactive plotting

jsonpath(string) path to save the JSON file; default is current directory

Description

msboxes is a simple descriptive tool to summarise data to be used in a multistate model. It will plot boxes for each
state and summarise the number at risk at the start and end of follow-up. Transitions are denoted by arrows between the
boxes and show the number of subjects that transition between the different states. Before using msboxes you should
use msset and then stset. See the examples below.

By default the boxes are plotted on a (0,1) (0,1) grid and the user must give sensible values for the centre of each box.
There are simple rules on how to join the boxes with arrows and where to place the text.

msboxes can produce JSON files for use with interactive multi-state model visualisations.

msboxes is part of the multistate package.

Options

boxheight(#) Height of the boxes to denote states. Default is 0.3varname.

boxwidth(#) Width of the boxes to denote states. Default is 0.2varname.

grid Add a grid to the plot. Useful when trying to get the plot to look nice by showing where it my be a good
idea to move the boxes.

id(varname) Name of id variable.

statenames(string) The names of each state. These should be given as a list of names, for example
statenames("Healthy" "Diseased" "Dead before disease" "Dead with disease").

transnames(string) The name of each transition. These should be given as a list of names, for example
transnames("Transition 1" " Transition 2" " Transition 3").

transmatrix(matrix) specifies the transition matrix used in the multi-state model that was fitted. This must be an
upper triangular matrix (with diagonal and lower triangle elements coded missing). Transitions must be numbered as an
increasing sequence of integers from 1,...,K. This transition matrix should be the same as that used/produced by msset.

yrange(numlist) gives the range of the y-axis. By default this is (0 1).

xrange(numlist) gives the range of the x-axis. By default this is (0 1).

ysize(#) gives the ysize of the plot. Default taken from the default scheme.(0 1).

xsize(#) gives the xsize of the plot. Default taken from the default scheme.(0 1).

yvalues(numlist) gives the y locaion of the centre of each box for each state. It should be a numlist of length K, where K is the number of states.

xvalues(numlist) gives the x locaion of the centre of each box for each state. It should be a numlist of length K, where K is the number of states.

freqat(varname) calculates the number of individuals being in each state at times specified in the provided varname.
It also calculates the number of individuals that have made each transition by time t. freqat() takes as argument a
variable that supplies the time points of interest. The calculated measures are returned in r(frequencies). In the case that
options interactive and jsonpath() are used, this matrix is automatically saved in the produced JSON file.

scale(#) rescale time values provided at freqat(). For example, if freqat() provides time points on a daily timescale
but _start, _stop are on a year timescale, we can to provide scale(365.25). Default value is 1.

interactive create a JSON file named "msboxes". This jsonfile can be used as input to the MSMplus web tool for
the interactive exploration of the multi-state graph.

jsonpath(string) If option interactive is defined, the user has to specify the position in the folder that the
json file will be saved by providing the pathway. For example, jsonpath("C:\documents\multistate").

Remarks

This is a fairly basic implementation and aims to give a quick summary of the data that feeds into the multi-state model.
It is not aimed to give publication quality figures.
You may need some trial and error of the location and size of the boxes.

Examples

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.

1. Illness death model:

. use http://fmwww.bc.edu/repec/bocode/m/multistate_example
. msset, id(pid) states(rfi osi) times(rf os)
. matrix tmat = r(transmatrix)
. msboxes, transmat(tmat) id(pid) xvalues(0.2 0.7 0.45) yvalues(0.7 0.7 0.2) ///
> statenames("Surgery" "Relapse" "Dead")

(click to run)

2. Extended illness death model. Separate deaths before/after recurrence.

. use http://fmwww.bc.edu/repec/bocode/m/multistate_example
. matrix tmat = (.,1,2,. \ .,.,.,3 \ .,.,.,. \ .,.,.,.)
. matrix list tmat
. msset, id(pid) states(rfi osi osi) times(rf os os) transmatrix(tmat)
. msboxes, transmatrix(tmat) id(pid) ///
> xvalues(0.2 0.7 0.2 0.7) ///
> yvalues(0.7 0.7 0.2 0.2) ///
> statenames(Surgery Relapse Dead Dead) ///
> boxheight(0.2) yrange(0.09 0.81) ysize(3)

(click to run)

Authors

Paul Lambert, University of Leicester, UK.
(paul.lambert@leicester.ac.uk)

Nikolaos Skourlis, Karolinska Institutet.

Acknowledgement

This is based on the R command boxes written by Bendix Carstensen.