processbehavior 0.3.1__tar.gz → 0.3.3__tar.gz

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

@@ -7,6 +7,56 @@ 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
+- **Binning a heavily tied column no longer collapses to one bin.** 0.3.1 capped the
+  requested bin count at the number of distinct values *before* taking the quantiles, and on
+  a column of 3,000 ones and 1,000 twos the halved quantile positions both landed on 1, so
+  one bin fitted where 0.3.0 fitted two. When at least as many bins are requested as there
+  are distinct values, the fit now cuts at the midpoints between neighbouring values: one
+  bin per distinct value, every value in its own bin, with the message ``requested n bins,
+  ties produced k (one per distinct value)``. Requesting fewer bins than distinct values is
+  untouched (the original quantile / equal-width path). Found by the app's preview test.
+- **The connecting line on a lane chart no longer crosses lane boundaries.** On an X or mR
+  chart with factors and ``by=[]`` (one chart, subgroups side by side), the last point of
+  each subgroup was joined to the first point of the next, so every boundary drew a steep
+  rise or drop that was only the sort order. The line is now its own trace with a gap at
+  each boundary, drawn under the markers; the markers trace keeps hover, legend and
+  signal highlighting exactly as before. Single-series and faceted charts are unchanged. #121
+
+### Added
+- Docs: a user-guide page on series length and where sigma comes from (the position, the
+  n = 3..30 precision table from ``validation/short_series_bands.py`` with credit to
+  @rabujamra, the trending-series and not-one-process cautions, the formulation lesson from
+  #114, and the two-audiences position on run rules), and a user-guide page stating the
+  derived-variables contract (never raises, what counts as a violation, what bins promise,
+  what construction rejects).
+
 ## [0.3.1] - 2026-09-14
 
 ### Fixed
@@ -903,7 +953,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.1...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
 [0.2.1]: https://github.com/cnicholas/processbehavior/compare/v0.2.0...v0.2.1

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: processbehavior
-Version: 0.3.1
+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.1 → 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.1'
+__version__ = '0.3.3'
 
 # Result object
 from processbehavior.analysis_result import AnalysisResult

{processbehavior-0.3.1 → processbehavior-0.3.3}/processbehavior/derivations.py

@@ -528,19 +528,24 @@ def _fit_edges(spec: Derivation, present_vals: pd.Series):
         edges = [-math.inf, mu - 2 * sigma, mu - sigma, mu + sigma, mu + 2 * sigma, math.inf]
     else:
         n = params['n']
-        n_distinct = int(present_vals.nunique())
-        if n_distinct and n > n_distinct:
-            # More bins than distinct values can only produce empty bins.
-            message = f'requested {n} bins, only {n_distinct} distinct values; fitted {n_distinct}'
-            n = n_distinct
-        if method == 'equal_width':
+        distinct = np.unique(present_vals.to_numpy(dtype=float))
+        if len(distinct) >= 2 and n >= len(distinct):
+            # More bins than distinct values: one bin per distinct value, cut at the
+            # midpoints between neighbours. Capping n and re-taking quantiles instead
+            # collapsed heavily tied columns (3,000 ones and 1,000 twos fitted one bin);
+            # the requested-n quantiles interpolated between the values and left mostly
+            # empty bins when n was large.
+            mids = (distinct[:-1] + distinct[1:]) / 2.0
+            edges = [float(distinct[0]), *[float(m) for m in mids], float(distinct[-1])]
+            message = f'requested {n} bins, ties produced {len(distinct)} (one per distinct value)'
+        elif method == 'equal_width':
             lo, hi = float(present_vals.min()), float(present_vals.max())
             edges = list(np.linspace(lo, hi, n + 1))
         else:  # equal_freq
             qs = np.linspace(0.0, 1.0, n + 1)
             edges = list(np.unique(np.quantile(present_vals, qs)))
             if len(edges) - 1 != n:
-                message = f'requested {params["n"]} bins, ties produced {len(edges) - 1}'
+                message = f'requested {n} bins, ties produced {len(edges) - 1}'
     return edges, message
 
 

{processbehavior-0.3.1 → 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.1 → processbehavior-0.3.3}/processbehavior/plotting/renderers.py

@@ -35,6 +35,36 @@ if TYPE_CHECKING:
 # ---------------------------------------------------------------------------
 
 
+def _lane_positions(lane_boundaries, chart_name: str, n_rows: int) -> list[int]:
+    """0-based row positions where a new lane starts (excluding row 0), for this chart.
+
+    Accepts the flat ``list[dict]`` form or the per-stratum ``dict`` form of the
+    ``lane_boundaries`` metadata; returns ``[]`` when there are no boundaries.
+    """
+    if not lane_boundaries:
+        return []
+    if isinstance(lane_boundaries, dict):
+        lane_boundaries = lane_boundaries.get(chart_name) or []
+    positions = sorted({int(b['position']) for b in lane_boundaries if 0 < int(b['position']) < n_rows})
+    return positions
+
+
+def _with_gaps(values: list, positions: list[int], repeat: bool = False) -> list:
+    """Insert a gap entry before each position so Plotly breaks the line there.
+
+    For ``y`` the gap is ``None`` (a null y breaks the line). For ``x`` pass
+    ``repeat=True`` to insert the position's own x value instead, so the x array
+    stays numeric/categorical throughout and axis consumers never see a null.
+    """
+    out: list = []
+    cut = set(positions)
+    for i, v in enumerate(values):
+        if i in cut:
+            out.append(v if repeat else None)
+        out.append(v)
+    return out
+
+
 def _build_hover(
     data: pd.DataFrame,
     ctx: RenderContext,
@@ -136,10 +166,32 @@ def render_control_chart(
 
     # 2. Main data trace
     customdata, hovertemplate = _build_hover(data, ctx, value_col)
+    lane_positions = _lane_positions(spec.lane_boundaries, ctx.chart_name, len(data))
+    if lane_positions:
+        # Lane chart: the connecting line must not cross a lane boundary. The last point
+        # of one subgroup joined to the first of the next drew a steep "event" at every
+        # boundary that was only the sort order (#121). Draw the line as its own trace
+        # with a gap at each boundary, under the markers; the markers trace keeps the
+        # hover, customdata and legend exactly as before.
+        _add_trace(
+            fig,
+            go.Scatter(
+                x=_with_gaps(list(x_data), lane_positions, repeat=True),
+                y=_with_gaps(list(data[value_col]), lane_positions),
+                mode='lines',
+                line=dict(color=theme.data_color, width=ctx.line_width),
+                opacity=theme.data_opacity,
+                hoverinfo='skip',
+                showlegend=False,
+                name=f'{ctx.chart_name} (lanes)',
+            ),
+            row,
+            col,
+        )
     trace_kw = dict(
         x=x_data,
         y=data[value_col],
-        mode='lines+markers',
+        mode='markers' if lane_positions else 'lines+markers',
         name=ctx.chart_name,
         marker=dict(size=ctx.marker_size, color=theme.data_color),
         line=dict(color=theme.data_color, width=ctx.line_width),

{processbehavior-0.3.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → 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.1 → processbehavior-0.3.3}/tests/test_derivations.py

@@ -133,11 +133,18 @@ def test_equal_freq_labels_and_fitted_edges():
 
 
 def test_tie_drop_uses_fitted_count_labels_and_message():
+    """Fewer bins than distinct values, on a tied column: the quantile edges collide.
+
+    Requesting 4 bins on six 1s and one each of 2..5 puts three quartile edges on 1, so
+    only 2 bins fit. Labels are keyed on that fitted count, and the message says so.
+    (Requesting *at least* as many bins as distinct values now fits one per value; see
+    test_derivations_robustness.)
+    """
     tie = pd.Series([1, 1, 1, 1, 1, 1, 2, 3, 4, 5], dtype=float)
-    r = evaluate(Derivation.bin('t', n=5, bin_labels='ordinal'), tie)
-    assert r.fitted['n_bins'] == 3                      # qcut dropped duplicate edges
-    assert r.fitted['labels'] == ['Low', 'Medium', 'High']  # keyed on FITTED count, not 5
-    assert 'requested 5 bins' in r.message and 'produced 3' in r.message
+    r = evaluate(Derivation.bin('t', n=4, bin_labels='ordinal'), tie)
+    assert r.fitted['n_bins'] == 2  # quantile edges collided on the tied value
+    assert r.fitted['labels'] == ['Low', 'High']  # keyed on FITTED count, not 4
+    assert 'requested 4 bins' in r.message and 'produced 2' in r.message
 
 
 @pytest.mark.parametrize('method', ['equal_freq', 'equal_width', 'sd'])
@@ -252,8 +259,8 @@ def test_validate_structured_results():
 
 def test_validate_label_count_against_fitted_not_requested():
     df = pd.DataFrame({'t': [1, 1, 1, 1, 1, 1, 2, 3, 4, 5]})
-    # request 5 bins with 5 labels, but ties produce 3 bins -> mismatch caught
-    res = validate(Derivation.bin('t', n=5, bin_labels=['a', 'b', 'c', 'd', 'e']), df)
+    # request 4 bins with 4 labels, but ties produce 2 bins -> mismatch caught
+    res = validate(Derivation.bin('t', n=4, bin_labels=['a', 'b', 'c', 'd']), df)
     assert res.ok is False
     assert any(i['code'] == 'label_count' for i in res.issues)
 

{processbehavior-0.3.1 → processbehavior-0.3.3}/tests/test_derivations_robustness.py

@@ -183,11 +183,25 @@ class TestBinRobustness:
         r = evaluate(B('x', method='sd'), pd.Series([-0.085, -0.085, -0.085, -0.085000001]))
         assert r.fitted['n_bins'] == 5 and r.values.notna().all()
 
-    def test_more_bins_than_distinct_values_is_capped_with_a_message(self):
+    def test_more_bins_than_distinct_values_gives_one_bin_per_value(self):
         r = evaluate(B('x', n=1000), pd.Series(np.arange(1.0, 21.0)))
-        assert r.fitted['n_bins'] == 20 and 'only 20 distinct values' in r.message
+        assert r.fitted['n_bins'] == 20 and 'ties produced 20 (one per distinct value)' in r.message
+        assert r.values.value_counts(sort=False).tolist() == [1] * 20
         r = evaluate(B('x', method='equal_width', n=9), pd.Series([1.0, 2.0, 3.0]))
         assert r.fitted['n_bins'] == 3 and r.values.notna().all()
+        assert r.fitted['edges'] == [1.0, 1.5, 2.5, 3.0]
+
+    def test_heavily_tied_column_keeps_one_bin_per_distinct_value(self):
+        """Regression: capping n before the quantiles collapsed 3,000 ones + 1,000 twos to one bin."""
+        tied = pd.Series([1.0] * 3000 + [2.0] * 1000)
+        r = evaluate(B('x', n=4), tied)
+        assert r.fitted['n_bins'] == 2 and 'ties' in r.message
+        assert r.values.value_counts(sort=False).tolist() == [3000, 1000]
+
+    def test_fewer_bins_than_distinct_values_is_untouched(self):
+        """n below the distinct count takes the original quantile / linspace path."""
+        r = evaluate(B('x', n=4), pd.Series(np.arange(1.0, 21.0)))
+        assert r.fitted['edges'] == [1.0, 5.75, 10.5, 15.25, 20.0] and r.message is None
 
     def test_ordinal_beyond_five_bins_says_so(self):
         r = evaluate(B('x', n=6, bin_labels='ordinal'), pd.Series(np.arange(1.0, 61.0)))

processbehavior-0.3.3/tests/test_lane_connectors.py

@@ -0,0 +1,103 @@
+"""On a lane chart the connecting line breaks at every lane boundary (#121).
+
+One subgroup's last point used to be joined to the next subgroup's first point, so every
+boundary showed a steep rise or drop that was only the sort order. The line is now its own
+trace with a gap at each boundary; the markers trace keeps hover, customdata and legend.
+"""
+
+import numpy as np
+import pandas as pd
+
+import processbehavior as pb
+
+
+def _lane_study(n_lanes=3, T=4):
+    rng = np.random.default_rng(121)
+    rows = []
+    for k in range(n_lanes):
+        base = 100 * (k + 1)
+        for t in range(1, T + 1):
+            rows.append({'unit': f'U{k + 1}', 't': t, 'y': base + t + rng.normal(0, 0.1)})
+    return pb.formulate(pd.DataFrame(rows), response='y', factors=['unit'], time='t')
+
+
+def _traces(fig):
+    return {t.name: t for t in fig.data}
+
+
+def test_lane_chart_draws_the_line_with_one_gap_per_boundary():
+    fig = _lane_study(n_lanes=3, T=4).execute(chart='X', by=[], companion=True).plot(chart='X')
+    traces = _traces(fig)
+    line = traces['X (lanes)']
+    markers = traces['X']
+    assert line.mode == 'lines' and markers.mode == 'markers'
+    ys = list(line.y)
+    assert ys.count(None) == 2, 'three lanes -> two boundaries -> two gaps'
+    assert len([y for y in ys if y is not None]) == 12 and len(markers.y) == 12
+    # The gaps sit exactly at the lane starts (positions 4 and 8).
+    assert [i for i, y in enumerate(ys) if y is None] == [4, 9]
+
+
+def test_lines_never_join_two_lanes():
+    """No drawn segment spans a boundary: every consecutive non-gap pair is within a lane."""
+    fig = _lane_study(n_lanes=4, T=3).execute(chart='X', by=[], companion=True).plot(chart='X')
+    line = _traces(fig)['X (lanes)']
+    ys = list(line.y)
+    # Lanes are at 100, 200, 300, 400 (+ small t); any segment crossing a lane would jump ~100.
+    for a, b in zip(ys, ys[1:], strict=False):
+        if a is not None and b is not None:
+            assert abs(a - b) < 10, (a, b)
+
+
+def test_markers_keep_hover_and_the_line_has_none():
+    fig = _lane_study().execute(chart='X', by=[], companion=True).plot(chart='X')
+    traces = _traces(fig)
+    assert traces['X'].hovertemplate
+    assert traces['X (lanes)'].hoverinfo == 'skip' and traces['X (lanes)'].showlegend is False
+
+
+def test_single_series_chart_is_unchanged():
+    """No lanes -> the original single lines+markers trace, no extra trace."""
+    df = pd.DataFrame({'t': range(1, 13), 'y': np.arange(12, dtype=float)})
+    fig = pb.formulate(df, response='y', time='t').execute(chart='X', companion=True).plot(chart='X')
+    names = [t.name for t in fig.data]
+    assert 'X (lanes)' not in names
+    assert _traces(fig)['X'].mode == 'lines+markers'
+
+
+def test_faceted_charts_are_unchanged():
+    """by=['unit'] gives one panel per lane: no boundaries inside a panel, so no gaps."""
+    fig = _lane_study().execute(chart='X', by=['unit'], companion=True).plot(chart='X', facet=True, ncols=3)
+    assert not [t for t in fig.data if t.name and t.name.endswith('(lanes)')]
+
+
+# ---------------------------------------------------------------------------
+# The helpers, directly: both boundary shapes, out-of-range positions, both gap modes
+# ---------------------------------------------------------------------------
+
+
+def test_lane_positions_accepts_flat_and_per_stratum_boundaries():
+    from processbehavior.plotting.renderers import _lane_positions
+
+    flat = [{'position': 4, 'label': 'B'}, {'position': 8, 'label': 'C'}]
+    assert _lane_positions(flat, 'X', n_rows=12) == [4, 8]
+    per_stratum = {'X': flat, 'mR': [{'position': 3}]}
+    assert _lane_positions(per_stratum, 'X', n_rows=12) == [4, 8]
+    assert _lane_positions(per_stratum, 'mR', n_rows=12) == [3]
+    assert _lane_positions(per_stratum, 'Histogram', n_rows=12) == []
+    assert _lane_positions(None, 'X', n_rows=12) == [] and _lane_positions([], 'X', n_rows=12) == []
+
+
+def test_lane_positions_ignores_row_zero_and_out_of_range():
+    from processbehavior.plotting.renderers import _lane_positions
+
+    raw = [{'position': 0}, {'position': 5}, {'position': 5}, {'position': 12}, {'position': 99}]
+    assert _lane_positions(raw, 'X', n_rows=12) == [5]
+
+
+def test_with_gaps_inserts_none_for_y_and_repeats_x():
+    from processbehavior.plotting.renderers import _with_gaps
+
+    assert _with_gaps([10, 11, 12, 13], [2]) == [10, 11, None, 12, 13]
+    assert _with_gaps(['a', 'b', 'c', 'd'], [2], repeat=True) == ['a', 'b', 'c', 'c', 'd']
+    assert _with_gaps([1, 2, 3], []) == [1, 2, 3]

{processbehavior-0.3.1 → 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'],
 )