help for funnelperform(Brent McSharry, Silvia Forni, Rosa Gini)

Title

funnelperform Funnel plot for institutional comparison

Syntax

funnelperform outcome population_size identifier [std_dev] [if] [in] [iweight] , continuous/binomial/poisson/gamma/beta } [smr] [
options]

Variables
outcome Y-axis such as standardised mortality ratio (SMR) or risk adjusted rate

population_size X-axis such as the number of cases performed or number of expected failures

identifier The identifier for each data point such as institution or surgeon name

iweight
iw=varname when using beta distribution & the x-axis is the expected number of failures, will weight confidence intervals by the size of the population at risk. See examples below.

Distribution (mandatory)
continuous normal distribution

binomial binomial distribution

poisson Poisson distribution

gamma gamma distribution

beta beta distribution

smr values are indirectly standardised rates

Distribution parameters
noweight specify that target value and/or standard deviation of the target distribution must be computed from the data,
but without using pop as weights

ext_stand(num) specify target value as an external standard, instead of weighted mean of value

ext_sd(num) specify standard deviation as an external value, instead of weighted mean of sdvalue

Contours
contours(numlist:numlist) specify significance levels (in percentage) of the contours to be plotted; default is 95.45% and 99.73% (2 & 3 standard deviations)

exact specify that contours are computed using an exact formula instead of the normal approximation (only valid for discrete distributions; implies Stata version 10.0)

contcolor(colorstyle:color) specify colour of the contour lines if shadedcontours is not specified

shadedcontours specify shaded, instead of black, contour lines

solidcontours specify solid, instead of dashed, contour lines

n number of points connecting the the contour lines. Default is 100.

Constant
constant(num) contains the multiplicative constant by which the
indicators contained in value are multiplied on the y-axis, e.g. 100 if they are percentages

Legend
legendcontour specify that contours should be labeled with labels of the form "Sign. 95%"

