---
title: "Getting started with shewhartr"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with shewhartr}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment  = "#>",
  fig.width  = 7,
  fig.height = 4.2,
  dpi = 96
)
```

```{r setup, message = FALSE}
library(shewhartr)
library(ggplot2)
library(dplyr)
```

This vignette walks through the typical workflow for using the
**shewhartr** package: pick a chart, fit it to historical data, inspect
the result, deploy the limits prospectively. We use built-in synthetic
datasets so everything is reproducible.

## Five minutes, three charts

We will hit three of the most common chart types. Each follows the same
pattern: a constructor that takes `data` first, returns an S3 object,
and works with `print()` and `autoplot()`.

### 1. An I-MR chart on individual measurements

`bottle_fill` is a 100-point time series of bottle-fill volumes. There
is no natural rational subgroup (bottles are filled one at a time), so
the right tool is the Individuals and Moving Range chart.

```{r}
fit_imr <- shewhart_i_mr(bottle_fill, value = ml, index = observation)
fit_imr
```

The print method shows control limits for both panels (the I chart and
the MR chart) and lists any rule violations. To see the chart:

```{r, eval = FALSE}
autoplot(fit_imr)
```

### 2. An Xbar-R chart on a subgrouped process

`tablet_weight` is a pharmaceutical weight dataset with 25 batches of
5 tablets each. The right tool is Xbar-R.

```{r}
fit_xbar <- shewhart_xbar_r(tablet_weight,
                            value    = weight,
                            subgroup = subgroup)
broom::glance(fit_xbar)
```

The Xbar chart limits use the constant $A_2(5) = 0.577$ from
Montgomery (2019, Appendix VI); see `?shewhart_constants` if you need
to inspect or extend the table.

### 3. A c chart on defect counts

`pcb_solder` records the number of defective solder joints on each of
50 inspected PCBs.

```{r}
fit_c <- shewhart_c(pcb_solder, defects = defects, index = board)
broom::tidy(fit_c)
```

For Poisson means below about 10, the normal approximation underlying
classical 3-sigma c-chart limits is poor (the 3-sigma lower limit can
even be negative). Box's advice — *don't transform if you can model
the right distribution* — applies. Try:

```{r}
fit_c_exact <- shewhart_c(pcb_solder, defects = defects, index = board,
                          limits = "poisson")
broom::tidy(fit_c_exact)
```

## Working with the result

Every chart object integrates with broom:

```{r}
broom::tidy(fit_imr)            # control-limit summary
broom::glance(fit_imr)          # one-row diagnostic
head(broom::augment(fit_imr))   # per-observation results
```

The `augment()` output has `.value`, `.center`, `.sigma`, `.upper`,
`.lower`, `.flag_<rule>` and `.flag_any` columns, ready for downstream
analysis or alternative plotting.

## Phase I and Phase II

A control chart serves two distinct purposes (Woodall 2000):

* **Phase I** — retrospective analysis on historical data, to identify
  out-of-control points and arrive at trustworthy in-control limits.
* **Phase II** — prospective monitoring of new data against those
  established limits.

The package draws this line in code via `calibrate()` and `monitor()`:

```{r}
# Suppose the first 60 bottles are our calibration baseline,
# and the next 40 are new data we want to monitor.
baseline <- bottle_fill[1:60, ]
new_obs  <- bottle_fill[61:100, ]

calib  <- calibrate(baseline, value = ml, index = observation,
                    chart = "i_mr")
alarms <- monitor(new_obs, calib)
alarms$violations
```

See the vignette `phase1-phase2` for the full discussion.

## A roadmap for the rest of the documentation

* **Variables charts**: deeper dive into I-MR, Xbar-R, Xbar-S, with
  the underlying constants and choice of sigma estimator.
* **Attributes charts**: p, np, c, u, including the exact Poisson
  alternative for low-mean count data.
* **Regression charts**: the package's flagship — control charts for
  trended processes.
* **ARL by simulation**: how to evaluate a chart's operating
  characteristics for any rule combination.
* **Diagnostics**: the Tukey-style residual panel and the Box-Cox
  guidance step.
* **COVID-19 case study**: the original use case, now as a vignette.

## References

* Montgomery, D. C. (2019). *Introduction to Statistical Quality
  Control* (8th ed.). Wiley.
* Woodall, W. H. (2000). Controversies and Contradictions in
  Statistical Process Control. *Journal of Quality Technology*,
  32(4), 341-350.
* Box, G. E. P., & Cox, D. R. (1964). An Analysis of
  Transformations. *Journal of the Royal Statistical Society B*,
  26(2), 211-252.