Type: Package
Title: Funnel Plots for Comparing Institutional Performance
Version: 0.5.0
Maintainer: Chris Mainey <c.mainey1@nhs.net>
Description: An implementation of methods presented by Spiegelhalter (2005) <doi:10.1002/sim.1970> Funnel plots for comparing institutional performance, for standardised ratios, ratios of counts and proportions with additive overdispersion adjustment.
Language: en-GB
License: MIT + file LICENSE
URL: https://nhs-r-community.github.io/FunnelPlotR/, https://github.com/nhs-r-community/FunnelPlotR
BugReports: https://github.com/nhs-r-community/FunnelPlotR/issues
Encoding: UTF-8
Imports: dplyr, ggrepel, ggplot2, scales, rlang
RoxygenNote: 7.3.1
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown, COUNT, tidyr, covr
VignetteBuilder: knitr
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2024-04-12 08:08:53 UTC; ChrisMainey(Birmingh
Author: Chris Mainey ORCID iD [aut, cre], Andrew Johnson [ctb], Matthew Bass [ctb], NHS-R Community [cph]
Repository: CRAN
Date/Publication: 2024-04-12 08:40:02 UTC

Aggregation function for record-level data, prior to plot.

Description

Internal function to aggregate record-level data for plotting as a funnel.

Usage

aggregate_func(mod_plot)

Arguments

mod_plot

A data frame of values to be aggregated. Expected columns, 'group', 'numerator' and 'denominator'

Value

Returns an aggregated data.frame of the same columns, but summed by 'group', with a relative risk 'rr' column added.

Function to build funnel limits

Description

Internal function for funnel plot to build the control limits prior to plotting.

Usage

build_limits_lookup(
  min_x,
  max_x,
  min_y,
  max_y,
  draw_adjusted,
  tau2,
  data_type,
  sr_method,
  target,
  multiplier,
  denominators
)

Arguments

min_x

Minimum predicted value for range of x-axis

max_x

Maximum predicted value for range of x-axis

min_y

Minimum ratio value for range of y-axis

max_y

Maximum ratio value for range of y-axis

draw_adjusted

TRUE/FALSE Use overdispersion adjustment

tau2

If using draw_adjusted, what is the tau2 ("between" standard error) to use?

data_type

SR, PR or RC. Used to set target reference

sr_method

Which adjustment method is being used, SHMI or CQC?

target

target to be used to set centre line

multiplier

Multiply ratio value by an amount. Default is 1, but some mortality ratios use 100, for example.

Value

A data.frame with an index column and various control limits based on the index as an x-axis value.

Overdispersion-adjusted funnel limit calculation

Description

Add 95

Usage

calculate_limits(
  dfCI = dfCI,
  data_type = "SR",
  sr_method = "SHMI",
  multiplier = 1,
  tau2 = 0,
  target = target,
  draw_adjusted = draw_adjusted
)

Arguments

dfCI

Aggregated model input data

data_type

Type of data for adjustment and plotting: Indirectly Standardised ratio (\"SR\"), proportion (\"PR\"), or ratio of counts (\"RC\").

sr_method

Adjustment method for standardised ratios, can take the value \"SHMI\" or \"CQC\". \"SHMI\" is default.

multiplier

Multiplier to adjust limits if reporting by a multiplier, e.g. per 1000.

tau2

A 'between' standard deviation to add to the within standard deviation, S, to inflate limits.

target

The centre line of the plot. Mean for non-SRs or 1 for SR

Value

A data.frame of with appended OD limits

Funnel Plots drawing function

Description

Internal function for drawing plot. Do not use this directly, call 'funnel_plot()' instead.

Usage

draw_plot(
  mod_plot_agg,
  limits,
  x_label,
  y_label,
  title,
  label,
  multiplier,
  draw_unadjusted,
  draw_adjusted,
  target,
  min_y,
  max_y,
  min_x,
  max_x,
  data_type,
  sr_method,
  theme,
  plot_cols,
  max.overlaps
)

Arguments

mod_plot_agg

data.frame of containing numerator, denominator, ratio/proportion, SEs and limits

limits

data.frame of limits from set_plot_range().

x_label

Title for the funnel plot x-axis. Usually expected deaths, readmissions, incidents etc.

y_label

Title for the funnel plot y-axis. Usually a standardised ratio.

title

Plot title

label

Whether to label outliers, highlighted groups, both or none. Default is "outlier", by accepted values are: "outlier", "highlight", "both" or "NA".

multiplier

Scale relative risk and funnel by this factor. Default to 1, but 100 is used for HSMR

draw_unadjusted

Draw exact limits based only on data points with no iterpolation. (default=FALSE)

draw_adjusted

Draw overdispersed limits using Spiegelhalter's (2012) tau2 (default=TRUE)

target

the calculated target value for the data type

min_y

Specify the plot range.

max_y

Specify the plot range.

min_x

Specify the plot range.

max_x

Specify the plot range.

data_type

the data type SR, PR or RC.

sr_method

CQC or SHMI methods for standardised ratios

theme

a ggplot theme function.

Value

A list containing [1] the funnel plot as a ggplot2 object., [2]the limits table.

A clean funnel plot theme

Description

A ggplot theme function for clean looking funnel plots. Try funnel_grey if you like the old one.

Usage

funnel_clean()

Value

a list of ggplot theme items

See Also

funnel_grey

Examples

## Not run: funnel_plot(theme=funnel_clean())

A grey ggplot funnel theme

Description

A classic ggplot theme function for funnel plots. Try funnel_clean if you don't like the grey background.

Usage

funnel_grey()

Value

a list of ggplot theme items

See Also

funnel_clean

Examples

## Not run: funnel_plot(theme=funnel_grey())

Funnel plots for comparing institutional performance

Description

An implementation of funnel plots for indirectly standardised ratios, as described by Spiegelhalter (2005) <https://doi.org/10.1002/sim.1970/>. There are several parameters for the input, with the assumption that you will want smooth, overdispersed, funnel control limits. Limits may be inflated for overdispersion based on the methods of DerSimonian & Laird (1986), buy calculating a between unit standard deviation (\tau) and constructing an additive random effects models, originally used for meta-analyses of clinical trials data.

Usage

funnel_plot(
  .data,
  numerator,
  denominator,
  group,
  data_type = "SR",
  limit = 99,
  label = "outlier",
  highlight = NA,
  draw_unadjusted = FALSE,
  draw_adjusted = TRUE,
  sr_method = "SHMI",
  trim_by = 0.1,
  title = "Untitled Funnel Plot",
  multiplier = 1,
  x_label = "Expected",
  y_label,
  x_range = "auto",
  y_range = "auto",
  plot_cols = c("#FF7F0EFF", "#FF7F0EFF", "#1F77B4FF", "#1F77B4FF", "#9467BDFF",
    "#9467BDFF", "#2CA02CFF", "#2CA02CFF"),
  theme = funnel_clean(),
  label_outliers,
  Poisson_limits,
  OD_adjust,
  xrange,
  yrange,
  SHMI_rounding = TRUE,
  max.overlaps = 10
)

Arguments

.data

A data frame containing a numerator, denominator and grouping field.

numerator

A vector of the numerator (observed events/counts) values. Used as numerator of the Y-axis

denominator

A vector of denominator (predicted/population etc.) Used as denominator of the Y-axis and the scale of the x-axis

group

A vector of group names as character or factor. Used to aggregate and group points on plots

data_type

A string identifying the type of data used for in the plot, the adjustment used and the reference point. One of: "SR" for indirectly standardised ratios, such SHMI, "PR" for proportions, or "RC" for ratios of counts. Default is "SR".

limit

Plot limits, accepted values are: 95 or 99, corresponding to 95% or 99.8% quantiles of the distribution. Default=99,and applies to OD limits if both OD and Poisson are used.

label

Whether to label outliers, highlighted groups, both or none. Default is "outlier", by accepted values are:

  • "outlier" - Labels upper and lower outliers, determined in relation to the 'limit' argument.

  • "outlier_lower" - Labels just and lower outliers, determined in relation to the 'limit' argument.

  • "outlier_upper" - Labels just upper, determined in relation to the 'limit' argument.

  • "highlight" - Labels the value(s) given in the 'highlight'argument.

  • "both" - Labels both the highlighted values(s), upper and lower outliers, determined in relation to the 'limit' argument.

  • "both_lower" - Labels both the highlighted values(s) and lower outliers, determined in relation to the 'limit' argument.

  • "both_upper" - Labels both the highlighted values(s) and upper outliers, determined in relation to the 'limit' argument.

  • NA - No labels applied

highlight

Single or vector of points to highlight, with a different colour and point style. Should correspond to values specified to 'group'. Default is NA, for no highlighting.

draw_unadjusted

Draw control limits without overdispersion adjustment. (default=FALSE)

draw_adjusted

Draw overdispersed limits using hierarchical model, assuming at group level, as described in Spiegelhalter (2012). It calculates a second variance component ' for the 'between' standard deviation (\tau), that is added to the 'within' standard deviation (sigma) (default=TRUE)

sr_method

Method for adjustment when using indirectly standardised ratios (type="SR") Either "CQC" or "SHMI" (default). There are a few methods for standardisation. "CQC"/Spiegelhalter uses a square-root transformation and Winsorises (rescales the outer most values to a particular percentile). SHMI, instead, uses log-transformation and doesn't Winsorise, but truncates the distribution before assessing overdisperison . Both methods then calculate a dispersion ratio (\phi) on this altered dataset. This ratio is then used to scale the full dataset, and the plot is drawn for the full dataset.

trim_by

Proportion of the distribution for winsorisation/truncation. Default is 10 % (0.1). Note, this is applied in a two-sided fashion, e.g. 10% refers to 10% at each end of the distribution (20% winsorised/truncated)

title

Plot title

multiplier

Scale relative risk and funnel by this factor. Default to 1, but 100 sometime used, e.g. in some hospital mortality ratios.

x_label

Title for the funnel plot x-axis. Usually expected deaths, readmissions, incidents etc.

y_label

Title for the funnel plot y-axis. Usually a standardised ratio.

x_range

Manually specify the y-axis min and max, in form c(min, max), e.g. c(0, 200). Default, "auto", allows function to estimate range.

y_range

Manually specify the y-axis min and max, in form c(min, max), e.g. c(0.7, 1.3). Default, "auto", allows function to estimate range.

plot_cols

A vector of 8 colours for funnel limits, in order: 95% Poisson (lower/upper), 99.8% Poisson (lower/upper), 95% OD-adjusted (lower/upper), 99.8% OD-adjusted (lower/upper). Default has been chosen to avoid red and green which can lead to subconscious value judgements of good or bad. Default is hex colours: c("#FF7F0EFF", "#FF7F0EFF", "#1F77B4FF","#1F77B4FF", "#9467BDFF", "#9467BDFF", "#2CA02CFF", "#2CA02CFF")

theme

a ggplot theme function. This can be a canned theme such as theme_bw(), a theme() with arguments, or your own custom theme function. Default is new funnel_clean(), but funnel_classic() is original format.

label_outliers

Deprecated. Please use the 'label' argument instead.

Poisson_limits

Deprecated. Please use the 'draw_unadjusted' argument instead.

OD_adjust

Deprecated. Please use the 'draw_adjusted' argument instead.

xrange

Deprecated. Please use the 'x_range' argument instead.

yrange

Deprecated. Please use the 'y_range' argument instead.

SHMI_rounding

TRUE/FALSE, for SHMI calculation (standardised ratio, with SHMI truncation etc.), should you round the expected values to 2 decimal places (TRUE) or not (FALSE)

max.overlaps

Exclude text labels that overlap too many things. Defaults to 10. (inheritted from geom_label_repel)

Details

Outliers are marked based on the grouping, and the limits chosen, corresponding to either 95% or 99.8% quantiles of the normal distribution.
Labels can attached using the 'label' argument.
Overdispersion can be factored in based on the methods in Spiegelhalter et al. (2012), set 'draw_adjusted' to FALSE to suppress this.
To use Poisson limits set 'draw_unadjusted=TRUE'.
The plot colours deliberately avoid red-amber-green colouring, but you could extract this from the ggplot object and change manually if you like. Future versions of 'funnelplotr' may allow users to change this.

Value

A fitted 'funnelplot' object. A 'funnelplot' object is a list containing the following components:

print

Prints the number of points, outliers and whether the plot has been adjusted, and prints the plot

plot

A ggplot object with the funnel plot and the appropriate limits

limits_lookup

A lookup table with selected limits for drawing a plot in software that requires limits.

aggregated_data

A data.frame of the the aggregated dataset used for the plot.

outlier

A data frame of outliers from the data.

tau2

The between-groups standard deviation, \tau^2.

phi

The dispersion ratio, \phi.

draw_adjusted

Whether overdispersion-adjusted limits were used.

draw_unadjusted

Whether unadjusted Poisson limits were used.

References

DerSimonian & Laird (1986) Meta-analysis in clinical trials. <doi:10.1016/0197-2456(86)90046-2>

Spiegelhalter (2005) Funnel plots for comparing institutional performance <doi:10.1002/sim.1970>

Spiegelhalter et al. (2012) Statistical methods for healthcare regulation: rating, screening and surveillance: <doi:10.1111/j.1467-985X.2011.01010.x>

NHS Digital (2020) SHMI Methodology v .134 https://digital.nhs.uk/data-and-information/publications/ci-hub/summary-hospital-level-mortality-indicator-shmi

Examples

# We will use the 'medpar' dataset from the 'COUNT' package.
# Little reformatting needed

library(COUNT)
data(medpar)
medpar$provnum<-factor(medpar$provnum)
medpar$los<-as.numeric(medpar$los)

mod<- glm(los ~ hmo + died + age80 + factor(type)
      , family="poisson", data=medpar)

# Get predicted values for building ratio
medpar$prds<- predict(mod, type="response")

# Draw plot, returning just the plot object
fp<-funnel_plot(medpar, denominator=prds, numerator=los,
group = provnum, limit=95, title="An example funnel plot")

# Methods for viewing/extracting
print(fp)
plot(fp)
summary(fp)
limits(fp)
outliers(fp)
source_data(fp)
phi(fp)
tau2(fp)

Funnel plot limits

Description

Limits class for funnel plots

Usage

limits(x)

Arguments

x

object of class funnel plot

Funnel plot outliers

Description

Outliers class for funnel plots

Usage

outliers(x)

Arguments

x

object of class funnel plot

dispersion ratio, \phi, for Funnel plots

Description

Phi class for funnel plots

Usage

phi(x)

Arguments

x

object of class funnel plot

Calculate overdispersion ratio

Description

Internal function to perform the transformations for data types.

Usage

phi_func(n, zscores)

Arguments

n

Single numeric value for the count of the number of groups (and therefore z-scores)

zscores

Vector of z-scores z-scores to be used. Commonly, this would be 'winsorised' first to remove impact of extreme outliers. SHMI truncates instead, but this simply reduced the n as well as the z-score.

Value

A numeric phi value

source data used to create Funnel plots

Description

Source data class for funnel plots

Usage

source_data(x)

Arguments

x

object of class funnel plot

between groups variance, \tau^2, for Funnel plots

Description

Tau2 class for funnel plots

Usage

tau2(x)

Arguments

x

object of class funnel plot

Calculate the between group standard error (tau2) using a dispersion factor

Description

Internal function to calculate the additional, between group, standard error (tau2) to add to S2.

Usage

tau_func(n, phi, S)

Arguments

n

The number of groups for data items, e.g. hospitals trusts that z-scores are calculated at.

phi

The dispersion ratio, where > 1 means overdispersion

S

Standard error (within cluster, calculated in z-score process)

Value

A numeric Tau2 value

Transformation function for z-scoring

Description

Internal function to perform the transformations for data types.

Usage

transformed_zscore(
  mod_plot_agg = mod_plot_agg,
  data_type = "SR",
  sr_method = "SHMI"
)

Arguments

mod_plot_agg

Aggregated model input data

data_type

Type of data for adjustment and plotting: Indirectly Standardised ratio (\"SR\"), proportion (\"PR\"), or ratio of counts (\"RC\").

sr_method

Adjustment method, can take the value \"SHMI\" or \"CQC\". \"SHMI\" is default.

Value

A data.frame of original, aggregated data plus transformed z-score (unadjusted for overdispersion)

Truncation function for NHSD method

Description

Internal function to perform the truncation.

Usage

truncation(mod_plot_agg = mod_plot_agg, trim_by = 0.1)

Arguments

mod_plot_agg

Aggregated model input data

trim_by

The amount to truncate the distribution by, prior to transformation. 0.1 means 10% (at each end).

Value

A data.frame with truncated z-scores added

Winsorisation function

Description

Internal function to perform the Winsorisation.

Usage

winsorisation(mod_plot_agg = mod_plot_agg, trim_by = 0.1)

Arguments

mod_plot_agg

Aggregated model input data

trim_by

The amount to Winsorise the distribution by, prior to transformation. 0.1 means 10% (at each end).

Value

A data.frame with winsorised z-scores returned added

mirror server hosted at Truenetwork, Russian Federation.