Package 'qiverse.qiplotly'

Title: Quality Improvement Plotly Charts
Description: Defines functions needed to generate SPC and Funnel Plots in Plotly.
Authors: Healthcare Quality Intelligence Unit (Western Australia Health) [aut, cre]
Maintainer: Healthcare Quality Intelligence Unit (Western Australia Health) <[email protected]>
License: GPL (>= 3) + file LICENSE
Version: 0.1.5
Built: 2026-05-28 02:41:13 UTC
Source: https://github.com/AUS-DOH-Safety-and-Quality/qiverse

Help Index

Draw a funnel plot in plotly

Description

Draw a funnel plot in plotly

Usage

fpl_plotly_create(
  numerator,
  denominator,
  group,
  data_type = "PR",
  allow_overdispersion = FALSE,
  multiplier = 1,
  better_is = "Higher",
  title = "",
  group_name = NULL,
  short_group_name = NULL,
  parent_group_name = NULL,
  parent_group_name_label = NA,
  funnel_period_start = NA,
  funnel_period_end = NA,
  y_limit_lower = NA,
  y_limit_upper = NA,
  x_axis_label = NA,
  y_axis_label = NA,
  highlight_group = NULL,
  highlight_outlier = TRUE,
  highlight_outlier_options = list(direction_to_flag = "Deterioration"),
  brand_colour = "#00667B",
  actual_colour = "black",
  annotation_marker_colour = "grey",
  line_width = 3,
  marker_size = 8,
  marker_symbol = "circle",
  y_dp = 1,
  y_format = "Percentage",
  pattern_text_ay = 50,
  pattern_arrow_width = 2,
  pattern_font_size = 15,
  target = NA,
  target_annotation = NA,
  target_options = list(legend_name = "Target", line_colour = "#FF0000", line_width =
    1.5, line_dash = "solid"),
  nhs_colours_enable = TRUE,
  nhs_colours_options = list(improvement_direction = better_is, direction_to_flag =
    "Both", colours = list(neutral = "#490092", improvement = "#00B0F0", deterioration =
    "#E46C0A", common_cause = "#A6A6A6")),
  show_legend = FALSE,
  legend_font_size = 12,
  source_text = "Healthcare Quality Intelligence Unit"
)

Arguments

numerator

A vector of the numerator (observed events/counts) values. Used as the 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 as HSMR, "PR" for proportions, or "RC" for ratios of counts. Default is "PR".
allow_overdispersion

A boolean value to allow the use of overdispersion control limits. Default is FALSE.
multiplier

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

A string identifying the direction that is favourable for the indicator. "Higher" for points below the lower control limit to be unfavourable, "Lower" for points above the upper control limit to be unfavourable, and "Neutral" if the direction is not stated. Default is "Higher".
title

A string for the title of the plot.
group_name

A vector of the group names that may differ from the initial group identifiers. I.e. group is an alphanumeric code and group_name is the actual name.
short_group_name

A vector of shortened group names to be displayed for highlighted groups and outlier points.
parent_group_name

A vector of parent group names which are to be displayed in the tooltip. These are the major categories for the groups.
parent_group_name_label

A string for the tooltip label on the parent group name.
funnel_period_start

