processbehavior 0.3.1__tar.gz → 0.3.2__tar.gz

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

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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 +929,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.1...HEAD
+[Unreleased]: https://github.com/cnicholas/processbehavior/compare/v0.3.2...HEAD
+[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.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: processbehavior
-Version: 0.3.1
+Version: 0.3.2
 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.2}/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.2'
 
 # Result object
 from processbehavior.analysis_result import AnalysisResult

{processbehavior-0.3.1 → processbehavior-0.3.2}/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.2}/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.2}/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.2}/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.2/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]