Package {controlcharts}

Title: Interactive Plotting for Funnel, Sigma, and Statistical Process Control Charts
Version: 0.0.23
Description: Generate interactive funnel plots, multi-indicator sigma charts, and statistical process control ('SPC') charts. Chart calculation and plotting use JavaScript, allowing dynamic charts without a Shiny server. For more details see Spiegelhalter (2004) <doi:10.1002/sim.1970> and Pfadt & Wheeler (1995) <doi:10.1901/jaba.1995.28-349>.
License: MIT + file LICENSE
Encoding: UTF-8
Imports: htmlwidgets, htmltools, crosstalk, QuickJSR, jsutils, rlang
Suggests: rsvg, knitr, rmarkdown, testthat (≥ 3.0.0), chromote, xml2
VignetteBuilder: knitr
URL: https://aus-doh-safety-and-quality.github.io/controlcharts/
Config/roxygen2/version: 8.0.0
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-10-09 05:49:24 UTC; andrew
Author: Andrew R. Johnson ORCID iD [aut, cre], Healthcare Quality Intelligence Unit (Western Australia Health) [aut]
Maintainer: Andrew R. Johnson <andrew.johnson@arjohnsonau.com>
Repository: CRAN
Date/Publication: 2026-10-09 06:50:09 UTC

controlcharts: Interactive Plotting for Funnel Plots and Statistical Process Control Charts

Description

Generate fully interactive and dynamic funnel plots and statistical process control ('SPC') charts. All data manipulation, calculation, and plotting is done in 'JavaScript', allowing for completely dynamic charts without the need for a Shiny server. For more details see Spiegelhalter (2004) doi:10.1002/sim.1970 and Pfadt & Wheeler (1995) doi:10.1901/jaba.1995.28-349.

Author(s)

Maintainer: Andrew R. Johnson andrew.johnson@arjohnsonau.com (ORCID)

Authors:

See Also

Useful links:

Generate interactive Funnel chart

Description

Generate interactive Funnel chart

Usage

funnel(
  data,
  keys,
  numerators,
  denominators,
  tooltips,
  labels,
  aggregations = list(numerators = "sum", denominators = "sum", tooltips = "first",
    labels = "first"),
  title = NULL,
  canvas_settings = NULL,
  funnel_settings = NULL,
  outlier_settings = NULL,
  scatter_settings = NULL,
  line_settings = NULL,
  x_axis_settings = NULL,
  y_axis_settings = NULL,
  label_settings = NULL,
  tooltip_settings = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL,
  return_objs = c("html_plot", "static_plot", "limits")
)

Arguments

data

A data frame containing the data for the chart.

keys

A vector or column name representing the categories of the chart.

numerators

A numeric vector or column name representing the numerators for each category.

denominators

A numeric vector or column name representing the denominators for each category.

tooltips

A vector or column name, or a list of them, representing additional tooltips for each category. Each is labelled by its name in the list, or else by the expression supplied.

labels

A vector or column name representing the labels for each category.

aggregations

A list of aggregation function names for each field if multiple values are provided for each key. Valid options are:

  • "first": returns the first value

  • "last": returns the last value

  • "sum": returns the sum of values

  • "mean": returns the mean of values

  • "min": returns the minimum value

  • "max": returns the maximum value

  • "median": returns the median value

  • "count": returns the count of values

title

Optional title to be added to the top of the chart. It can be a character string for the title text only, or a list with the following options:

  • text: Title text (default: NULL)

  • font_size: Font size of the title (default: "16px")

  • font_weight: Font weight of the title (default: "bold")

  • font_family: Font family of the title (default: "'Arial', sans-serif")

  • x: Horizontal (x) position of the title as a percentage (default: "50%")

  • y: Vertical (y) position of the title in pixels (default: 5)

  • text_anchor: Text anchor of the title (default: "middle")

  • dominant_baseline: Dominant baseline of the title (default: "hanging")

  • subtitle: Subtitle text, drawn below the title (default: NULL)

  • subtitle_font_size: Font size of the subtitle (default: "12px")

  • subtitle_font_weight: Font weight of the subtitle (default: "normal")

