*!0.3.0 Brent Mcsharry brent@focused-light.net 11dec2015/26oct2017
help tabcusum

O-E + tabular CUSUM charts

tabcusum -- command to graph O-E (VLAD) type CUSUM vertically aligned with tabular (SPRT) CUSUM

Syntax

tabcusum

[if] [in]
, predicted(varname)
[options]

Options
or (#) the odds ratio for the alternative hypothesis. Default is 2

threshold (#) decision threshold (h). Default 2.9

headstart (#) point for CUSUM to reset to as a proportion of upper threshold. Default 0

xlabel (rule_or_values) major ticks plus labels. see axis_label_options

title (tinfo) overall title. see title_options

note (tinfo) note about graph. see title_options

subtitle (tinfo) subtitle. see title_options

xtitle (axis_title) title for x axis. see axis_title_options

xaxis (# [# ...]) the x axis on which the plot is to appear. see axis_choice_options

limits (numlist) upper and lower confidence bound(s) to display on O-E (0,100)

notrunclimits show all confidence bounds

shadearea (#) value of above which the graph will be shaded grey

Description

tabcusum Plots the observed minus expected (O-E or variable life adjusted display [VLAD]) type CUSUM, vertically aligned with tabular (sequential probability ratio) CUSUM over sequential observations.
Exceeding the decision threshold on the tabular CUSUM places a corresponding marker on the O-E CUSUM.

outcome The actual outcome being benchmarked. Must only contain the values missing(.), 0 or 1.

sequence A variable denoting in what order each subject has entered the analysis.

predicted The predicted value for the outcome under investigation.

Options

Main

threshold
The decision threshold (often denoted h). Default is 2.9. It is recommended the value be chosen after approximating the desired average run lengths.
See section Also see (bottom of this help file) for articles discussing setting appropriate run lengths,
and links to a program to calculate simulated average run lengths for a given threshold.

limits upper and lower confidence bound(s) to display on O-E Cusum chart. value(s) must be greater than 0 and less than 100.
If not specified, no confidence intervals are displayed. Obviously the usual caveats apply when applying frequentist confidence intervals to continuously analysed real time data.

notrunclimits show all confidence bounds. without specifying this option, confidence boundaries denoted in the limits option will only be displayed for the range relevant to the min & max of the O-E graph.

headstart point for CUSUM to reset to as a proportion of upper threshold.
Must be a value between 0 and 1.
Default 0.
This is for creating fast initial response (FIR) CUSUM graphs.

xlabel
Custom labels can be added. Tabcusum will generate a linear sequence from 1 to _N (number of variables) so that the deflection (gradient and step) for a given outcome is constant regardless of variable intervals between cases.
Therefore for the custom labels to work, first generate a sequencevar gen seq = _n. Another program written by the same author findit mydatelabels may be of use.

xaxis
Will apply multiple axes to the O-E (top) graph.

shadearea
The value of above which the graph will be shaded grey.
This can be used to indicate more contemporaneous data may not be complete or not fully validated.

Authors

Brent McSharry, Starship Children's Hospital, Auckland New Zealand

brentm@adhb.govt.nz

Examples

Setup

. clear

. webuse cancer

. gen int study_entry_sequence=_n

assuming we would expect each subject to have a 50% probability of failure/death

. gen float p = 0.5

Plot

. tabcusum died study_entry_sequence, pred(p) threshold(2.2) headstart(0.5)

with confidence bounds

. tabcusum died study_entry_sequence, pred(p) threshold(2.2) headstart(0.5) limit(95 99)

showing entire range of upper and lower confidence bounds

. tabcusum died study_entry_sequence, pred(p) threshold(2.2) headstart(0.5) limit(95 99) notrunc

Working with dates - involves installing mydatelabels

. gen study_entry_date = td(#1jan2010#) in 1

. replace study_entry_date = study_entry_date[_n-1] + (runiform()*20) in 2/l

divide the year into quarters, and label the first case in each quarter

. mydatelabels study_entry_sequence =ceil(month( study_entry_date )/3),local(mymac) start format(%tdMon_'YY)

. tabcusum died study_entry_sequence, pred(p) threshold(2.2) headstart(0.5) limit(95 99) xlabel(`mymac', axis(2)) xaxis(1 2)

Also see

Stata: findit rasprt plots a Risk adjusted sequential probability ratio test chart +/- Risk Adjusted Cumulative Sum chart (CUSUM)

Article: Liver Transplantation 2010; Volume 16, Number 10: pp. 1119–28
Review of methods for measuring and comparing center performance after organ transplantation

Article: Transplantation 2009; Volume 88, Number 8: pp. 970-5
The UK scheme for mandatory continuous monitoring of early transplant outcome in all kidney transplant centers

Program: CusumARL is a free, open source (MIT license) console application for calculating average run lengths for a given decision threshold.
ARL0 is the expected number of observations taken from an in-control process until the control chart falsely signals.
ARL1 is the expected number of observations taken from an out-of-control process until the control chart correctly signals.
CusumARL is written by the author of RASPRT in C++ rather than Stata for reasons of performance over millions of Monte Carlo iterations.
Binaries have not been compiled for Mac or Linux - feel free to contact the author if you would like these binaries, or more features.

Change log

0.3.0

confidence boudaries added to O-E cusum

0.2.0

Graph commences at 0 rather than first cumulative observation.

Graph line stops after exceeding threshold (instead of circle).

headstart, note and title options introduced.