Add a Staged Charts tutorial and make the 0.5 examples runnable (#144)

.github/workflows/ci.yml

@@ -65,6 +65,7 @@ jobs:
             docs/tutorials/derived-variables.ipynb \
             docs/tutorials/loss-function.ipynb \
             docs/tutorials/xbar-s-analysis.ipynb \
+            docs/tutorials/staged-charts.ipynb \
             docs/tutorials/signal-detection.ipynb \
             docs/tutorials/stratified-analysis.ipynb \
             docs/tutorials/design-state-tour.ipynb \

CHANGELOG.md

@@ -29,6 +29,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `phase`, `subgroups`, `N`, `center`, `s_bar`, `sigma_hat`, `lpl`, `upl`. X/mR: `phase`, `points`,
   `center`, `mR_bar`, `lpl`, `upl`, per stratum on a stratified chart (`stratum=`, or through
   `focus()`). (#144)
+- **Docs: a Staged Charts tutorial**, executed in CI. On the bundled coffee-shop data, with the
+  stage derived by one `.bin()` call, it compares one set of limits with limits per stage on Xbar
+  and S, reads `phase_statistics()`, puts every reading on a phased X/mR chart, and pools or splits
+  a second factor. The chart-types guide's staged example now runs as written, and its pooling
+  example uses a study that has a factor to pool. (#144)
 
 ### Changed
 - **`formulate(response=..., factors=[])` with no time is the same study.** It used to treat the

README.md

@@ -82,6 +82,20 @@ The whole pipeline is one expression when you don't need the intermediate object
 pb.formulate(df, response='y', factors=['factor 1'], time='time').execute().plot()
 ```
 
+A process that changed on purpose gets its own limits for each stage with `phased=True`:
+
+```python
+import processbehavior as pb
+
+# The bundled coffee-shop data: a new machine in week 8, a new POS in week 12, new baristas from week 14
+pbd = pb.load_coffee_shop().bin('week', method='breaks', breaks=[8, 12, 14],
+                                bin_labels=['baseline', 'new machine', 'new POS', 'new baristas'],
+                                label='stage')
+staged = pbd.formulate(response='wait_sec', factors=['stage'], time='date').execute(chart='Xbar', phased=True, companion=True)
+staged.phase_statistics('Xbar')   # one row per stage: center, S-bar, sigma-hat, limits
+staged.plot(chart='Xbar', title='Wait time: limits per stage')
+```
+
 Use `pb.ProcessBehavior(df)` directly when you want the fluent derived-variable verbs
 (`.transform(...)`, `.bin(...)`), which attach before formulating. With that object in hand,
 `pbd.cols.<column_name>` provides IDE auto-completion for column references.
@@ -184,6 +198,7 @@ The full report renders to `validation/e2e_bishop_report.html`.
 - **Variance decomposition**: R1-R6 residuals for factorial designs
 - **Effects analysis**: Main effects, time effects, and interaction effects
 - **Stratified charts**: Automatic per-stratum limits for grouped individual data
+- **Staged charts**: `phased=True` gives each stage its own center and limits on X/mR and Xbar/S; `phase_statistics()` returns the numbers behind the steps
 - **Signal detection**: all eight Western Electric rules on X/mR; Rule 1 (3-sigma) on Xbar/S, where the run- and zone-based rules need a time order that subgroup comparisons don't have
 - **Beyond the charts**: capability indices (Cp/Cpk/Pp/Ppk), Taguchi loss decomposition, and maximum-information analysis — validated in the same Bishop-reference CI gate
 - **IDE support**: Column auto-completion via `ProcessBehavior(df).cols`

docs/myst.yml

@@ -41,6 +41,8 @@ project:
           title: Loss Function
         - file: tutorials/xbar-s-analysis.ipynb
           title: Xbar-S Analysis
+        - file: tutorials/staged-charts.ipynb
+          title: Staged Charts
         - file: tutorials/signal-detection.ipynb
           title: Signal Detection
         - file: tutorials/stratified-analysis.ipynb

docs/reference/api.md

@@ -344,11 +344,12 @@ limits step within the phase). On X/mR: `phase`, `points`, `center`, `mR_bar`, `
 stratum: pass `stratum=`, or call it on `focus(stratum)`. It raises `ValidationError` on a
 chart that is not phased.
 
-Phased metadata carries `phased=True`, `run_rules_applicable=False`, `phase_by` (the
-factors a phase is one combination of), `lane_boundaries` (the divider positions),
-`single_point_phases` and `insufficient_phases` (phases with no replicated subgroup,
-charted without limits). Phased Xbar/S refuses residual values, calibrations and
-`by=[time]`; see [Staged Xbar/S](../user-guide/chart-types.md#staged-xbars).
+Phased metadata carries `phased=True`, `run_rules_applicable=False`, `lane_boundaries`
+(the divider positions) and `single_point_phases`. Phased Xbar/S adds `phase_by` (the
+factors a phase is one combination of) and `insufficient_phases` (phases with no
+replicated subgroup, charted without limits). Phased Xbar/S refuses residual values,
+calibrations and `by=[time]`; see [Staged Xbar/S](../user-guide/chart-types.md#staged-xbar-s)
+and the [Staged Charts tutorial](../tutorials/staged-charts.ipynb).
 
 ### Plotting, reporting, export
 

docs/tutorials/index.md

@@ -11,11 +11,12 @@ These tutorials walk through ProcessBehavior from first chart to full factorial
 | 5 | [Derived Variables](derived-variables.ipynb) | Transforms and binning: deriving factors before formulating |
 | 6 | [Taguchi Loss Function](loss-function.ipynb) | Loss decomposition: 5 components, Pareto charts, PDC breakdown |
 | 7 | [Xbar-S Analysis](xbar-s-analysis.ipynb) | Subgrouped data: the S chart in its own right, residuals on S |
-| 8 | [Signal Detection](signal-detection.ipynb) | The 8 WECO rules: presets, RuleSet builder, per-rule drill-down |
-| 9 | [Stratified Analysis](stratified-analysis.ipynb) | One chart per stream: strata, focus(), stratified vs. combined |
-| 10 | [Design-State Tour](design-state-tour.ipynb) | All six design states classified live; the ODS-to-ADS collapse rule |
-| 11 | [Bishop Reference Validation](sds-validation.ipynb) | Slide-by-slide validation of PM SDS 1-3 against Bishop's Minitab output |
-| 12 | [Complete Design-State-1 Analysis](sds1-complete-analysis.ipynb) | The by= matrix, residual charts, effects & interaction plots |
+| 8 | [Staged Charts](staged-charts.ipynb) | A process that changed: limits per stage on Xbar/S and X/mR, phase_statistics() |
+| 9 | [Signal Detection](signal-detection.ipynb) | The 8 WECO rules: presets, RuleSet builder, per-rule drill-down |
+| 10 | [Stratified Analysis](stratified-analysis.ipynb) | One chart per stream: strata, focus(), stratified vs. combined |
+| 11 | [Design-State Tour](design-state-tour.ipynb) | All six design states classified live; the ODS-to-ADS collapse rule |
+| 12 | [Bishop Reference Validation](sds-validation.ipynb) | Slide-by-slide validation of PM SDS 1-3 against Bishop's Minitab output |
+| 13 | [Complete Design-State-1 Analysis](sds1-complete-analysis.ipynb) | The by= matrix, residual charts, effects & interaction plots |
 
 ## Prerequisites