processbehavior 0.3.3__tar.gz → 0.5.0__tar.gz

{processbehavior-0.3.3 → processbehavior-0.5.0}/CHANGELOG.md

@@ -7,6 +7,234 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-29
+
+This release adds staged (phased) Xbar and S charts, computed per stage as Dr. Bishop
+specified (2026-10-18), with `phase_statistics()` for the numbers behind each stage on both
+chart families. A column of values with no time is now charted in the order received.
+
+### Added
+- **A bare response is charted in the order received.** `formulate(response=...)` with no time,
+  factors or plan used to be refused. The values are now numbered 1..N in an `Observation` column
+  (the same numbers as `obs_id`) and the study is exactly the one `time='Observation'` gives: a
+  single stream, ADS 2, X/mR, sigma from N − 1 moving ranges. An NA response keeps its place as an
+  empty cell. The design report adds `Time: received order (no time column given)`. If the data
+  already has an `Observation` column, formulate asks you to pass it as `time=` or rename it (#129).
+- **Phased limits on Xbar and S charts.** `execute(chart='Xbar', phased=True)` gives each factor
+  combination its own centre line and limits on one chart, drawn as stepped lines with a divider at
+  each change, the way phased X/mR already does for its lanes. Each phase is computed as a separate
+  Xbar/S analysis, exactly as `by=[time]` computes one chart per condition: the centre is the mean of
+  the phase's subgroup means, with its own S-bar and sigma-hat (10-12 manual Eqs 11-5, 11-8, 11-9,
+  11-16, 11-17). `by=['stage', time]` pools the other factors into the subgroup and phases on the
+  stage; the centre is then the mean of the pooled subgroup averages, as Dr. Bishop specified
+  (2026-10-18). On Wheeler's four-cavity thickness data the per-cavity centres and limits match
+  Minitab's staged Xbar-S chart. Residual values, calibrations and `by=[time]` are refused with
+  messages that say what to use instead; a phase with no replicated subgroup keeps its points without
+  limits and is named in `metadata['insufficient_phases']`. (#144)
+- **`result.phase_statistics(chart, stratum=None)`.** One row per phase of a phased chart. Xbar/S:
+  `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
+  whole column as one replicated cell: ADS 1, a recommended one-point Xbar chart, the "within-cell
+  replication" series-length line, and an X chart plotted against the response values. Its chart
+  tables now start with `Observation` (#129).
+- **Xbar and S chart data carry `n`.** `get_chart('Xbar')` / `get_chart('S')`, and the Excel chart
+  sheets, gain an `n` column after the subgroup label. Unstratified Xbar/S metadata names the label
+  column as `group_col` (#143).
+- **Lane dividers on an Xbar or S chart are labelled with the phase.** These charts have no time
+  column and so no cell band under the axis, which is where X charts name their lanes. (#144)
+- **Phased chart data and `chart_table` carry a `phase` column** (the lane label) after the subgroup
+  label, on X/mR as well as Xbar/S. Phased Xbar/S metadata carries `phase_by`, `lane_boundaries`,
+  `single_point_phases` and `insufficient_phases`; `n_avg` is not reported on a phased chart, whose
+  `n_mode='average'` is applied per phase, so the per-phase mean size is `phase_statistics(chart)['N']`.
+  (#144)
+
+### Fixed
+- **Xbar/S `chart_table` keeps the subgroup label and `n` on every `by=`.** With a `by=` other than
+  time alone, such as a pooled subset (`by=['FACTOR 1', time]`), all factors, factors without time,
+  or one factor, the table dropped both columns, so a row couldn't be traced to its subgroup and
+  stepped limits went unexplained. `n` is now the aggregation's own count, which covers every cell
+  a pooled subgroup spans. This also corrects one row on residual charts whose limits rest on R2
+  (R1, R3, R4, R5) in a design with singletons: the stream's first cell, where R2 is undefined at
+  the first value, showed its cell size, not the one-fewer values its S and limits use. Limits,
+  centres and statistics are unchanged (#143).
+- **`execute()` no longer documents `phased=True` as requiring `by=[]`.** Stratified phasing of X/mR
+  (`by=['factor 1'], phased=True`) has been accepted since 75bcdd1; the docstring never caught up. (#144)
+- **The companion mR of a phased X chart reports `single_point_phases`.** Only the solo mR did. (#144)
+- **X/mR lane order honours an ordered pandas Categorical factor.** A stage column with categories
+  `before < after` already ordered the Xbar/S subgroups that way, but the canonical row order sorted
+  the raw labels, so X/mR lanes, phases and `strata` came out `after, before`. The canonical sort now
+  uses an ordered Categorical's category codes; plain string and numeric factors sort as before. (#144)
+
+## [0.4.0] - 2026-10-14
+
+This release aligns the library with Bishop's VAS documentation manual dated 10-12-2026 and
+reproduces his VAS runs of October 2026 (PM SDS, PM INERT, known-effects and Medicare decks).
+Equation numbers below are that manual's.
+
+### Changed
+- **R6's factor-level effect is the average of the condition effects over the level.** R6 = α_i + R2
+  with α_i the condition effects ρ̂_k = R5 - R2 averaged over the level (was the level's mean of R5,
+  Eq 14-24, "≈ α_i"). The two differ by the level's average R2, which Dr. Bishop notes is always
+  near 0; in ADS 1 it is 0 (R2 averages to zero in each cell). On ADS 2/3 it shows when levels are
+  small: Tom's Medicare run centres the organisation-effects chart at 10831.1 (PB was 10829.8, now
+  10831.1).
+- **R2 for designs with a one-observation subgroup (ADS 2 and 3) follows the manual.**
+  The data are first stripped of the process mean and the condition and period effects
+  (Z = Y − Ȳ_k − Ȳ_t + Ȳ, Eq 14-4 / 14-9), Z is differenced along the condition-then-time
+  sequence, and the difference is divided by twice the R2 scale factor
+  c(K, M) = √((K − 1)/(2K) · (1 − K/(M − 1))), computed from the layout (Eqs 14-5..14-13).
+  Previously R2 was half the difference of consecutive raw values, so every step from one
+  condition's last period to the next condition's first carried the level difference between
+  them, a common trend was read as noise, and the result sat on a smaller scale than σ. R3–R6,
+  the effects, maximum information and potential capability follow. PM SDS 2 R2 chart limits
+  ±1.94 → ±2.76, PM SDS 3 ±2.47 → ±3.70, potential Cp on PM SDS 2 (specs 232/242)
+  2.51 → 1.78; on the Medicare ACO file the R2 σ falls from about 1,023 to 300 and the
+  organisation chart (recentred R5 by ACO) flags 19 of 24 organisations instead of 8. ADS 1
+  R2 (within-cell deviation, Eq 14-3) is unchanged. `calculate_r2` now dispatches on
+  `r2_method` and takes `n_conditions`; its `n_per_cell` argument is gone.
+- **Taguchi loss follows the manual.** ADS 1 unexplained loss is the average cell
+  variance (1/KT)·ΣS²_kt, without dividing each S_kt by c4 (Eq 15-16). ADS 2/3 unexplained
+  loss is the sample variance of R2 (Eq 15-17; the 1/0.7 correction is gone), and the
+  interaction is what the other parts leave of the total loss (Ȳ − T)² + S², set to 0 when
+  negative (Eqs 15-18..15-20), so the parts add to the total. PM SDS 1 at target 237:
+  unexplained 23.0% → 20.9%, interaction 43.3% → 44.5%; PM SDS 2: interaction 42.5% → 25.6%,
+  unexplained 23.6% → 30.0%; pure noise (PM INERT) now shows 0% interaction in ADS 2/3.
+- **Re-centred residuals are the residual plus the process mean, the mean of the cell means
+  (Eq 14-26).** RCR3, RCR4 and
+  RCR5 were "reconstructed Y" (each algebraically Ȳ_kt + R2), so a recentred interaction
+  chart plotted close to the raw cell means. They now plot the effect plus R2 on the
+  measurement scale, as VAS does; RCR2 is unchanged. Xbar means by condition (RCR5) or
+  period (RCR4) are unchanged on complete designs; period effects are charted from R4.
+- **ADS 3 recommends the Xbar chart** (was X): Xbar/S is VAS's default for SDS 3 and 6.
+- **Capability is centred on the process mean as VAS computes it**: the unweighted mean of the
+  (factor × time) cell means, the same centre as the Xbar chart and the loss function, instead
+  of the plain average of the readings. `CapabilityResult.y_bar`, current PPL/PPU and the
+  potential centre (ȳ + mean(R2)) move when cells have different sizes (SDS 3, 4, 6); balanced
+  designs are unchanged. PM SDS 6 now reads PROCESS MEAN 237.86 and PPL 1.102 / PPU 0.78, as
+  Tom's VAS run does (was 237.834, 1.098 / 0.784).
+- **Validation gate re-referenced to Tom's 3 October 2026 VAS run**
+  (`validation/e2e_bishop_report.py`, `tests/fixtures/bishop_analyses/`). PM SDS 3 is checked
+  as Xbar/S, as VAS now draws it; its limits vary with subgroup size and are not printed on the
+  slides, so they carry no reference yet. The gate now reports 254 assertions passing and 61
+  with no reference value (was 280 / 35); PB's side is compared at full precision.
+- **The validation gate covers every VAS run on hand** (14 runs, 1155 assertions, was 3 runs and
+  254): PM SDS 1-6, PM INERT SDS 1-6 (the pure-noise column with each design state's missing-data
+  pattern), Tom's known-effects data (`validation/PBTESTKNOWNEFFECTS_T100.csv`, SDS 1) and the
+  Medicare ACO data (`validation/aco_per_capita_expenditure.csv`, 24 organisations x 4 years). Each
+  run's reference values, spec limits and target are in its own file,
+  `tests/fixtures/bishop_analyses/<run>.json` (the `vassds{1,2,3}analysis.json` references are
+  now `pm_sds_{1,2,3}.json`). All six PM runs use target 237; PM SDS 5's loss shares come from
+  Tom's rerun at 237 (8 October 2026), because his 10/3 run used the process mean.
+- **Limits VAS prints as "UNEQUAL" are checked against the lines it draws.** Where subgroup sizes
+  differ, VAS steps the limits per subgroup and prints no value; the gate now reads every
+  subgroup's LBL/UBL from the red limit lines in the VAS chart drawing (scaled by the y-axis ticks,
+  good to about one drawing unit) and compares PB subgroup by subgroup, to 1.5 drawing units. 186
+  charts in SDS 3-6; the gate reports 1475 assertions passing, 0 failing, and 79 with no
+  reference (was 1155 / 0 / 399).
+- **The R6 S charts are checked wherever VAS computed them correctly.** VAS's α<sub>N</sub>
+  (Eq 10-11) used Minitab's GAMMA function, which overflows above N = 343; the 10/3 VAS runs held
+  α<sub>N</sub> at 0.9995 from there on, so their S limits followed N = 500 whatever the subgroup size.
+  Dr. Bishop confirmed it (8 October 2026) and is replacing it with a table; PB computes α<sub>N</sub>
+  with log-gamma for any N. The gate now checks the R6 S charts whose subgroups are under 343 (all
+  match), the factor S charts' centerlines (one subgroup per factor level, as Dr. Bishop confirmed),
+  and PM SDS 5's loss shares from his rerun at 237; only the limits for subgroups of 343 or more
+  wait for his rerun. The references' notes now give that cause.
+- **Every R6 S chart in the PM runs is checked, against Dr. Bishop's reruns of 13 October 2026.**
+  His reruns of PM SDS 1-6 and PM INERT SDS 1-6 compute α<sub>N</sub> for every N. Against the
+  10/3 runs they change only the R6 S charts (pages 21, 25 and 27) and potential capability in
+  PM SDS 3 and 4. The limits for subgroups of 343 or more, pending until now, all match PB within
+  the gate's tolerances (36 assertions). The rerun's potential capability is now PB's value
+  to the digit it prints: PM SDS 3 Cp 1.58 and CPL 1.84 (PB 1.5751 and 1.8356; the 10/3 run
+  printed 1.57 and 1.83), and PM SDS 4 CPL 2.66 (PB 2.6555; was 2.65). The gate no longer lists
+  the per-factor loss shares (F1, F2, PDC Int) for a one-factor run such as Medicare, where they
+  don't exist. It reports 1547 assertions passing, 0 failing and 4 with no reference (was 1511 /
+  0 / 43): the known-effects factor S limits, whose 6 October run predates the fix.
+
+### Added
+- **R2 is reported unavailable, with the reason, when the R2 scale factor is undefined**
+  (fewer than two process design conditions, or M < K + 2 observations). `formulate()` warns;
+  R2–R6 are not offered; `execute()` and `why_not()` give the reason; `loss_function()` and
+  `maximum_information()` raise `ValidationError`; `capability()` reports potential capability
+  unavailable. Previously these layouts produced half-differences of the raw data.
+- **`CapabilityResult.potential_center`**: the centre of the potential values, ȳ + mean(R2).
+  Potential CPL/CPU and the potential chart's centre line use it, as VAS does (Medicare potential
+  PPU 5.74; ȳ alone gives 5.73). It equals ȳ in ADS 1.
+
+### Fixed
+- **Stratified charts take time in proportion to the data, however many strata there are.**
+  The stratified X/mR path looked each stratum up with a scan of the whole table, so its cost
+  grew with strata × rows. With every row its own condition, an X/mR pair took 48 s at 30,165
+  rows, and an estimated 80 minutes at 307,683 (a gene-expression study, 6,033 genes × 51
+  subjects). It now takes 0.2 s and 1.9 s. The same scan sat in the stratified Xbar/S loops and
+  the lane-boundary loop, the per-stratum limits were computed one `pd.Series` at a time, and
+  two lists of strata were searched as lists. Results are unchanged: every chart, statistic,
+  lane boundary and stratum list was compared before and after on the reference data and a
+  30,165-row gene-effects file. `scripts/benchmark.py` adds a one-row-strata scenario, and
+  `tests/test_performance.py` checks that it scales linearly. Stratified Xbar/S still costs
+  about 2.5 ms per stratum (15 s at 6,033): linear, but not yet vectorised.
+- **Charts with many lanes draw in a fraction of a second.** Each lane divider was added to the
+  figure with its own `add_shape` call, and plotly re-validates every shape already there, so the
+  cost grew with the square of the number of lanes: 800 dividers took 27 s, and an X chart of a
+  6,033-gene study (one lane per gene) would have taken about 25 minutes. They are now added in
+  one assignment, which builds the same figure (0.03 s for 800). Above 1,000
+  (`plotting.lane_boundaries.MAX_LANE_DIVIDERS`) none are drawn: the dividers would merge into a
+  solid band at any chart width.
+- **`detect_signals()` works on phased charts.** It raised `TypeError` on every `phased=True`
+  chart: each phase has its own centre, so the statistics carry `center=None`, and the zone
+  calculation read that scalar. The chart already marks run rules not applicable, but only the
+  plot read the flag. Phased charts now get Rule 1 by default, judged against each phase's
+  limits, with the same points the chart flags; an explicit rule list runs as given, against each
+  row's own centre. The limits and the flagged points on the chart were always correct.
+- **`value='response'` charts the response**, as the `execute()` signature and docstring say.
+  Every chart refused it ("Valid charts for RESPONSE: None"): residuals are told apart by a leading
+  `R`, which `RESPONSE` also has. `execute()`, `supports_calibration()` and `why_not()` now treat
+  it, in any case, exactly as `value=None`.
+- **Xbar and S charts with subgroups of unequal size follow the manual (Eqs 11-5, 11-16,
+  11-17).** sigma-hat is the average of each subgroup's S_r / c4(N_r) (was S-bar / c4(N_r)), and each
+  subgroup's limits use its own N_r, so they step with subgroup size, as VAS draws them. N_r now
+  counts the values the chart is drawn from (was the response's count): on ADS 2 and 3 residual
+  charts, R2's blank first value leaves one subgroup one smaller. Equal-size charts are unchanged.
+  Found on Tom's Medicare run (slides 52-53): ACO-001 has 3 R6 values, and its limits are wider by
+  sqrt(4/3) on the Xbar chart and use B4(3) on the S chart.
+- **Xbar charts include one-reading subgroups, as VAS draws them.** A subgroup with one value has
+  no S, so it takes no part in sigma-hat, but it is charted with limits centre ± 3 sigma-hat
+  (Eqs 11-16/17 with N_r = 1); it was left off the chart. The companion S chart still leaves it
+  out. On PM SDS 3 the Xbar chart now has all 800 subgroups (was 783) and on PM SDS 6 all 772
+  (was 642), matching the limit lines in Tom's VAS run subgroup by subgroup; on PM SDS 6's
+  interaction chart the one cell whose single reading has no R2 stays off, as in VAS. Designs
+  without one-reading subgroups (ADS 1) are unchanged.
+- **Per-stratum Xbar centre lines count one-observation subgroups.** The centre is Bishop's
+  unweighted mean of every subgroup mean; subgroups with n = 1 were dropped before it was
+  taken, which moved four of the eight PM SDS 3 per-condition centres by 0.01–0.04.
+- **Code and docs cite the manual's Chapters 10 and 12.** The X/mR limits and constants
+  (Eqs 12-1..12-11), c4 and the S-chart factors (Eqs 10-11, 10-12, 10-14), the cell and marginal
+  means (Eqs 10-7, 10-9) and the model the residuals estimate (Eq 10-3) now cite the manual where
+  the code computes exactly those equations, and every citation names the 10-12 edition (its
+  Chapter 10 drops the 10-1 edition's Eq 10-4, so Eqs 10-5..10-16 became 10-4..10-15); dotted
+  citations ("Eq 12.4") and an older manual's numbering in a test are gone.
+  `tests/test_manual_citations.py` keeps one citation form, and CONTRIBUTING.md describes it. The
+  residuals guide now says Ȳ is the mean of the cell means.
+- **Bishop's methodology is called the Variation Analysis System**, as his VAS documentation
+  manual names it (was "Variance Analysis System" in the README, docs, CITATION.cff, docstrings and
+  the design report's VAS line). The synthetic-data module no longer credits the design states to
+  Wheeler.
+- **Docs:** the three note blocks in the chart-types and design-state guides now render on the
+  MyST site (they used mkdocs syntax); the DS 4–6 chart tables and the no-factors branch of the
+  decision tree match what the library offers (a time-only study is DS 1, 2 or 3 by the number
+  of observations per time point, not DS 6); the R1 note no longer claims the residuals sum to
+  zero on unbalanced data (their cell means average to zero); R1 is cited as Eq 14-2, and the
+  design states are attributed to Bishop. The README's Validation section describes the gate as
+  it is (14 VAS runs, 1,547 assertions, SDS 4–6 included); it still described 3 runs and 254.
+
 ## [0.3.3] - 2026-09-29
 
 ### Changed
@@ -953,7 +1181,9 @@ and may change between minor versions until 1.0.
 - `natsort >= 8.0`
 - `plotly >= 5.18, < 7`
 
-[Unreleased]: https://github.com/cnicholas/processbehavior/compare/v0.3.3...HEAD
+[Unreleased]: https://github.com/cnicholas/processbehavior/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/cnicholas/processbehavior/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/cnicholas/processbehavior/compare/v0.3.3...v0.4.0
 [0.3.3]: https://github.com/cnicholas/processbehavior/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/cnicholas/processbehavior/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/cnicholas/processbehavior/compare/v0.3.0...v0.3.1

{processbehavior-0.3.3 → processbehavior-0.5.0}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use processbehavior in your research, please cite it as below."
-title: "processbehavior: Process Behavior Charts and Variance Analysis for Python"
+title: "processbehavior: Process Behavior Charts and Variation Analysis for Python"
 abstract: >-
-  A Python implementation of Thomas A. Bishop's Variance Analysis System (VAS):
+  A Python implementation of Thomas A. Bishop's Variation Analysis System (VAS):
   three-state design-state lineage detection (planned / observed / analytical),
   process behavior charts, R1-R6 residual variance decomposition, capability
   indices, and Taguchi loss functions. Analytical outputs are validated
@@ -17,11 +17,11 @@ authors:
 repository-code: "https://github.com/cnicholas/processbehavior"
 url: "https://cnicholas.github.io/processbehavior/"
 license: Apache-2.0
-version: 0.2.0
+version: 0.5.0
 keywords:
   - statistical process control
   - process behavior charts
-  - variance analysis
+  - variation analysis
   - control charts
   - quality control
   - shewhart
@@ -31,7 +31,7 @@ references:
   - type: book
     title: "The Scientific Basis for Modern Analytic Practice"
     abstract: >-
-      The methodological foundation for the Variance Analysis System this
+      The methodological foundation for the Variation Analysis System this
       package implements: applied-research foundations, scientific methodology,
       Shewhart's inductive analytic approach and process behavior charts,
       operational definitions and research protocols, and case studies.

{processbehavior-0.3.3 → processbehavior-0.5.0}/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to processbehavior
 
 Thanks for your interest. processbehavior is an implementation of Thomas A.
-Bishop's Variance Analysis System (VAS); methodology fidelity is more
+Bishop's Variation Analysis System (VAS); methodology fidelity is more
 important than feature volume. Smaller, well-validated changes are preferred.
 
 ## What this library is, and what it is not
@@ -77,12 +77,12 @@ residuals (R1–R5), DS detection, limit calculations, or variance
 decomposition must keep the relevant Bishop-reference tests green:
 
 ```bash
-pytest tests/test_bishop_reference.py -v
+pytest tests/test_bishop_reference.py -v   # skips unless Bishop's residual workbooks are present
 ```
 
 There is also a full end-to-end check that compares every chart center, control
-limit, capability index and loss component against Bishop's published Minitab
-results — 280 assertions across ADS 1–3:
+limit, capability index and loss component against Bishop's VAS runs for the
+10-12-2026 manual (PM SDS 1–6, PM INERT, his known-effects data and the Medicare data):
 
 ```bash
 python validation/e2e_bishop_report.py
@@ -97,6 +97,18 @@ summary.
 If a Bishop check fails after your change, the change is wrong — not the
 reference.
 
+## Citing the methodology
+
+Code and docs cite Bishop's VAS documentation manual by edition and equation number:
+`(10-12 manual Eq 14-8)`, `Eqs 14-4..14-13`, `Eqs 11-16/17`. Name the edition once per file and use
+the chapter-number form; `tests/test_manual_citations.py` checks both. The citations are read
+against the manual itself, so a new edition reports every place in the library whose equation
+changed or moved.
+
+Cite an equation only where the code computes exactly that equation. Where it computes something
+close (a different weighting, an approximation, a different sequence), say how it differs instead
+of citing it.
+
 ## Docs versioning
 
 The docs have one live version, deliberately, until 1.0:

{processbehavior-0.3.3 → processbehavior-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: processbehavior
-Version: 0.3.3
+Version: 0.5.0
 Summary: Python-native Process Behavior & Control Charts (spec-driven SPC with tidy outputs)
 Project-URL: Homepage, https://github.com/cnicholas/processbehavior
 Project-URL: Repository, https://github.com/cnicholas/processbehavior
@@ -89,7 +89,7 @@ Description-Content-Type: text/markdown
 [![codecov](https://codecov.io/gh/cnicholas/processbehavior/graph/badge.svg)](https://codecov.io/gh/cnicholas/processbehavior)
 [![License](https://img.shields.io/pypi/l/processbehavior.svg)](https://github.com/cnicholas/processbehavior/blob/main/LICENSE)
 
-A Python library for **Process Behavior Analysis** following Thomas A. Bishop's Variance Analysis System (VAS) methodology.
+A Python library for **Process Behavior Analysis** following Thomas A. Bishop's Variation Analysis System (VAS) methodology.
 
 Unlike traditional SPC packages, processbehavior faithfully implements Bishop's VAS equation-by-equation: automatic detection of the three-state design lineage (PDS / ODS / ADS), variance decomposition via R1-R6 residuals, and chart selection routed by the data your study can actually analyze.
 
@@ -108,6 +108,22 @@ pip install "processbehavior[images]"  # kaleido, for static plot images
 
 ## Quickstart
 
+A column of values, charted in the order received, is an X/mR chart in two calls:
+
+```python
+import pandas as pd
+import processbehavior as pb
+
+df = pd.DataFrame({'weight': [50.2, 49.8, 50.5, 50.1, 49.6, 50.9, 50.3, 49.9, 50.4, 50.0, 49.7, 50.6]})
+
+study = pb.formulate(df, response='weight')   # no time column: rows are numbered 1..N as 'Observation'
+result = study.execute(companion=True)        # X chart with its mR companion
+print(result.statistics('X'))                 # {'N': 1, 'center': 50.167, 'lpl': 48.619, 'upl': 51.714}
+result.plot()
+```
+
+When the data has a time order, factors, or both, name them. The design state routes the analysis:
+
 ```python
 import processbehavior as pb
 
@@ -149,6 +165,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.
@@ -231,17 +261,16 @@ for stratum in result.strata:
 
 ## Validation
 
-processbehavior's analytical outputs are continuously verified against Dr. Thomas A. Bishop's Minitab reference results. The validator at `validation/e2e_bishop_report.py` runs **280 numerical assertions** through the full formulate → execute → capability / loss / maximum-information pipeline:
-
-| Analytical Design State | Datasets validated | Assertions | Status |
-|---|---|---|---|
-| ADS 1 (full replication) | `PM SDS 1` from `PBTESTDATABASE_T100.csv` | 102 | ✅ all pass |
-| ADS 2 (no replication) | `PM SDS 2` | 89 | ✅ all pass |
-| ADS 3 (partial replication) | `PM SDS 3` | 89 | ✅ all pass |
+processbehavior's analytical outputs are verified against Dr. Thomas A. Bishop's VAS (Minitab-based) reference results on every push. The validator at `validation/e2e_bishop_report.py` runs **1,547 numerical assertions** through the full formulate → execute → capability / loss pipeline, across 14 of his VAS runs:
 
-Reference data is Bishop's published Minitab golden output. The library matches every chart center, control limit, signal classification, capability index, and loss-function value to within the precision Bishop reports.
+| VAS runs | Data | Analytical design states | Assertions | Status |
+|---|---|---|---|---|
+| `PM SDS 1`–`6` | `PBTESTDATABASE_T100.csv` | ADS 1, 2, 3 | 630 | ✅ all pass |
+| `PM INERT SDS 1`–`6` (pure noise) | `PBTESTDATABASE_T100.csv` | ADS 1, 2, 3 | 630 | ✅ all pass |
+| `PM SDS 1 KNOWN` (known effects) | `PBTESTKNOWNEFFECTS_T100.csv` | ADS 1 | 101 | ✅ all pass |
+| `Medicare ACO (PCE)` | `aco_per_capita_expenditure.csv` | ADS 2 | 186 | ✅ all pass |
 
-ODS 4–6 (incomplete-grid scenarios) are detected and routed correctly but their end-to-end Bishop-reference coverage is pending. The synthetic generators in `make_design(state=4|5|6)` produce data with the structural shape Bishop's Table 1 specifies; full numerical validation against Bishop's incomplete-grid Minitab output is on the roadmap (issue #109).
+Reference data is Bishop's VAS output for the 10-12-2026 manual (his runs of October 2026). The library matches every chart center, control limit, capability index and loss-function value that output prints, to within the precision Bishop reports. Where subgroup sizes differ, VAS prints "UNEQUAL" instead of a limit; there every subgroup's limits are read from the limit lines VAS draws and compared one by one. SDS 4–6 are incomplete grids (ODS 4–6), checked as the complete design that survives tidying (ADS 1–3). Four values, the factor S-chart limits of the known-effects run, wait for a VAS rerun. The per-run table is in `docs/reference/validation.md`.
 
 The full report renders to `validation/e2e_bishop_report.html`.
 
@@ -252,6 +281,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`

{processbehavior-0.3.3 → processbehavior-0.5.0}/README.md

@@ -6,7 +6,7 @@
 [![codecov](https://codecov.io/gh/cnicholas/processbehavior/graph/badge.svg)](https://codecov.io/gh/cnicholas/processbehavior)
 [![License](https://img.shields.io/pypi/l/processbehavior.svg)](https://github.com/cnicholas/processbehavior/blob/main/LICENSE)
 
-A Python library for **Process Behavior Analysis** following Thomas A. Bishop's Variance Analysis System (VAS) methodology.
+A Python library for **Process Behavior Analysis** following Thomas A. Bishop's Variation Analysis System (VAS) methodology.
 
 Unlike traditional SPC packages, processbehavior faithfully implements Bishop's VAS equation-by-equation: automatic detection of the three-state design lineage (PDS / ODS / ADS), variance decomposition via R1-R6 residuals, and chart selection routed by the data your study can actually analyze.
 
@@ -25,6 +25,22 @@ pip install "processbehavior[images]"  # kaleido, for static plot images
 
 ## Quickstart
 
+A column of values, charted in the order received, is an X/mR chart in two calls:
+
+```python
+import pandas as pd
+import processbehavior as pb
+
+df = pd.DataFrame({'weight': [50.2, 49.8, 50.5, 50.1, 49.6, 50.9, 50.3, 49.9, 50.4, 50.0, 49.7, 50.6]})
+
+study = pb.formulate(df, response='weight')   # no time column: rows are numbered 1..N as 'Observation'
+result = study.execute(companion=True)        # X chart with its mR companion
+print(result.statistics('X'))                 # {'N': 1, 'center': 50.167, 'lpl': 48.619, 'upl': 51.714}
+result.plot()
+```
+
+When the data has a time order, factors, or both, name them. The design state routes the analysis:
+
 ```python
 import processbehavior as pb
 
@@ -66,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.
@@ -148,17 +178,16 @@ for stratum in result.strata:
 
 ## Validation
 
-processbehavior's analytical outputs are continuously verified against Dr. Thomas A. Bishop's Minitab reference results. The validator at `validation/e2e_bishop_report.py` runs **280 numerical assertions** through the full formulate → execute → capability / loss / maximum-information pipeline:
-
-| Analytical Design State | Datasets validated | Assertions | Status |
-|---|---|---|---|
-| ADS 1 (full replication) | `PM SDS 1` from `PBTESTDATABASE_T100.csv` | 102 | ✅ all pass |
-| ADS 2 (no replication) | `PM SDS 2` | 89 | ✅ all pass |
-| ADS 3 (partial replication) | `PM SDS 3` | 89 | ✅ all pass |
+processbehavior's analytical outputs are verified against Dr. Thomas A. Bishop's VAS (Minitab-based) reference results on every push. The validator at `validation/e2e_bishop_report.py` runs **1,547 numerical assertions** through the full formulate → execute → capability / loss pipeline, across 14 of his VAS runs:
 
-Reference data is Bishop's published Minitab golden output. The library matches every chart center, control limit, signal classification, capability index, and loss-function value to within the precision Bishop reports.
+| VAS runs | Data | Analytical design states | Assertions | Status |
+|---|---|---|---|---|
+| `PM SDS 1`–`6` | `PBTESTDATABASE_T100.csv` | ADS 1, 2, 3 | 630 | ✅ all pass |
+| `PM INERT SDS 1`–`6` (pure noise) | `PBTESTDATABASE_T100.csv` | ADS 1, 2, 3 | 630 | ✅ all pass |
+| `PM SDS 1 KNOWN` (known effects) | `PBTESTKNOWNEFFECTS_T100.csv` | ADS 1 | 101 | ✅ all pass |
+| `Medicare ACO (PCE)` | `aco_per_capita_expenditure.csv` | ADS 2 | 186 | ✅ all pass |
 
-ODS 4–6 (incomplete-grid scenarios) are detected and routed correctly but their end-to-end Bishop-reference coverage is pending. The synthetic generators in `make_design(state=4|5|6)` produce data with the structural shape Bishop's Table 1 specifies; full numerical validation against Bishop's incomplete-grid Minitab output is on the roadmap (issue #109).
+Reference data is Bishop's VAS output for the 10-12-2026 manual (his runs of October 2026). The library matches every chart center, control limit, capability index and loss-function value that output prints, to within the precision Bishop reports. Where subgroup sizes differ, VAS prints "UNEQUAL" instead of a limit; there every subgroup's limits are read from the limit lines VAS draws and compared one by one. SDS 4–6 are incomplete grids (ODS 4–6), checked as the complete design that survives tidying (ADS 1–3). Four values, the factor S-chart limits of the known-effects run, wait for a VAS rerun. The per-run table is in `docs/reference/validation.md`.
 
 The full report renders to `validation/e2e_bishop_report.html`.
 
@@ -169,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`

{processbehavior-0.3.3 → processbehavior-0.5.0}/processbehavior/__init__.py

@@ -2,7 +2,7 @@
 ProcessBehavior - Statistical Process Control for Python
 
 A Pythonic library for process behavior analysis following Bishop's
-Variance Analysis System (VAS). The library models the data lifecycle
+Variation Analysis System (VAS). The library models the data lifecycle
 through three design states and routes analysis by what your data
 actually supports:
 
@@ -47,7 +47,7 @@ its ``.sds`` field. Internally some modules still use the legacy "SDS"
 prefix (e.g. ``sds_detector.py``); the model itself is three-state.
 """
 
-__version__ = '0.3.3'
+__version__ = '0.5.0'
 
 # Result object
 from processbehavior.analysis_result import AnalysisResult