Skip to content

Commit

Permalink
Merge branch 'main' into issue_210
Browse files Browse the repository at this point in the history
  • Loading branch information
@francisbarton
francisbarton authored Aug 6, 2024
2 parents 54e7e0b + f261a14 commit 0718bb7
Show file tree
Hide file tree
Showing 5 changed files with 185 additions and 141 deletions.
14 changes: 6 additions & 8 deletions DESCRIPTION
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,26 +11,24 @@ Authors@R: c(
person("Chris", "Mainey", ,"[email protected]", "aut", comment = c(ORCID ="0000-0002-3018-6171")),
person("John", "MacKintosh", ,"[email protected]", "aut"),
person("Marcos", "Fabietti", ,"[email protected]", "aut"),
person("Fran", "Barton",
person("Fran", "Barton",
email = "[email protected]",
role = "aut",
comment = c(ORCID = "0000-0002-5650-1176")
),
person("NHS-R community",
),
person("NHS-R community",
email = "[email protected]",
role = "cph"
)
)
)
Maintainer: Christopher Reading <[email protected]>
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.
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,
https://github.com/nhs-r-community/NHSRplotthedots
BugReports: https://nhs-r-community.github.io/NHSRplotthedots/issues
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.2.3
RoxygenNote: 7.3.2
Roxygen: list(markdown = TRUE)
Imports:
assertthat,
Expand Down
114 changes: 80 additions & 34 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Please be aware that this package is in the early stages of development, and fea

## Installation

```{r, eval=FALSE}
```r
# install from CRAN
install.packages("NHSRplotthedots")