canvas_settings

Optional list of settings for the canvas, see funnel_default_settings('canvas') for valid options.

funnel_settings

Optional list of settings for the Funnel chart, see funnel_default_settings("funnel") for valid options.

outlier_settings

Optional list of settings for outliers, see funnel_default_settings('outliers') for valid options.

scatter_settings

Optional list of settings for scatter points, see funnel_default_settings('scatter') for valid options.

line_settings

Optional list of settings for lines, see funnel_default_settings('lines') for valid options.

x_axis_settings

Optional list of settings for the x-axis, see funnel_default_settings('x_axis') for valid options.

y_axis_settings

Optional list of settings for the y-axis, see funnel_default_settings('y_axis') for valid options.

label_settings

Optional list of settings for labels, see funnel_default_settings('labels') for valid options.

tooltip_settings

Optional list of settings for tooltips, see funnel_default_settings('tooltips') for valid options.

width

Optional width of the chart in pixels. If NULL (default), the chart will fill the width of its container.

height

Optional height of the chart in pixels. If NULL (default), the chart will fill the height of its container.

elementId

Optional HTML element ID for the chart.

return_objs

Character vector of object types to return. Valid values are:

  • "html_plot": Interactive htmlwidgets plot

  • "static_plot": Non-interactive SVG plot

  • "limits": Calculated control limits

  • "limit_lines": Control limits across the full range of denominators, for drawing the limit lines (not returned by default)

Value

An object of class controlchart containing the interactive plot, static plot, limits data frame, raw data, and a function to save the plot.

Shiny bindings for wrapper

Description

Output and render functions for using wrapper within Shiny applications and interactive Rmd documents.

Usage

funnelOutput(outputId, width = "100%", height = "400px")

renderfunnel(expr, env = parent.frame(), quoted = FALSE)

Arguments

outputId

output variable to read from

width, height

Must be a valid CSS unit (like '100%', '400px', 'auto') or a number, which will be coerced to a string and have 'px' appended.

expr

An expression that generates a wrapper

env

The environment in which to evaluate expr.

quoted

Is expr a quoted expression (with quote())? This is useful if you want to save an expression in a variable.

Value

Interactive Shiny widget for funnel plot

Interactive Shiny widget for funnel plot

Get default settings for Funnel charts Retrieve the default settings for Funnel charts or a specific settings group.

Description

Get default settings for Funnel charts Retrieve the default settings for Funnel charts or a specific settings group.

Usage

funnel_default_settings(group = NULL)

Arguments

group

Optional. A specific settings group to retrieve. If NULL, all settings groups are returned.

Value

A list of default settings for Funnel charts or the specified settings group.

Examples

#' # Get all default settings for Funnel charts
funnel_default_settings()
# # Get default settings for a specific group
funnel_default_settings("x_axis")

Generate a multi-indicator sigma chart

Description

Calculates a funnel plot independently for each indicator, then displays the selected target's funnel z-score for every indicator. Positive values are in the favourable direction.

Usage

misc(
  data,
  keys,
  numerators,
  denominators,
  indicators,
  target,
  groupings = NULL,
  tooltips,
  aggregations = list(numerators = "sum", denominators = "sum", tooltips = "first",
    labels = "first"),
  title = NULL,
  funnel_settings = NULL,
  outlier_settings = NULL,
  canvas_settings = NULL,
  misc_settings = NULL,
  bar_settings = NULL,
  line_settings = NULL,
  x_axis_settings = NULL,
  y_axis_settings = NULL,
  tooltip_settings = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL,
  return_objs = c("html_plot", "static_plot", "limits")
)

Arguments

data

