runchart.Rmd

---
title: "runchart Quickstart Guide"
author: "Joseph Adams"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{runchart Quickstart Guide}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

## Introduction

>A run chart is a simple analytical tool that helps us understand changes in data over time. - [NHS Healthcare Improvement Scotland](http://www.healthcareimprovementscotland.org/previous_resources/implementation_support/guide_to_using_run_charts.aspx).

Run charts^[As defined by the NHS Scotland Quality Improvement Hub] are non-trivial to automate. A number of solutions exist in the healthcare improvement community in Scotland. However the author is only aware of small-scale solutions such as scripts and Excel macros.

These kinds of approaches have the following limitations:

* Version control is cumbersome and unrealistic.
* Adding a separate script to an existing workflow is inconvenient and error prone.
* Scripts are often written to operate under specific conditions; making wider adoption unlikely.
* Testing edge cases is a time consuming task which is replicated with each new script or macro.

The `runchart` package aims to overcome these limitations by exporting a single, well tested, function of the same name: `runchart()`.

## Getting Started
Install the package using like this:

```
# install.packages("devtools")
devtools::install_github('jsphdms/runchart')
```

<!-- The `runchart` package exports one simple function: `runchart()`. The only parameter is a numeric vector of non-zero length. It returns a data frame with 4 columns: `base`, `base_ext`, `shift`, and `val`. -->

For example:


Code for plotting the result might look like this:


## Things to Notice
There are several behaviours to notice in the plot above:

* **Rephasing** for each sustained shift (9 consecutive points all above/below the baseline).

* **Shifts** are identified (6 or more consecutive points all above/below the baseline).

* **Missing values** are ignored. For example the 27th data point above is missing, which causes the rephased baseline to be longer than the first.

* **Non-useful observations** are ignored. For example the 15th data point above lands exactly on the first baseline. Therefore it neither breaks nor contributes to the observed shift.

<!-- The `runchart()` function has been well tested using the `testthat` package to correctly handle such different scenarios and edge cases. -->