processbehavior 0.3.2__tar.gz → 0.3.3__tar.gz

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

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-09-29
+
+### Changed
+- **Individuals and moving-range limits now use the constants exactly as Bishop's VAS manual
+  defines them.** The individuals-chart multiplier is 3/1.128 = 2.659574 (previously the
+  rounded 2.66) and the moving-range upper limit is 1 + 3(0.8525)/1.128 = 3.267287 (previously
+  3.268), built from the manual's d₂ = 1.128 and d₃ = 0.8525 (Eq 12.4, 12.5, 12.10, 12.11). The
+  manual prints the rounded values; Bishop's VAS software computes them without rounding, and PB's
+  X and mR limits now match it digit for digit (Medicare first chart: ±3838.32 and 4715.38).
+  Limits move by 0.016% and 0.02%, so a signal changes only for a point within that distance of a
+  limit. The d₂ used on the calibration path and by the maximum-information chart is now exactly
+  1.128 (it was 3/2.66 = 1.1278), and `MR_SIGMA_INTERVAL_80` was regenerated: five entries move
+  by 0.001. New constant `D3_N2` in `processbehavior.spc_constants`.
+
+### Added
+- Docs: the chart-types guide now explains the three views of a study with factors and
+  time (the combined ``by=[]`` chart, the ``phased=True`` view, and full stratification),
+  how to read a signal at a subgroup boundary on the combined chart (evidence about the
+  traversal, kept in the calculation deliberately because it reproduces Bishop's reference
+  limits), and which claims survive reordering the lanes, with the R5 chart's limits
+  caveat for DS 2 and 3. The ``phased`` view is documented in the user guide for the first
+  time. From the #114 discussion with @rabujamra, whose permutation check is
+  ``validation/mr_permutation_invariance.py``.
+
 ## [0.3.2] - 2026-09-15
 
 ### Fixed