A data frame containing the comparison population.

keys

A vector or column name identifying the funnel groups.

numerators

A numeric vector or column name containing numerators.

denominators

A numeric vector or column name containing denominators.

indicators

A vector or column name identifying indicators. A separate funnel calculation is performed for each value.

target

A single value from keys to display.

groupings

Optional vector or column name used to group indicator labels.

tooltips

An optional vector or column name, or a list of them, providing additional tooltips. Each is labelled by its name in the list, or otherwise by the supplied expression.

aggregations

A list of aggregation function names passed to funnel().

title

Optional chart title. See funnel() for the supported format.

funnel_settings, outlier_settings

Settings used for each indicator's funnel calculation. outlier_settings$improvement_direction may be conditionally formatted by indicator. Three-sigma detection is always enabled.

canvas_settings, misc_settings, bar_settings, line_settings, x_axis_settings, y_axis_settings

Optional chart settings. See misc_default_settings() for valid options.

tooltip_settings

Optional tooltip settings.

width, height

Optional chart dimensions in pixels.

elementId

Optional HTML element ID for the chart.

return_objs

Character vector containing any of "html_plot", "static_plot", and "limits".

Value

An object of class controlchart.

Examples

comparison <- data.frame(
  organisation = rep(LETTERS[1:4], 2),
  indicator = rep(c("Measure A", "Measure B"), each = 4),
  numerator = c(8, 5, 4, 6, 2, 4, 5, 3),
  denominator = 10
)
misc(
  comparison,
  keys = organisation,
  numerators = numerator,
  denominators = denominator,
  indicators = indicator,
  target = "A",
  return_objs = "limits"
)

Shiny bindings for multi-indicator sigma charts

Description

Shiny bindings for multi-indicator sigma charts

Usage

miscOutput(outputId, width = "100%", height = "400px")

renderMisc(expr, env = parent.frame(), quoted = FALSE)

Arguments

outputId

Output variable to read from.

width, height

Valid CSS dimensions.

expr

An expression that generates a MISC chart.

env

Environment in which to evaluate expr.

quoted

Whether expr is quoted.

Value

An interactive Shiny widget.

Get default settings for multi-indicator sigma charts

Description

Get default settings for multi-indicator sigma charts

Usage

misc_default_settings(group = NULL)

Arguments

group

Optional settings group. If NULL, all groups are returned.

Value

A list of MISC settings.

Generate interactive SPC chart

Description

Generate interactive SPC chart

Usage

spc(
  data,
  keys,
  numerators,
  denominators,
  groupings,
  indicators = NULL,
  xbar_sds,
  tooltips,
  labels,
  aggregations = list(numerators = "sum", denominators = "sum", groupings = "first",
    xbar_sds = "first", tooltips = "first", labels = "first"),
  title = NULL,
  canvas_settings = NULL,
  spc_settings = NULL,
  outlier_settings = NULL,
  nhs_icon_settings = NULL,
  scatter_settings = NULL,
  line_settings = NULL,
  x_axis_settings = NULL,
  y_axis_settings = NULL,
  date_settings = NULL,
  label_settings = NULL,
  tooltip_settings = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL,
  return_objs = c("html_plot", "static_plot", "limits")
)

Arguments

data

A data frame containing the data for the chart.

keys

A vector or column name representing the categories (x-axis) of the chart.

numerators

A numeric vector or column name representing the numerators for each category.

denominators

A numeric vector or column name representing the denominators for each category.

groupings

A vector or column name representing the grouping for each category.

indicators

A vector or list of vectors representing indicator categories for the summary table.

xbar_sds

A numeric vector or column name representing the x-bar and standard deviation values for each category.

tooltips

A vector or column name, or a list of them, representing additional tooltips for each category. Each is labelled by its name in the list, or else by the expression supplied.

labels

A vector or column name representing the labels for each category.

aggregations