A date (or character of format #' "yyyy-mm-dd") for the start date of the funnel period.
funnel_period_end

A date (or character of format #' "yyyy-mm-dd") for the end date of the funnel period.
y_limit_lower

A value denoting the y-axis lower limit range
y_limit_upper

A value denoting the y-axis upper limit range
x_axis_label

A value denoting the x-axis label. Usually NA or a specified label.
y_axis_label

A value denoting the y-axis label. Usually NA, a specified label or "Rate", for items which are proportion based with multipliers.
highlight_group

Optional group(s) to highlight individually
highlight_outlier

Boolean, if FALSE do not highlight outliers
highlight_outlier_options

Options to apply if highlight_outlier is TRUE. Default is list(direction_to_flag = "Deterioration"), where direction_to_flag can be "Deterioration", "Improvement" or "Both".
brand_colour

Hex code for the colour of the funnel limits. Default is "#00667b"
actual_colour

Hex code for the colour actual data points. Default is "black"
annotation_marker_colour

Hex code for the colour actual data points. Default is "grey"
line_width

A value denoting the width of the line in pixels (default = 3)
marker_size

A value denoting the size of the markers in pixels (default = 8)
marker_symbol

A value denoting the symbol type. See plotly documentation for further options (default = 'circle')
y_dp

Number of decimal points for the y-axis ticks and hoverinfo. Default is 1
y_format

Set to either "Numeric" or "Percentage" to format the y-axis. Default is "Percentage"
pattern_text_ay

Set the y offset for pattern detection text in pixels (default = 50)
pattern_arrow_width

Set the width of the pattern arrow in pixels (default = 2)
pattern_font_size

Numeric value for the font size of the annotation. Default is 15
target

Set a target value for the SPC chart. If NA, no target will be displayed. (default = NA)
target_annotation

A string to annotate the target line with a text on the plot. A value of NA indicates no annotation. (default = NA)
target_options

A list of parameters to set the target line:

  • legend_name: A string to set the legend name for the target line

  • line_colour: A hex code to set the colour of the target line

  • line_width: A numeric value to set the width of the target line

  • line_dash: A string to set the dash of the target line. Options are "solid", "dot", "dash", "longdash", "dashdot", "longdashdot"

(default = list(legend_name = "Target", line_colour = "#FF0000", line_width = 2, line_dash = "solid"))
nhs_colours_enable

A boolean to enable NHS colours for the SPC chart. (default = TRUE)
nhs_colours_options

A list of parameters to enable NHS colours for the SPC chart. (default = list(improvement_direction = better_is, direction_to_flag = "Both", colours = list(neutral = "#490092", improvement = "#00B0F0", deterioration = "#E46C0A", common_cause = "#A6A6A6"))
show_legend

A boolean to enable legend for the Funnel Plot (default = FALSE)
legend_font_size

A numeric value to set the font size of the legend (default = 12)
source_text

Set source text of the chart. If empty ("") or NA, no source will be displayed (default = "Healthcare Quality Intelligence Unit")

Value

Funnel plot in plotly for the specified indicator

Additional requirements for this function

The group vector must be a vector of unique values that are associated with a numerator and a denominator. Any summation of numerators and denominators by group must be done prior to input into this function.

Examples

## Not run: 
# Minimal Example

fpl_plotly_create(
  numerator = (sapply(1:5, function(x) rpois(5, x * 20 * 0.6)) |> c() -
                 (runif(25) * 10) |> round(0)) |>
    sapply(function(x) ifelse(x<0, 0, x)),
  denominator = sapply(1:5, function(x) rpois(5, x * 20)) |> c(),
  group = paste0('Q', 1:25),
  data_type = 'PR',
  multiplier = 1,
  better_is = "Higher",
  title = "Test Indicator",
  y_format = "Percentage",
  x_axis_label = "This is X Axis",
  y_axis_label = "This is Y Axis"
)

# Full Example
fpl_plotly_create(
  numerator = (sapply(1:5, function(x) rpois(5, x * 20 * 0.6)) |> c() -
                 (runif(25) * 10) |> round(0)) |>
    sapply(function(x) ifelse(x<0, 0, x)),
  denominator = sapply(1:5, function(x) rpois(5, x * 20)) |> c(),
  group = paste0('Q', 1:25),
  data_type = 'PR',
  multiplier = 1,
  better_is = "Higher",
  title = "Test Indicator",
  group_name = c("Alfa", "Bravo", "Charlie", "Delta", "Echo", "Foxtrot",
                 "Golf","Hotel", "India", "Juliett", "Kilo", "Lima", "Mike",
                 "November","Oscar", "Papa", "Quebec", "Romeo", "Sierra",
                 "Tango", "Uniform", "Victor", "Whiskey", "X-ray", "Yankee"),
  short_group_name = LETTERS[1:25],
  parent_group_name = "Code Words",
  parent_group_name_label = "Category",
  funnel_period_start = '2021-07-01',
  funnel_period_end = '2022-06-30',
  y_limit_lower = NA,
  y_limit_upper = 85,
  x_axis_label = "This is X Axis",
  y_axis_label = "This is Y Axis",
  highlight_group = c('Q2', 'Q5'),
  highlight_outlier = TRUE,
  nhs_colours_enable = TRUE,
  show_legend = FALSE,
  legend_font_size = 12,
  y_format = "Percentage",
  source_text = 'Healthcare Quality Intelligence Unit'
)

## End(Not run)

Draw a statistical process control chart in plotly

Description

Draw a statistical process control chart in plotly

Usage

spc_plotly_create(
  x,
  numerator,
  denominator = NULL,
  data_type = "p",
  multiplier = 1,
  better_is = "Lower",
  title = "",
  spc_period_start = NA,
  spc_period_end = NA,
  x_axis_label = NA,
  y_axis_label = NA,
  brand_colour = "#00667B",
  actual_colour = "black",
  annotation_marker_colour = "grey",
  line_width = 2,
  marker_size = 10,
  y_dp = 1,
  y_format = "Percentage",
  x_format = "%b %Y",
  patterns = "Yes",
  pattern_text_ay = 50,
  pattern_arrow_width = 2,
  pattern_font_size = 25,
  trend_size = 5,
  shift_size = 7,
  target = NA,
  target_annotation = NA,
  target_options = list(legend_name = "Target", line_colour = "#FF0000", line_width = 2,
    line_dash = "solid"),
  nhs_colours_enable = TRUE,
  nhs_colours_options = list(improvement_direction = better_is, direction_to_flag =
    "Both", colours = list(neutral = "#490092", improvement = "#00B0F0", deterioration =
    "#E46C0A", common_cause = "#A6A6A6")),
  nhs_icons_enable = FALSE,
  nhs_icons_options = list(flag_last_point_only = FALSE, sizex = 0.075, sizey = 0.15),
  show_legend = FALSE,
  legend_font_size = 12,
  source_text = "Healthcare Quality Intelligence Unit"
)

Arguments

x

A vector of the x-axis for the SPC chart. Usually dates.
numerator

A vector of the numerator (observed events/counts) values. Used as the 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. Only required when when necessary.
data_type

A string identifying the type of data used for in the plot, the adjustment used and the reference point. One of: "i" for indirectly standardised ratios, "p" for proportions, "r" for ratios of counts, "run" for run charts, "g" for geometric charts and "t" for time charts. Default is "p".
multiplier

Scale relative risk and funnel by this factor. Default to 1.
better_is

A string identifying the direction that is favourable for the indicator. "Higher" for points below the lower control limit to be unfavourable, "Lower" for points above the upper control limit to be unfavourable, and "Neutral" if the direction is not stated. Default is "Higher".
title

A string for the title of the plot.
spc_period_start

A date (or character of format #' "yyyy-mm-dd") for the start date of the SPC period.
spc_period_end

A date (or character of format #' "yyyy-mm-dd") for the end date of the SPC period.
x_axis_label

A value denoting the x-axis label. Usually NA or a specified label.
y_axis_label

A value denoting the y-axis label. Usually NA, a specified label or "Rate", for items which are proportion based with multipliers.
brand_colour

Hex code for the colour of the funnel limits
actual_colour

Hex code for the colour actual data points
annotation_marker_colour

Hex code for the colour actual data points
line_width

A value denoting the width of the line in pixels (default = 2)
marker_size

A value denoting the size of the markers in pixels (default = 10)
y_dp

Number of decimal points for the y-axis ticks and hoverinfo
y_format

Set to either "Numeric" or "Percentage" to format the y-axis
x_format

The format for the x-axis. Default is "%b %Y".
patterns

Either set to "Yes", "No" or as a dataframe with only a single row with the columns "Astro", "Trend", "TwoInThree", "Shift". This is the output of the runPat function in qiverse.qipatterns, or a filtered pattern dataframe. The "Yes" option automatically applies this function to the data. The "No" option does not display any patterns. (default = "Yes")
pattern_text_ay

Set the y offset for pattern detection text in pixels (default = 50)
pattern_arrow_width

Set the width of the pattern arrow in pixels (default = 2)
pattern_font_size

Numeric value for the font size of the annotation. Default is 25
trend_size

Set the number of points required for a trend to be detected (default = 5)
shift_size

Set the number of points required for a shift to be detected (default = 7)
target

Set a target value for the SPC chart. If NA, no target will be displayed. (default = NA)
target_annotation

A string to annotate the target line with a text on the plot. A value of NA indicates no annotation. (default = NA)
target_options

A list of parameters to set the target line:

  • legend_name: A string to set the legend name for the target line

  • line_colour: A hex code to set the colour of the target line

  • line_width: A numeric value to set the width of the target line

  • line_dash: A string to set the dash of the target line. Options are "solid", "dot", "dash", "longdash", "dashdot", "longdashdot"

(default = list(legend_name = "Target", line_colour = "#FF0000", line_width = 2, line_dash = "solid"))
nhs_colours_enable

A boolean to enable NHS colours for the SPC chart. (default = TRUE)
nhs_colours_options

A list of parameters to enable NHS colours for the SPC chart. (default = list(improvement_direction = better_is, direction_to_flag = "Both", colours = list(neutral = "#490092", improvement = "#00B0F0", deterioration = "#E46C0A", common_cause = "#A6A6A6"))
nhs_icons_enable

A boolean to enable NHS icons for the SPC chart. This option is only available if nhs_colours_enable is TRUE. (default = FALSE)
nhs_icons_options

A list of options for the NHS icons:

  • flag_last_point_only: A boolean to enable flagging of the last point only when determining the NHS icons. (default = FALSE)

  • sizex: A numeric value to set the size of the NHS icons as a proportion of the plot's width. (default = 0.075)

  • sizey: A numeric value to set the size of the NHS icons as a proportion of the plot's height. (default = 0.15) (default = list(flag_last_point_only = FALSE, sizex = 0.075, sizey = 0.15))

show_legend

A boolean to enable legend for the SPC Chart (default = FALSE)
legend_font_size

A numeric value to set the font size of the legend (default = 12)
source_text

Set source text of the chart. If empty ("") or NA, no source will be displayed (default = "Healthcare Quality Intelligence Unit")

Value

Statistical process control chart in plotly for the specific indicator and groups.

Additional requirements for this function

NA

Examples

## Not run: 
spc_plotly_create(
  x = seq(from = as.Date('2019-02-01'),
          to = as.Date('2022-01-01'),
          by = 'month')-1,
  numerator = c(20,25,17,22,18,18,30,29,18,23,17,18,
                15,17,19,21,30,19,15,17,22,24,20,13,
                14,18,14,21,17,27,24,30,25,24,26,24),
  denominator = c(86,91,99,110,96,110,96,97,105,87,94,89,
                  102,106,107,95,106,132,95,117,97,99,108,106,
                  101,96,96,98,105,117,94,77,97,90,106,107),
  data_type = 'p',
  multiplier = 1,
  better_is = "Lower",
  title = paste0("Example Indicator", " - ", "Hospital"),
  spc_period_start = "2019-01-01",
  spc_period_end = "2021-12-31",
  x_axis_label = "Date",
  y_axis_label = "Proportion",
  brand_colour = "#00667B",
  actual_colour = "black",
  annotation_marker_colour = "grey",
  y_dp = 1,
  y_format = "Percentage",
  x_format = "%b %Y",
  patterns = "Yes",
  pattern_text_ay = 50,
  trend_size = 5,
  shift_size = 7,
  nhs_colours_enable = TRUE,
  show_legend = FALSE,
  legend_font_size = 12,
  source_text = 'Healthcare Quality Intelligence Unit'
)

## End(Not run)