Type: | Package |
Title: | Draw XmR Charts for NHSE/I 'Making Data Count' Programme |
Version: | 0.1.0 |
Maintainer: | Christopher Reading <christopher.reading1@nhs.net> |
Description: | Provides tools for drawing Statistical Process Control (SPC) charts. This package supports the NHSE/I programme 'Making Data Count', and allows users to draw XmR charts, use change points and apply rules with summary indicators for when rules are breached. |
URL: | https://nhs-r-community.github.io/NHSRplotthedots/ |
License: | MIT + file LICENSE |
Encoding: | UTF-8 |
RoxygenNote: | 7.1.2 |
Imports: | ggplot2, scales, dplyr, rlang, crayon, utils, NHSRdatasets, assertthat, grid |
Suggests: | covr, lintr, testthat (≥ 3.0.0), rmarkdown, knitr, mockery, withr, spelling |
VignetteBuilder: | knitr |
Config/testthat/edition: | 3 |
Language: | en-US |
NeedsCompilation: | no |
Packaged: | 2021-11-02 18:47:02 UTC; Giselle |
Author: | Christopher Reading [cre, aut],
Simon Wellesley-Miller [aut],
Zoƫ Turner |
Repository: | CRAN |
Date/Publication: | 2021-11-03 20:20:10 UTC |
Create ggplot2
Description
Creates a ggplot2 object using the parameters passed in.
Usage
ptd_create_ggplot(
x,
point_size = 4,
percentage_y_axis = FALSE,
main_title,
x_axis_label,
y_axis_label,
fixed_x_axis_multiple = TRUE,
fixed_y_axis_multiple = TRUE,
x_axis_date_format = "%d/%m/%y",
x_axis_breaks = NULL,
y_axis_breaks = NULL,
icons_size = 8L,
icons_position = c("top right", "bottom right", "bottom left", "top left", "none"),
colours = ptd_spc_colours(),
theme_override = NULL,
break_lines = c("both", "limits", "process", "none"),
...
)
Arguments
x |
an object created by |
point_size |
Specify the plotting point size for the ggplot output. Default is 2.5. |
percentage_y_axis |
Specify whether the y axis values are percentages. Accepted values are TRUE for percentage y axis, FALSE for integer y axis. Defaults to FALSE. |
main_title |
Specify a character string value for the ggplot title. |
x_axis_label |
Specify a character string value for the x axis title. |
y_axis_label |
Specify a character string value for the y axis title. |
fixed_x_axis_multiple |
Specify whether, if producing a faceted spc, x axis should be fixed for all facet plots. Accepted values are TRUE for fixed x axes or FALSE for individual x axes. |
fixed_y_axis_multiple |
Specify whether, if producing a faceted spc, y axis should be fixed for all facet plots. Accepted values are TRUE for fixed y axes or FALSE for individual y axes. |
x_axis_date_format |
Specify how dates on the x axis should be displayed. Format should be provided as a character string using 'd m Y' etc syntax. |
x_axis_breaks |
Specify an interval value for breaks on the x axis. Value should be a character string expressing interval length and type, e.g. "3 months", "7 days". |
y_axis_breaks |
Specify an interval value for breaks on the y axis. Value should be a numeric vector of length 1, either an integer for integer scales or a decimal value for percentage scales. This option is ignored if faceting is in use. |
icons_size |
The size of the icons, defined in terms of font size. Defaults to 8. |
icons_position |
Where to show the icons, either "top right" (default), "bottom right", "bottom left", "top left", or "none". |
colours |
Specify the colours to use in the plot, use the |
theme_override |
Specify a list containing ggplot theme elements which can be used to override the default appearance of the plot. |
break_lines |
whether to break lines when a rebase happens. Defaults to "both", but can break just "limits" lines, "process" lines, or "none". |
... |
currently ignored |
Value
The ggplot2 object
Rebase
Description
Produces an object that can be used for rebasing an SPC chart. This method provides two different ways to rebase:
You can either provide a single vector of dates, which will rebase every facet of an SPC with the same dates
You can provide named vectors of dates, where the names correspond to the names of the facets, in order to rebase a facetted chart
Usage
ptd_rebase(...)
Arguments
... |
either a single vector of dates, or, named vectors of dates. See examples. |
Value
a list
Examples
# if you aren't using a facetted chart, or you want to rebase each facet at the same dates, then
# you can simply call this method with a vector of dates. For example, to rebase on the 1^st^
# January 2020 and 22^nd^ March 2020:
ptd_rebase(as.Date(c("2020-01-01", "2020-03-22")))
# if you are using a facetted chart, and wish to rebase each facet with different dates, then
# you can call this method, naming each vector of dates with the name of the facet. If there are
# facet's that you don't need to rebase you can simply ignore them. For example, if you had a
# chart with facets "a", "b", and "c", and you wanted to rebase "a" on the 1^st^ January 2020,
# and "b" on the 22^nd^ March 2020:
ptd_rebase(
"a" = as.Date("2020-01-01"),
"b" = as.Date("2020-03-22")
)
SPC Plotting Function
Description
ptd_spc
returns a plot object or data table with SPC values using NHSI 'plot the dots' logic.
Usage
ptd_spc(
.data,
value_field,
date_field,
facet_field,
rebase = ptd_rebase(),
fix_after_n_points = NULL,
improvement_direction = "increase",
target = ptd_target(),
trajectory,
screen_outliers = TRUE
)
Arguments
.data |
A data frame containing a value field, a date field, and a category field (if for faceting). There should be no gaps in the time series for each category. |
value_field |
Specify the field name which contains the value data, to be plotted on y axis. Field name can be specified using non-standard evaluation (i.e. no quotation marks). |
date_field |
Specify the field name which contains the date data, to be plotted on x axis. Field name can be specified using non-standard evaluation (i.e. no quotation marks). |
facet_field |
Optional: Specify field name which contains a grouping/faceting variable. SPC logic will be applied to each group separately, with outputs combined. Currently accepts 1 variable only. Field name can be specified using non-standard evaluation (i.e. no quotation marks). |
rebase |
Specify a date vector of dates when to rebase, or, if facet_field is set, a named list of date vectors
of when to rebase. Each item in the list should be named after the facet you wish to rebase. See |
fix_after_n_points |
Specify a number points after which to fix SPC calculations. |
improvement_direction |
Specify whether process improvement is represented by an increase or decrease in measured variable, or is neutral. Accepted values are 'increase' for increase as improvement, 'decrease' for decrease as improvement, and 'neutral' where neither direction represents an improvement. Defaults to 'increase'. |
target |
Specify a single value, which will apply the same target to every facet of an SPC chart,
or named values of targets, where the names correspond to the names of the facets, in order to
have different targets for each facet. See |
trajectory |
Specify a field name which contains a trajectory value. Field name can be specified using non-standard evaluation (i.e. no quotation marks). |
screen_outliers |
Whether we should screen for outliers or not when calculating the control limits. Defaults to
|
Details
This function is designed to produce consistent SPC charts across Information Department reporting, according to the 'plot the dots' logic produced by NHSI. The function can return either a plot or data frame.
Value
A ggplot2 object of the spc charts. This will automatically print the plot, but can also be saved as an object if you want to manipulate it further.
Examples
library(NHSRdatasets)
library(dplyr)
data("ae_attendances")
# Pick a trust at random to look at their data for two years
trust1 <- subset(ae_attendances, org_code == "RJZ" & type == 1)
# Basic chart with improvement direction decreasing
ptd_spc(trust1,
value_field = breaches, date_field = period,
improvement_direction = "decrease"
)
# Pick a few trust, and plot individually using facet
# Also set the x-axis scale to vary for each and date groups to 3 months
orgs <- c("RAS", "RJZ", "RR1", "RJC", "RQ1")
trusts4 <- filter(ae_attendances, org_code %in% orgs, type == 1)
s <- ptd_spc(trusts4,
value_field = breaches, date_field = period, facet_field = org_code,
improvement_direction = "decrease"
)
plot(s, fixed_y_axis_multiple = FALSE, x_axis_breaks = "3 months")
# Save the first chart as an object this time then alter the ggplot theme
my_spc <- ptd_spc(trust1,
value_field = "breaches", date_field = "period",
improvement_direction = "decrease"
)
plot(my_spc) + ggplot2::theme_classic()
SPC Colours
Description
Produces a list of colours that controls the geoms in the plot
Usage
ptd_spc_colours(
common_cause = "#7B7D7D",
special_cause_improvement = "#289de0",
special_cause_neutral = "#361475",
special_cause_concern = "#fab428",
value_line = "#7B7D7D",
mean_line = "#000000",
lpl = "#7B7D7D",
upl = "#7B7D7D",
target = "#de1b1b",
trajectory = "#361475"
)
Arguments
common_cause , special_cause_improvement , special_cause_neutral , special_cause_concern |
the colour of the points |
value_line |
the colour of the line joining the points |
mean_line |
the colour of the "mean" (average) line |
lpl , upl |
the colour the the lower and upper process limit lines |
target |
the colour of the target line |
trajectory |
the colour of the trajectory line |
Value
a list of colours
Target
Description
Produces an object that can be used for adding Targets to an SPC chart. This method provides two different ways to add a target:
You can either provide a single value, which will apply the same target to every facet of an SPC
You can provide named values of targets, where the names correspond to the names of the facets, in order to have different targets for each facet
Usage
ptd_target(...)
Arguments
... |
either a single values, or, named values of targets. See examples. |
Details
This function is a helper to provide data in the correct format for use with ptd_spc()
. See Value
section for details of return type. If you are trying to do something like ptd_spc(list_of_values)
then you can
skip using the function and just use list_of_values
, so long as the list meets the requirements as listed above.
Value
returns either:
a single numeric value, in this case all facets in the plot will use this target value
a named list of single numeric values, where each item is named as for one of the facet's in the plot. If a facet isn't specified then it will not have a target
Examples
# if you aren't using a facetted chart, or you want to use the same target for each facet, you
# can simply call this method with a single value. For example, to use a target of 90%:
ptd_target(0.9)
# if you are using a facetted chart, and wish to use a different target for each facet, then you
# can call this method, naming each value with the name of the facet. Any facet that isn't listed
# will not have a target applied to it.
# For example, to apply a target of 25 to the "a" facet and 10 to the "b" facet:
ptd_target(
"a" = 25,
"b" = 10
)
# If you already have your data in a list, you do not need to use ptd_target(). But, if you
# wanted to check that your values are valid, you could call it like so:
my_targets <- list("a" = 25, "b" = 10)
do.call(ptd_target, my_targets)
# or, if your targets are in a numeric vector
my_targets <- c("a" = 25, "b" = 10)
do.call(ptd_target, as.list(my_targets))