A list of aggregation function names for each field if multiple values are provided for each key. Valid options are:

  • "first": returns the first value

  • "last": returns the last value

  • "sum": returns the sum of values

  • "mean": returns the mean of values

  • "min": returns the minimum value

  • "max": returns the maximum value

  • "median": returns the median value

  • "count": returns the count of values

title

Optional title to be added to the top of the chart. It can be a character string for the title text only, or a list with the following options:

  • text: Title text (default: NULL)

  • font_size: Font size of the title (default: "16px")

  • font_weight: Font weight of the title (default: "bold")

  • font_family: Font family of the title (default: "'Arial', sans-serif")

  • x: Horizontal (x) position of the title as a percentage (default: "50%")

  • y: Vertical (y) position of the title in pixels (default: 5)

  • text_anchor: Text anchor of the title (default: "middle")

  • dominant_baseline: Dominant baseline of the title (default: "hanging")

  • subtitle: Subtitle text, drawn below the title (default: NULL)

  • subtitle_font_size: Font size of the subtitle (default: "12px")

  • subtitle_font_weight: Font weight of the subtitle (default: "normal")

canvas_settings

Optional list of settings for the canvas, see spc_default_settings('canvas') for valid options.

spc_settings

Optional list of settings for the SPC chart, see spc_default_settings('spc') for valid options.

outlier_settings

Optional list of settings for outliers, see spc_default_settings('outliers') for valid options.

nhs_icon_settings

Optional list of settings for NHS icons, see spc_default_settings('nhs_icons') for valid options.

scatter_settings

Optional list of settings for scatter points, see spc_default_settings('scatter') for valid options.

line_settings

Optional list of settings for lines, see spc_default_settings('lines') for valid options.

x_axis_settings

Optional list of settings for the x-axis, see spc_default_settings('x_axis') for valid options.

y_axis_settings

Optional list of settings for the y-axis, see spc_default_settings('y_axis') for valid options.

date_settings

Optional list of settings for dates, see spc_default_settings('dates') for valid options.

label_settings

Optional list of settings for labels, see spc_default_settings('labels') for valid options.

tooltip_settings

Optional list of settings for tooltips, see spc_default_settings('tooltips') for valid options.

width

Optional width of the chart in pixels. If NULL (default), the chart will fill the width of its container.

height

Optional height of the chart in pixels. If NULL (default), the chart will fill the height of its container.

elementId

Optional HTML element ID for the chart.

return_objs

Character vector of object types to return. Valid values are:

  • "html_plot": Interactive htmlwidgets plot

  • "static_plot": Non-interactive SVG plot

  • "limits": Calculated control limits

Value

An object of class controlchart containing the interactive plot, static plot, limits, and a function to save the plot. When indicators are supplied, limits are a named nested list of data frames.

Shiny bindings for wrapper

Description

Output and render functions for using wrapper within Shiny applications and interactive Rmd documents.

Usage

spcOutput(outputId, width = "100%", height = "400px")

renderSpc(expr, env = parent.frame(), quoted = FALSE)

Arguments

outputId

output variable to read from

width, height

Must be a valid CSS unit (like '100%', '400px', 'auto') or a number, which will be coerced to a string and have 'px' appended.

expr

An expression that generates a wrapper

env

The environment in which to evaluate expr.

quoted

Is expr a quoted expression (with quote())? This is useful if you want to save an expression in a variable.

Value

Interactive Shiny widget for SPC chart

Interactive Shiny widget for funnel plot

Get default settings for SPC charts

Description

Retrieve the default settings for SPC charts or a specific settings group.

Usage

spc_default_settings(group = NULL)

Arguments

group

Optional. A specific settings group to retrieve. If NULL, all settings groups are returned.

Value

A list of default settings for SPC charts or the specified settings group.

Examples

#' # Get all default settings for SPC charts
spc_default_settings()
# # Get default settings for a specific group
spc_default_settings("x_axis")