Expand All @@ -44,33 +44,38 @@ remotes::install_github("https://github.com/nhs-r-community/NHSRplotthedots", bu

# Overview

Welcome to the NHS-R community's package for building a specific type of statistical process control (SPC) chart, the
XmR chart. We are aiming to support NHS England's ['Making Data Count'][mdc] programme. The programme encourages boards,
managers, and analyst teams to present data in ways that show change over time and drive better understanding of
indicators than 'RAG' (red, amber, green) rated board reports often present.
Welcome to the NHS-R community's package for building a specific type of statistical process control (SPC) chart, the XmR chart.
We are aiming to support NHS England's ['Making Data Count'][mdc] programme.
The programme encourages boards, managers, and analyst teams to present data in ways that show change over time and drive better understanding of indicators than 'RAG' (red, amber, green) rated board reports often present.

The help files and vignettes within this package tell you more about the possible options for controlling the charts,
but below is a simple example of the type of chart the package produces. We will use the `ae_attendances` dataset from
the `{NHSRdatasets}` package and a bit of `{dplyr}` code to select some organisations.
The help files and vignettes within this package tell you more about the possible options for controlling the charts, but below are some simple examples of the type of chart the package produces.
We will use the `ae_attendances` dataset from the `{NHSRdatasets}` package and a bit of `{dplyr}` code to select some organisations.

```{r example, message=FALSE, warning=FALSE}
library(NHSRplotthedots)
library(NHSRdatasets)
library(tidyverse)
library(dplyr)
sub_set <- ae_attendances %>%
filter(org_code == "RQM", type == 1, period < as.Date("2018-04-01"))
sub_set %>%
ptd_spc(value_field = breaches, date_field = period, improvement_direction = "decrease")
ptd_spc(
value_field = breaches,
date_field = period,
improvement_direction = "decrease"
)
```

This plot is ok on its own, but we can specify more control options when we pass it on, using the `{dplyr}` pipe
function below: `%>%` to the plot argument.
This plot is ok on its own, but we can specify more control options if we explicitly pass it on to the `plot()` function.

```{r}
sub_set %>%
ptd_spc(value_field = breaches, date_field = period, improvement_direction = "decrease") %>%
ptd_spc(
value_field = breaches,
date_field = period,
improvement_direction = "decrease"
) %>%
plot(
y_axis_label = "4-hour wait breaches",
main_title = "SPC of A&E waiting time breaches for RQM"
Expand All @@ -79,79 +84,120 @@ sub_set %>%

or, equivalently:

```{r, eval=FALSE}
```r
sub_set %>%
ptd_spc(value_field = breaches, date_field = period, improvement_direction = "decrease") %>%
ptd_spc(
value_field = breaches,
date_field = period,
improvement_direction = "decrease"
) %>%
ptd_create_ggplot(
y_axis_label = "4-hour wait breaches",
main_title = "SPC of A&E waiting time breaches for RQM"
)
```
In addition, you can use summary() function to get some basic statistics about your SPC data frame.
You can also use the `summary()` function to get some basic statistics about your SPC data frame.
The function prints the SPC options, and then returns the summarised results as a table:
```{r, eval=TRUE}

```r
summary <- sub_set %>%
ptd_spc(value_field = breaches, date_field = period, improvement_direction = "decrease", target = 1200) %>%
ptd_spc(
value_field = breaches,
date_field = period,
improvement_direction = "decrease",
target = 1200
) %>%
summary()
```

You could assign this summary table to a variable and use it later:

```{r, eval=TRUE}
```r
summary$variation_type
summary$assurance_type
```


### Interactive plots with Plotly

It's also possible to generate interactive plots using the `{plotly}` package by replacing the call to `plot` with
`ptd_create_plotly`. This function takes the same arguments as `plot`/`ptd_create_ggplot`.
It's also possible to generate interactive plots using the `{plotly}` package by replacing the call to `plot` with `ptd_create_plotly`.
This function takes the same arguments as `plot`/`ptd_create_ggplot`.

```{r, eval=FALSE}
```r
sub_set %>%
ptd_spc(value_field = breaches, date_field = period, improvement_direction = "decrease") %>%
ptd_spc(
value_field = breaches,
date_field = period,
improvement_direction = "decrease"
) %>%
ptd_create_plotly(
y_axis_label = "4-hour wait breaches",
main_title = "SPC of A&E waiting time breaches for RQM"
)
```


### Adding annotations for mean and process limits

The package (from v0.2.0) supports annotating the values of the mean and the
upper and lower process limits on a secondary (right-hand side) y axis,
if this is helpful for you and your audience.

The way to achieve this is to turn on the `label_limits` option:

```{r}
sub_set |>
ptd_spc(
value_field = breaches,
date_field = period,
improvement_direction = "decrease"
) |>
ptd_create_ggplot(
y_axis_label = "4-hour wait breaches",
main_title = "SPC of A&E waiting time breaches for RQM",
label_limits = TRUE
)
```

If you have rebased the chart, the mean and process limit annotations will only show for the most recent section.


## Getting help

To find out more about the `ptd_spc()` function, you can view the help with:

```{r, eval=FALSE}
```r
?ptd_spc
```

Details on the extra plot controls can be found using:

```{r, eval=FALSE}
```r
?ptd_create_ggplot
```

To view the vignette (worked example), use:

```{r eval=FALSE}
```r
vignette("intro", package = "NHSRplotthedots")

vignette(package = "NHSRplotthedots")
```

# Contribution

This is an NHS-R Community project that is open for anyone to contribute to in any way that they are able. The project
is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.
This is an NHS-R Community project that is open for anyone to contribute to in any way that they are able.
The project is released with a [Contributor Code of Conduct][coc].
By contributing to this project, you agree to abide by its terms.

If you want to learn more about this project, please join the discussion at [the NHS-R Community Slack group][nhsr-slack]
and the specific channel [#proj-nhsr-plot-the-dots][#proj-nhsr-plot-the-dots].
If you want to learn more about this project, please join the discussion at
[the NHS-R Community Slack group][nhsr-slack] and the specific channel
[#proj-nhsr-plot-the-dots][ptd-slack-channel].

The simplest way to contribute is to raise an issue detailing the feature or functionality you would like to see added,
or any unexpected behaviour or bugs you have experienced.
The simplest way to contribute is to raise an issue detailing the feature or functionality you would like to see added, or any unexpected behaviour or bugs you have experienced.

[nhsr]: https://nhsrcommunity.com
[mdc]: https://www.england.nhs.uk/publication/making-data-count/
[coc]: https://contributor-covenant.org/version/2/1/CODE_OF_CONDUCT.html
[nhsr-slack]: https://nhsrcommunity.slack.com/
[#proj-nhsr-plot-the-dots]: https://nhsrcommunity.slack.com/archives/CSVD4SYF3
[ptd-slack-channel]: https://nhsrcommunity.slack.com/archives/CSVD4SYF3
73 changes: 37 additions & 36 deletions vignettes/deviations.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,42 +19,39 @@ library(NHSRplotthedots)
library(NHSRdatasets)
```

The overall intent of this package is to mimic as completely as possible the output available from the
[NHSEI Making Data Count][mdc] Excel tools. However, we have identified some areas where the R implementation
should deviate from the main Excel tools. We have done this only after careful consideration, and we believe there is a
benefit to deviating.
The overall intent of this package is to mimic as completely as possible the output available from the [NHSEI Making Data Count][mdc] Excel tools.
However, we have identified some areas where the R implementation should deviate from the main Excel tools.
We have done this only after careful consideration, and we believe there is a benefit to deviating.

This vignette documents what these differences are, and how to
set options to over-ride them, so that if you need to you can completely replicate the output that the Excel tools would create.
This vignette documents what these differences are, and how to set options to over-ride them, so that if you need to you can completely replicate the output that the Excel tools would create.

You may consider this important if for example you are publishing outputs from both the Excel tool and this R tool, and
need the outputs to be completely consistent.
You may consider this important if for example you are publishing outputs from both the Excel tool and this R tool, and need the outputs to be completely consistent.

## List of Deviations

### 1. Treatment of outlying points

By default, this package will screen outlying points, removing them from the moving range calculation, and hence from
the process limits calculation. This is in line with the published paper:
By default, this package will screen outlying points, removing them from the moving range calculation, and hence from the process limits calculation.
This is in line with the published paper:

> Nelson, LS, "Control Charts for Individual Measurements", Journal of Quality Technology, 1982, 14(34)
> Nelson, Lloyd S. (1982) Control Charts for Individual Measurements, _Journal of Quality Technology_ 14(3): 172-173
It is discussed further in the book:

> Lloyd P Provost & Sandra K Murray, The Health Care Data Guide: Learning from Data for Improvement (San Francisco, CA: Jossey-Bass, 2011), p.155 & p.192.
> Provost, Lloyd P. & Murray, Sandra K. (2011) _The Health Care Data Guide: Learning from Data for Improvement_, San Francisco, CA: Jossey-Bass, pp.155, 192

The Making Data Count" Excel tools do not screen outlying points, and all points are included in the moving range and
limits calculations. If outlying points exist, the process limits on the Excel tools will therefore be wider than if
outlying points were screened from the calculation.
The "Making Data Count" Excel tools do not screen outlying points, and all points are included in the moving range and limits calculations.
If outlying points exist, the process limits on the Excel tools will therefore be wider than if outlying points were screened from the calculation.

This behaviour is controlled by the `screen_outliers` argument. By default, `screen_outliers = TRUE`.
This behaviour is controlled by the `screen_outliers` argument.
By default, `screen_outliers = TRUE`.

To replicate the Excel method, set the argument `screen_outliers = FALSE`.

The two charts below demonstrate the default, and how to over-ride to replicate the Excel tools.

**R Package Default:**
#### R Package Default:

```{r}
data <- c(1, 2, 1, 2, 10, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1, 2, 1)
Expand All @@ -74,7 +71,7 @@ spc_data %>%
)
```

**Over-riding to replicate "Making Data Count" Excel output:**
#### Over-riding to replicate "Making Data Count" Excel output:

```{r}
# setting screen_outliers = FALSE produces the same output as Excel
Expand All @@ -90,21 +87,24 @@ spc_data %>%
)
```


### 2. Breaking of lines

By default, this package will break process and limit lines when a plot is rebased. The Excel tool draws all lines as
continuous lines. However, rebasing is a change to the process, so by breaking lines it more clearly indicates that a
change in process has happened.
By default, this package will break process and limit lines when a plot is rebased.
The Excel tool draws all lines as continuous lines.
However, rebasing is a change to the process, so by breaking lines it more clearly indicates that a change in process has happened.

This can be controlled with the `break_lines` argument.
There are 4 possible values:

This can be controlled with the `break_lines` argument. There are 4 possible values:
* "both" (default)
* "limit" (to just break the limit lines, but leave the process line connected)
* "process" (to just break the process line, but leave limit lines connected)
* "none" (as per the Excel tool).

Examples of these 4 are shown below:

**R Package Default:**
#### R Package Default:

```{r}
spc_data <- ae_attendances %>%
Expand All @@ -115,46 +115,47 @@ spc_data <- ae_attendances %>%
plot(spc_data, break_lines = "both")
```

**just breaking the limit lines:**
#### Just breaking the limit lines:

```{r}
plot(spc_data, break_lines = "limits")
```

**just breaking the limit lines:**
#### Just breaking the process lines:

```{r}
plot(spc_data, break_lines = "process")
```

**Over-riding to replicate "Making Data Count" Excel output:**
#### Over-riding to replicate "Making Data Count" Excel output:

```{r}
plot(spc_data, break_lines = "none")
```

### 3. X Axis Text Angle

As can be seen in the plots above, by default this package will print x axis text rotated by 45 degrees for better utilisation of space, and readability. Excel's behaviour is to print this text at 90 degrees to the axis.
As can be seen in the plots above, by default this package will print x axis text rotated by 45 degrees for better utilisation of space, and readability.
Excel's behaviour is to print this text at 90 degrees to the axis.

Text angle can be over-ridden by passing a ggplot `theme()` into the `theme_override` argument of the plot function. Any of the modifications documented in the [ggplot2 theme documentation](https://ggplot2.tidyverse.org/reference/theme.html) can be made, but in this case we just need to modify `axis.text.x`.
Text angle can be over-ridden by passing a ggplot `theme()` into the `theme_override` argument of the plot function.
Any of the modifications documented in the
[ggplot2 theme documentation][gg_theme]
can be made, but in this case we just need to modify `axis.text.x`.

**To re-instate 90 degree axis text:**
#### To re-instate 90 degree axis text:

```{r}
ae_attendances %>%
group_by(period) %>%
summarise(across(attendances, sum)) %>%
ptd_spc(attendances, period) %>%
plot(
theme_override = theme(
axis.text.x = element_text(angle = 90)
)
)
plot(theme_override = theme(axis.text.x = element_text(angle = 90)))
```

---
Find the package code on [GitHub](https://github.com/nhs-r-community/NHSRplotthedots)

Find the package code on [GitHub][ptd_gh].

[mdc]: https://www.england.nhs.uk/publication/making-data-count/
[gg_theme]: https://ggplot2.tidyverse.org/reference/theme.html
[ptd_gh]: https://github.com/nhs-r-community/NHSRplotthedots
Loading

0 comments on commit 0718bb7

Please sign in to comment.