legendmore(options) specify any additional graph to be labeled; the options string must be contained in compound double quotes, e.g. `"3 "lower bound""'

legendoptions(options) specify any legend_options

Marking options: principal scatter
scattercolor(colorstyle:color) colour of scatter points

scatteropts(options) other marker_options and marker_label_options

unitlabel(string) string to be used in the legend of the scatter points, instead of the variable label of unit or the string "Units"

markall specify that all scatter points should be labeled with the value label or, if there is no value label, with the actual value of the unit they represent

Marking options: contours
markup specify that points upper the countour at significance markcontour should be coloured in markupcolor and labeled with the label or value of the unit they represent

markupcolor(colorstyle:color) option of markup

marklow specify that points lower the countour at significance markcontour should be coloured in marklowcolor

marklowcolor(colorstyle:color) option of marklow

markcontour(num) option of markup and/or marklow, the default is the first contour of the numlist in contours(numlist) - if contours is not specified, the default is significance 95%

trunc0 truncate the confidence intervals at 0. Use when the y axis represents a rate or ratio for which a negatve number could not exist

Marking options: conditions
markcond(condition) must contain a condition valid on the active dataset; specifies that points satisfying that condition should be coloured in colormarkcond with marker_options and marker_label_options contained in optionsmarkcond
and that the legend of this scatter should be legendmarkcond

colormarkcond(colorstyle:color) option of markcond

labelcond display individual unit identifiers for units satisfying the markcond. default is not to display individual unit identifiers

legendmarkcond(string) the string to print in the legend associated with the relevant markcond

optionsmarkcond(options) marker_options.option of markcond

markcond1(condition)... up to 3 additional conditions might be specified of the form markcond#(condition); specifies that points satisfying markcond#(condition) should be coloured in
colormarkcond#(color) with the marker_options contained in optionsmarkcond#(options) and that the legend of this condition grouping should display the string in legendmarkcond#(string)

Marking options: markunit
markunits(# [# ...]) list a set of values of unit whose scatter point must labeled; The value label or value itself is used as a label

labelunits(v "d" [v "d"..]) custom labels where v is the value and d is the display name

markcolor(colorstyle:color) specify the colour of the units

marktextoptions(options) specify any added_text_options; default is placement(ne)

Other graph options
vertical plot a vertical funnel plot instead of a horizontal one

linecolor(colorstyle:color) specify the colour of the target line

extraplot(plot) specify additional plots to overlay the funnel plot

title(string) specify title_options

tit:le(string) specify axis title, see axis_options

aspectratio(options) specify aspectratio, see aspect_option

twowayopts(options) specify additional twoway_options possibly overriding other default or specified options (e.g. legending options)

Programming options
displaycommand show the command that generates the graph

saving(filename) save a dta file ready for funnel generation with the command displayed by displaycommand, with target value and other information saved as dataset characteristics

nodraw avoid plotting the graph

value contains the values of the indicator;
pop contains the denominators of the indicator or,
if smr is specified, the expected number of events; unit contains an identifier of the
units (e.g. institutions) whose indicator values are to be compared with a target value;
sdvalue is optionally specified in case the continuous option
is also specified, and contains the standard deviations of the indicator values.

Description

funnelperform computes data and plots a funnel plot as defined by Spiegelhalter 2005. A scatter plot of an indicator values value is plotted against a measure of their precision pop, typically the sample size, together
with a target line and control limits (contours), that narrow as the sample size gets bigger. The plot graphically tests whether each value of the indicator is extracted from a target distribution specified by the options.

funnelperform was forked off the user written command funnelcompar written by Silvia Forni & Rosa Gini, in order to address a few issues - namely
a) if the program fails the data (both variables and number of observations) should be left untouched;
b) gama and beta distributions have been added;
c) exact methods are significantly more performant with smoother contour lines;
d) labeling of the data points handles string names and encoded (labeled) integers equally as well;
e) scatteroptions will accept marker_label_options in order to make it easier to avoid overlapping labels;
f) a trunc0 option to prevent confidence intervals being displayed below 0, for instances where this would be impossible;
g) confidence intervals now default to 95.45 & 99.73 (2 & 3 std deviations);
h) fix const option so that y-axis labels change but graph appears the same;
i) add labelunits option allowing consistent syntax whether the identifier storage type is numeric or string
j) more examples including data are included in this help file;

Target distribution and algorithm for parameter definition

The user must specify a distribution among normal, binomial, beta, gamma or
Poisson, respectively with the appropriate option. The parameters of the target distribution (target value and standard deviation) are then defined.

The target value is computed as a default as a weighted mean of value with weights pop. If the noweight option is specified it is computed as a simple mean. Finally, it might be specified by the user as an external value via
the ext_stand option.

If the distribution is binomial or Poisson with target value t then the standard deviation is obtained as the squared root of, respectively, t(1-t) and t. Only if the distribution is normal the standard deviation
must be further estimated. As a default it is computed as a weighted mean of sdvalue with weights pop. If the noweight option is specified it is computed as a simple mean of sdvalue. Finally, it might be specified
by the user as an external value via the ext_sd option.

If the smr option is specified
then poisson or gamma or beta (in the case of a beta SMR, an iweight must also be specified) must be specified as well, and the target is assumed to be 1 (or the value specified
in the constant option).

Contours

Plotting the default contours of the funnel plot corresponds to testing if the value of the indicator differ 2 or 3 standard deviations from the target value, as recommended by standard Statistical Process Control principles. Other
significance values can be chosen with the contours() option.

If the distribution is discrete (i.e. binomial or Poisson) the exact option specifies that the contours are plotted with an exact formula, that produces slightly different contours for small values of the indicator. As
a default the normal approximation is used.

Examples

Setup

Create individual patient data

. clear

. set obs 2000

. gen unit = irecode(_n,50,150,300,500,750,1250)

. gen float risk_of_death = uniform()*.2

. gen byte died=uniform()+cond(unit==3,0.25,0.1)

Collapse patient data down by unit

. collapse (sum) risk_of_death died (count) freq=died, by(unit)

Create summary statistics

. gen smr = died/ risk_of_death

. sum died, meanonly

. gen ramr = smr*r(sum)/2000

. label variable risk_of_death "predicted number of deaths"

. label variable freq "number of procedures"

. label variable ramr "risk adjusted mortality rate"

. gen byte mlabpos = _n

. gen byte group = mod(unit,3)

. label define tmplbl 1 "OS1"

. label values unit tmplbl

Application

gamma distribution agains predicted number of deaths

. funnelperform smr risk_of_death unit , gamma markup marklow smr

beta distribution agains predicted number of deaths, weighted by total number of cases. When using this option, the contours can only have as many points as there are data points

. funnelperform smr risk_of_death unit [iw= freq], beta smr markup markall

beta distribution agains number of cases. const(100) displays risk adjusted mortality rate as a percentage on the y-axis

. funnelperform ramr freq unit , beta markup marklow markall scatteropt(mlabv(mlabpos)) const(100) ytitle("risk adj mortality (%)")

using the binomial distribution to calculate mean and standard deviation from the data points provided, then applying normal distribution confidence intervals.
The exact option would display binomial distribtion confidence intervals

. funnelperform ramr freq unit, binomial markup marklow markall const(100)

poisson confidence intervals. Display 95% & 99% conficence intervals, rather than 2 & 3 std deviation

. funnelperform ramr freq unit, pois markup marklow markall exact const(100) contour(95 99)

applying an externally derived reference line (1.0) and standard deviation, notmal distribution confidence intervals

. funnelperform smr freq unit, cont markup markall ext_sd(3.9) ext_stand(1) trunc0 unitlabel("LHAs")

Plot funnel of percentages and mark in blue a group of units and in green another group of units

. funnelperform ramr freq unit, binomial const(100) markcond(group==0) legendmarkcond(Group 0) colormarkcond(blue) markcond1(group==1) labelcond1 legendmarkcond1(Group 1) colormarkcond1(green)

Plot funnel of indirectly standardised rates, mark in green a single point labelled "Your hospital", display the command and save a dataset containing instructions for plotting the graph again

. funnelperform smr risk_of_death unit, poisson smr labelunit(2 "Your hospital") markunit(4) display saving(for_funnel)

And if the unit variable is of string data type

. tostring unit, replace force

. replace unit="unit 2" if unit=="2"

. funnelperform smr risk_of_death unit, poisson smr labelunit(4 "Your unit" "unit 2" "Sister unit") markunit(5)

Notes for those wanting to improve or help with this project

The project is hosted on github at https://github.com/mcshaz/funnelperform. Raising new issues and pull requests are always welcome.
Please note that for tracing purposes it may be easier to comment out the capture statement and closing bracket.
This capture block exists so that if the program encounters an error while calculating exact confidence intervals, the user is not faced with a different size data set than prior to the command.
This capture statement will need to be uncommented prior to submitting a pull request.
Please also check that every example above produces a plot with the appropriate marker labels, marker colors, legend etc.

Updating Author

Brent Mcharry, Starship Children's Hospital, Auckland, New Zealand
Email: brentm@adhb.govt.nz

Original Authors

Silvia Forni, Rosa Gini, Agenzia regionale di sanità della Toscana, Italy.
Last Known Email: rosa.gini@arsanita.toscana.it

References

Spiegelhalter, DJ. Funnel plots for institutional comparison. Qual. Saf. Health Care 2002; 11:390-391.

Spiegelhalter, DJ. Funnel plots for comparing institutional performance. Statist. Med. 2005; 24:1185–1202.

Also see

Silvia Forni, Rosa Gini. Funnel plots for institutional comparisons. 2009 UK Stata Users Group meeting. See the
abstract or the
presentation(pdf)

confunnel (Contour-enhanced funnel plots for meta-analysis).

extfunnel (graphical augmentations to the funnel plot to indicate the potential impact of a new study on an existing meta-analysis).