@@ -929,7 +953,8 @@ 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.2...HEAD
+[Unreleased]: https://github.com/cnicholas/processbehavior/compare/v0.3.3...HEAD
+[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
 [0.3.0]: https://github.com/cnicholas/processbehavior/compare/v0.2.1...v0.3.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: processbehavior
-Version: 0.3.2
+Version: 0.3.3
 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

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

@@ -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.2'
+__version__ = '0.3.3'
 
 # Result object
 from processbehavior.analysis_result import AnalysisResult

{processbehavior-0.3.2 → processbehavior-0.3.3}/processbehavior/maximum_information.py

@@ -21,7 +21,7 @@ import numpy as np
 import pandas as pd
 
 from .exceptions import ValidationError
-from .spc_constants import R_UPPER_LIMIT_MULTIPLIER, XMR_LIMIT_MULTIPLIER
+from .spc_constants import D2_N2, R_UPPER_LIMIT_MULTIPLIER, XMR_LIMIT_MULTIPLIER
 
 if TYPE_CHECKING:
     from .analysis_dataset import AnalysisDataSet
@@ -48,9 +48,9 @@ class MaximumInformationResult:
     sigma_hat : float
         mR / d2 — noise floor sigma estimate.
     upl : float
-        Upper natural process limit (R2 mean + 2.66 * mR).
+        Upper natural process limit (R2 mean + E2 * mR, E2 = 3/1.128 ≈ 2.66).
     lpl : float
-        Lower natural process limit (R2 mean - 2.66 * mR).
+        Lower natural process limit (R2 mean - E2 * mR).
     n_signals : int
         Points beyond limits on XmR.
     round_to : int
@@ -159,9 +159,6 @@ class MaximumInformationResult:
 # Pure Function
 # ============================================================================
 
-# d2 for n=2 (moving range of consecutive pairs)
-_D2 = 1.128
-
 
 def assess_maximum_information(
     ads: AnalysisDataSet,
@@ -204,7 +201,7 @@ def assess_maximum_information(
     r2_mean = float(np.mean(r2_values))
     mr_values = np.abs(np.diff(r2_values))
     r2_mR = float(np.mean(mr_values))
-    sigma_hat = r2_mR / _D2
+    sigma_hat = r2_mR / D2_N2
 
     # Limits: mean ± E2 * mR
     upl = r2_mean + XMR_LIMIT_MULTIPLIER * r2_mR

{processbehavior-0.3.2 → processbehavior-0.3.3}/processbehavior/spc_constants.py

@@ -29,15 +29,19 @@ from .exceptions import ValidationError
 # Control limit multiplier (3-sigma limits are standard in SPC)
 SIGMA_MULTIPLIER = 3
 
-# E2 constant for XmR charts (n=2, moving range of 2 consecutive observations)
-# Used for calculating control limits on individual values
-# E2 = d2 / d3 for n=2, where d2 = 1.128 and d3 = 0.8525
-XMR_LIMIT_MULTIPLIER = 2.66
+# Moving-range constants for n = 2 (consecutive pairs), as in Bishop's VAS manual:
+# sigma = mR / d2 (Eq 12.4), X limits = X ± 3·mR/d2 (Eq 12.10-12.11), and the
+# moving-range upper limit = (1 + 3·d3/d2)·mR (Eq 12.5). The manual prints the
+# rounded values 2.66 and 3.268; Bishop's VAS software computes them from d2 and
+# d3 without rounding, and so does this library.
+D2_N2 = 1.128
+D3_N2 = 0.8525
 
-# D4 constant for R charts (n=2, range of 2 consecutive observations)
-# Used for upper control limit on moving range
-# D4 = 1 + 3(d3/d2) for n=2
-R_UPPER_LIMIT_MULTIPLIER = 3.268
+# E2 for XmR charts: X ± E2·mR, E2 = 3/d2 (≈ 2.66)
+XMR_LIMIT_MULTIPLIER = SIGMA_MULTIPLIER / D2_N2
+
+# D4 for the moving-range chart: upper limit = D4·mR, D4 = 1 + 3·d3/d2 (≈ 3.267)
+R_UPPER_LIMIT_MULTIPLIER = 1 + SIGMA_MULTIPLIER * D3_N2 / D2_N2
 
 
 # ============================================================================
@@ -260,8 +264,8 @@ def calculate_limits(
     -----
     Xbar limits: X̄ ± (3 * Wd) / sqrt(n), where Wd = S / c4(n)
     S limits: S * b3(n) to S * b4(n)
-    XmR limits: X̄ ± (E2 * mR), where E2 = 2.66
-    R limits: 0 to mR * D4, where D4 = 3.268
+    XmR limits: X̄ ± (E2 * mR), where E2 = 3/d2 = 3/1.128 (≈ 2.66)
+    R limits: 0 to mR * D4, where D4 = 1 + 3·d3/d2 = 1 + 3(0.8525)/1.128 (≈ 3.267)
 
     References
     ----------
@@ -414,11 +418,8 @@ def calculate_limits_vectorized(
     return pd.DataFrame({'lpl': lpl, 'upl': upl}, index=index)
 
 
-# d2 bias constant for the n=2 moving range, derived from the library's own E2
-# (E2 = sigma_multiplier / d2 at n=2, with the default 3-sigma multiplier). Used
-# only on the calibration path so calibrated X/mR limits stay internally
-# consistent with the data-path XmR/R constants.
-D2_N2 = 3.0 / XMR_LIMIT_MULTIPLIER
+# calibrated_limits uses D2_N2 (defined with the XmR constants above), so
+# calibrated X/mR limits stay consistent with the data-path XmR/R constants.
 
 
 def calibrated_limits(
@@ -714,12 +715,12 @@ MR_SIGMA_INTERVAL_80: dict[int, tuple[float, float]] = {
     9: (0.618, 1.418),
     10: (0.637, 1.396),
     11: (0.656, 1.375),
-    12: (0.670, 1.360),
+    12: (0.670, 1.359),
     13: (0.680, 1.344),
-    14: (0.694, 1.330),
+    14: (0.694, 1.329),
     15: (0.703, 1.315),
     16: (0.714, 1.310),
-    17: (0.722, 1.300),
+    17: (0.721, 1.300),
     18: (0.730, 1.288),
     19: (0.739, 1.280),
     20: (0.745, 1.274),
@@ -728,9 +729,9 @@ MR_SIGMA_INTERVAL_80: dict[int, tuple[float, float]] = {
     23: (0.761, 1.253),
     24: (0.766, 1.249),
     25: (0.771, 1.243),
-    26: (0.775, 1.238),
+    26: (0.774, 1.238),
     27: (0.780, 1.234),
     28: (0.784, 1.229),
-    29: (0.787, 1.224),
+    29: (0.787, 1.223),
     30: (0.790, 1.220),
 }

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/fixtures/golden_masters/missing_values/mR_statistics.json

@@ -2,5 +2,5 @@
   "N": 2,
   "center": 0.707,
   "lpl": 0.0,
-  "upl": 2.312
+  "upl": 2.311
 }

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/fixtures/golden_masters/paired_xmr_r/X_statistics.json

@@ -1,6 +1,6 @@
 {
   "N": 1,
   "center": 49.085,
-  "lpl": 46.738,
+  "lpl": 46.739,
   "upl": 51.432
 }

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/fixtures/golden_masters/pathological_ordering/X_statistics.json

@@ -1,6 +1,6 @@
 {
   "N": 1,
   "center": 49.774,
-  "lpl": 47.548,
+  "lpl": 47.549,
   "upl": 52.0
 }

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/fixtures/golden_masters/pathological_ordering/mR_statistics.json

@@ -2,5 +2,5 @@
   "N": 2,
   "center": 0.837,
   "lpl": 0.0,
-  "upl": 2.735
+  "upl": 2.734
 }

processbehavior-0.3.3/tests/fixtures/golden_masters/single_obs_strata/X_statistics.json

@@ -0,0 +1,6 @@
+{
+  "N": 1,
+  "center": 48.991,
+  "lpl": 45.23,
+  "upl": 52.753
+}

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/fixtures/golden_masters/single_obs_strata/mR_statistics.json

@@ -2,5 +2,5 @@
   "N": 2,
   "center": 1.414,
   "lpl": 0.0,
-  "upl": 4.622
+  "upl": 4.621
 }

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/fixtures/golden_masters/unstratified_small/X_statistics.json

@@ -1,6 +1,6 @@
 {
   "N": 1,
   "center": 49.213,
-  "lpl": 46.364,
+  "lpl": 46.365,
   "upl": 52.061
 }

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/fixtures/golden_masters/unstratified_small/mR_statistics.json

@@ -2,5 +2,5 @@
   "N": 2,
   "center": 1.071,
   "lpl": 0.0,
-  "upl": 3.5
+  "upl": 3.499
 }

{processbehavior-0.3.2 → processbehavior-0.3.3}/tests/test_spc_constants.py

@@ -12,6 +12,10 @@ import pandas as pd
 import pytest
 
 from processbehavior.spc_constants import (
+    D2_N2,
+    D3_N2,
+    R_UPPER_LIMIT_MULTIPLIER,
+    XMR_LIMIT_MULTIPLIER,
     b3,
     b4,
     c4,
@@ -121,6 +125,34 @@ def test_b3_b4_raises_on_invalid_n(func):
         func(1)
 
 
+# ============================================================================
+# Test: moving-range constants (n = 2)
+# ============================================================================
+
+
+class TestMovingRangeConstants:
+    """The XmR and mR constants follow Bishop's VAS manual (Eq 12.4, 12.5, 12.10, 12.11)
+    and are computed from d2 = 1.128 and d3 = 0.8525 without rounding, as VAS does."""
+
+    def test_building_blocks_are_the_manuals(self):
+        assert D2_N2 == 1.128
+        assert D3_N2 == 0.8525
+
+    def test_multipliers_are_the_manuals_formulas(self):
+        assert XMR_LIMIT_MULTIPLIER == 3 / D2_N2
+        assert R_UPPER_LIMIT_MULTIPLIER == 1 + 3 * D3_N2 / D2_N2
+
+    def test_multipliers_match_the_vas_software(self):
+        # Measured from Bishop's VAS charts: Medicare 3838.32 / 1443.21 and 4715.38 / 1443.21.
+        assert abs(XMR_LIMIT_MULTIPLIER - 2.659574) < 1e-6
+        assert abs(R_UPPER_LIMIT_MULTIPLIER - 3.267287) < 1e-6
+
+    def test_multipliers_round_to_the_manuals_printed_values(self):
+        # The manual prints 2.66 and 3.268 (3.686/1.128, with 3.686 itself rounded).
+        assert round(XMR_LIMIT_MULTIPLIER, 2) == 2.66
+        assert abs(R_UPPER_LIMIT_MULTIPLIER - 3.268) < 0.001
+
+
 # ============================================================================
 # Test: calculate_limits
 # ============================================================================
@@ -133,10 +165,10 @@ def test_b3_b4_raises_on_invalid_n(func):
         ('Xbar', dict(mean=10.0, sd=0.5, N=5), 9.286, 10.714, 0.01, 0.01),
         # S: sd=0.5, N=5 → LPL=0.5*b3(5)=0, UPL=0.5*b4(5)≈1.044
         ('S', dict(sd=0.5, N=5), 0.0, 1.044, 0.001, 0.01),
-        # XmR: mean=10, mR=0.3 → 10±2.66*0.3=10±0.798
-        ('XmR', dict(mean=10.0, mR=0.3), 10.0 - 2.66 * 0.3, 10.0 + 2.66 * 0.3, 0.001, 0.001),
-        # R: mR=0.3 → LPL=0, UPL=0.3*3.268
-        ('R', dict(mR=0.3), 0.0, 0.3 * 3.268, 0.001, 0.001),
+        # XmR: mean=10, mR=0.3 → 10 ± (3/1.128)·0.3 = 10 ± 0.7979
+        ('XmR', dict(mean=10.0, mR=0.3), 10.0 - 3 / 1.128 * 0.3, 10.0 + 3 / 1.128 * 0.3, 1e-12, 1e-12),
+        # R: mR=0.3 → LPL=0, UPL = (1 + 3·0.8525/1.128)·0.3
+        ('R', dict(mR=0.3), 0.0, (1 + 3 * 0.8525 / 1.128) * 0.3, 1e-12, 1e-12),
     ],
     ids=['Xbar', 'S', 'XmR', 'R'],
 )

processbehavior-0.3.3/tests/test_vas_chart_constants.py

@@ -0,0 +1,86 @@
+"""Individuals and moving-range chart limits match Bishop's VAS software.
+
+The expected values are read from Bishop's VAS output decks of 29 September 2026 (Medicare and
+PM SDS 2), at the precision the charts print. They pin the XmR constants E2 = 3/1.128 and
+D4 = 1 + 3(0.8525)/1.128 from the manual (Eq 12.4, 12.5, 12.10, 12.11): with the rounded 2.66 and
+3.268 the Medicare limits miss by 0.6 and 1.0, and the PM SDS 2 moving-range limit prints 2.84.
+"""
+
+from pathlib import Path
+
+import pandas as pd
+import pytest
+
+import processbehavior as pb
+
+VALIDATION = Path(__file__).resolve().parent.parent / 'validation'
+MEDICARE_CSV = VALIDATION / 'aco_per_capita_expenditure.csv'
+T100_CSV = VALIDATION / 'PBTESTDATABASE_T100.csv'
+
+
+# precision=6 so the comparison rounds once, at the precision VAS prints.
+@pytest.fixture(scope='module')
+def medicare():
+    df = pd.read_csv(MEDICARE_CSV)
+    return pb.formulate(df, response='PER CAPITA EXPENDITURE', factors=['ACO'], time='YEAR', precision=6)
+
+
+@pytest.fixture(scope='module')
+def pm_sds_2():
+    df = pd.read_csv(T100_CSV, na_values=['*'])
+    return pb.formulate(df, response='PM SDS 2', factors=['FACTOR 1', 'FACTOR 2'], time='PRODUCTION TIME', precision=6)
+
+
+class TestMedicareFirstChart:
+    """VAS MEDICARE ANALYSIS, slides 1-2: individuals chart ±3838.32, moving range 1443.21 / 4715.38."""
+
+    def test_individuals_half_width(self, medicare):
+        s = medicare.execute(chart='X', by=[]).get_statistics('X')
+        assert s['upl'] - s['center'] == pytest.approx(3838.32, abs=0.005)
+        assert s['center'] - s['lpl'] == pytest.approx(3838.32, abs=0.005)
+
+    def test_moving_range_limits(self, medicare):
+        s = medicare.execute(chart='mR', by=[]).get_statistics('mR')
+        assert s['center'] == pytest.approx(1443.21, abs=0.005)
+        assert s['upl'] == pytest.approx(4715.38, abs=0.005)
+
+
+class TestMedicarePerOrganisationCharts:
+    """VAS MEDICARE ANALYSIS, slides 3-6: the per-organisation individuals and moving-range charts.
+
+    VAS prints six significant figures and appears to place the printed limits about a centre line
+    already rounded to that precision (ACO-002: 12637.4 + 2169.97 = 14807.37, printed 14807.4; the exact
+    limit is 14807.346), so one-decimal values allow 0.1.
+    """
+
+    @pytest.mark.parametrize(
+        'aco, lpl, upl, lpl_tol, upl_tol',
+        [('ACO-001', 7503.91, 11991.3, 0.005, 0.05), ('ACO-002', 10467.4, 14807.4, 0.1, 0.1)],
+    )
+    def test_individuals_limits(self, medicare, aco, lpl, upl, lpl_tol, upl_tol):
+        t = medicare.execute(chart='X', by=['ACO']).chart_table()
+        row = t[t['subgroup'] == aco].iloc[0]
+        assert row['lpl'] == pytest.approx(lpl, abs=lpl_tol)
+        assert row['upl'] == pytest.approx(upl, abs=upl_tol)
+
+    @pytest.mark.parametrize('aco, center, upl', [('ACO-001', 843.62, 2756.36), ('ACO-002', 815.91, 2665.81)])
+    def test_moving_range_limits(self, medicare, aco, center, upl):
+        t = medicare.execute(chart='mR', by=['ACO']).chart_table()
+        row = t[t['subgroup'] == aco].iloc[0]
+        assert row['center'] == pytest.approx(center, abs=0.005)
+        assert row['upl'] == pytest.approx(upl, abs=0.005)
+
+
+class TestPmSds2FirstChart:
+    """VAS PM SDS 2 ANALYSIS, slides 1-2: 237.78 (235.47 / 240.09), moving range 0.87 / 2.83."""
+
+    def test_individuals_limits(self, pm_sds_2):
+        s = pm_sds_2.execute(chart='X', by=[]).get_statistics('X')
+        assert round(s['center'], 2) == 237.78
+        assert round(s['lpl'], 2) == 235.47
+        assert round(s['upl'], 2) == 240.09
+
+    def test_moving_range_limits(self, pm_sds_2):
+        s = pm_sds_2.execute(chart='mR', by=[]).get_statistics('mR')
+        assert round(s['center'], 2) == 0.87
+        assert round(s['upl'], 2) == 2.83

processbehavior-0.3.2/tests/fixtures/golden_masters/single_obs_strata/X_statistics.json

@@ -1,6 +0,0 @@
-{
-  "N": 1,
-  "center": 48.991,
-  "lpl": 45.229,
-  "upl": 52.754
-}