-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathREADME.Rmd
173 lines (106 loc) · 7.68 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/"
)
```
# runcharter <img src="man/figures/logo.png" width="160px" align="right" />
Automated analysis and re-basing of run charts at scale.
Online documentation and vignettes : [runcharter](https://www.johnmackintosh.com/runcharter/)
[](https://travis-ci.org/johnmackintosh/runcharter)
[](https://www.repostatus.org/#wip)
[](https://codecov.io/github/johnmackintosh/runcharter?branch=master)
## Installation
You can install runcharter from github with:
```{r gh-installation, eval = FALSE}
# install.packages("devtools")
devtools::install_github("johnmackintosh/runcharter")
# to ensure the vignettes are built or ensure latest version is installed:
devtools::install_github("johnmackintosh/runcharter",
build_vignettes = TRUE, force = TRUE)
```
## Rationale
Run charts are easy to create and analyse on an individual basis, hence they are widely used in healthcare quality improvement.
A run chart is a regular line chart, with a central reference line.
This central line, calculated using the median of a number of values over a baseline period, allows the QI team to assess if any statistically significant improvement is taking place, as a result of their improvement initiatives.
These improvements are denoted by certain patterns, or signals, within the plotted data points, in relation to the median line. The main signal is a run of 9 or more consecutive values on the desired side of the median line.
If this signal occurs as a result of improvement activities, but performance is not yet at the target level, a new median line can be plotted.
This is calculated using the median of the points that contributed to the signal. The aim is to then continue to work on improvement, measure and plot data, and look for the next sustained signal, until the improvement initiative is operating at its target level.
While this 'rebasing' (calculating new medians) is manageable for a few charts, it quickly becomes labour intensive as QI initiatives expand or further QI programmes are launched.
While enterprise level database software can be used to store the raw data, their associated reporting systems are usually ill suited to the task of analysing QI data using run chart rules.
This package automatically creates rebased run charts, based on the run chart rule for sustained improvement commonly used in healthcare ( 9 consecutive points on the desired side of the median).
All sustained runs of improvement, in the desired direction, will be highlighted and the median re-phased, using the points that contributed to the run.
Non useful observations (points on the median) are ignored and are not highlighted.
The main motivation is to analyse many charts at once, but you can also create and analyse a single run chart, or iterate, plot and save many individual charts.
## The runcharter function - input
The function requires a simple three column dataframe, with the following column names
- grp : a character column indicating a grouping variable to identify each individual run chart and for faceted plots
- date : a column of type 'date'.
- y : the variable / value to plot.
## runcharter function arguments
- df : a three column dataframe with columns named 'grp', 'date' and 'y' as specified above
- med_rows : How many rows / data points should the initial baseline median be calculated over?
- runlength : How long a run of consecutive points do you want to find, before you rebase the median?
The median will be rebased using all useful observations (points on the median are not useful, and are ignored).
- chart_title : The main title for the chart
- chart_subtitle : A subtitle for the chart
- direction : "above" or "below" the median, or "both". Use "both" if you want to rebase the run chart any time a run of the desired length occurs, even if it is on the "wrong" side of the median line.
- faceted : defaults to TRUE. Set to FALSE if you only need to plot a single run chart. This will ensure the chart plots correctly
- facet_cols : the number of columns in a faceted plot - only required if faceted is set to TRUE, otherwise ignored
- save_plot : Calls ggsave if TRUE, saving in the current working directory
- plot_extension : one of "png", "pdf" or other valid extension for saving ggplot2 plots. Used in the call to ggsave.
## example plot
```{r, fig.show='hold',fig.cap = "One plot, one run below the median"}
library(runcharter)
library(dplyr)
signals %>%
dplyr::filter(grp == "WardX") %>%
runcharter(med_rows = 13,
runlength = 9,
chart_title = "Analysis of runs below median",
chart_subtitle = "Ward X",
direction = "below",
faceted = FALSE)
```
## Plot explanation
- `med_rows` defines the initial baseline period. In the example below, the first 13 points are used to calculate the initial median. This is represented with a solid orange horizontal line.
This median is then used as a reference for the remaining values, denoted by the extending orange dashed line
- `runlength` specifies the length of run to be identified. Along with `direction`, which specifies which side of median represents improvement, the runlength is your target number of successive points on the desired side of the median (points on the median are ignored as they do not make or break a run). You can set the `direction` as either "above" or "below" the line, to evidence improvement in a specific direction.
Searching for runs in "both" directions is also possible. This might be more applicable for long term monitoring, rather than improvement purposes.
If a run is identified, the points are highlighted (the purple coloured points), and a new median is calculated using them. The median is also plotted and extended into the future for further run chart rules analysis, with a new set of solid and dashed horizontal lines.
The analysis continues, rebasing any further runs, until no more runs are found or there are not enough data points remaining.
## Example
By default the function returns a faceted plot, highlighting successive runs below the median:
```{r fig.height=5, fig.width =8}
library(runcharter)
runcharter(signals,
direction = "below",
facet_cols = 2)
```
You can also look for any run, in any direction
```{r}
library(runcharter)
runcharter(signals,
direction = "both",
facet_cols = 2)
```
Note how runs below the median are found for Wards X and Y, while a run above the median is highlighted for Ward Z.
The function will print the plot, and return a list, containing:
- a ggplot2 object,
- a dataframe / tibble containing the rows of data used to calculate the baseline median
- if applicable, a dataframe / tibble showing the points in each sustained period of improvement.
- the initial baseline median value
The latter 3 items can be retrieved from the list and used to create new plots (if, for example, you would like different plot themes or colours from the package defaults)
Don't try this at home - setting runlength of 6 and searching in both directions to confirm that successive runs are identified:
```{r fig.height=5, fig.width =8}
library(dplyr)
signals %>%
runcharter(med_rows = 6,
runlength = 6,
direction = "both")
```