processbehavior 0.2.0__tar.gz → 0.3.0__tar.gz

{processbehavior-0.2.0 → processbehavior-0.3.0}/CHANGELOG.md

@@ -7,6 +7,120 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-14
+
+### Added
+- **The design report states where sigma comes from at the observed structure and
+  series length.** One line under ``Structure``: ``Series length: T=4. Sigma for X/mR
+  rests on 3 moving ranges.`` With every cell replicated it reads ``Series length: T=1.
+  Sigma rests on within-cell replication.`` — a single time period is a complete study.
+  Exposed as ``study.series_length`` (``SeriesLengthPrecision``, frozen) and
+  ``study.series_length_description``. The result also carries ``within_cell_df`` and,
+  for the moving-range case, ``mr_interval_80`` — the p10/p90 of MRbar/d2 by n = 3..30
+  from ``MR_SIGMA_INTERVAL_80`` (``spc_constants``), generated by
+  ``validation/short_series_bands.py`` (contributed by @rabujamra in #114 / #119) — for
+  callers who want the numbers; the report prints only the sentence. It is a fact beside
+  the design state, not a judgment on it: no threshold, label, or warning, and the design
+  state, recommended chart and analysis menu do not move with T (pinned by test). Closes
+  the series-length half of #114.
+
+### Changed
+- **The R2 method for partial replication is reported as ``ma2``, not ``hybrid``.** The
+  docs described a per-cell hybrid for design state 3 (exact deviation where a cell has
+  n ≥ 2, moving average where n = 1) and said it was validated by Monte Carlo. The code
+  has not done that since cb037f8 (2026-03-05): with any singleton cell, R2 is Bishop's
+  ungrouped 2-point moving average over the full canonical sequence (Eq 13.7–13.9) for
+  every observation, and the 89 ADS 3 reference assertions hold against that. Only the word
+  survived, in six docs pages (three of which described it three different ways), the
+  detector's method token, the analysis-plan limitation text, two docstrings and two test
+  names. All now say what the code does. ``R2Method`` is ``Literal['exact', 'ma2']``;
+  ``SDSRegistry.get_r2_method`` returns ``'ma2'`` where it returned ``'hybrid'``;
+  ``get_sds_characteristics`` and ``SDSAnalysisPlan.residual_calculation_method`` use the
+  same two spellings in place of ``'within_cell'``, ``'moving_average'`` and ``'hybrid'``.
+  No arithmetic changed; none of these names is exported from the package top level.
+
+### Dependencies
+- ``plotly>=5.18,<8`` (was ``<7``). plotly 7.0.0 (2026-08-25) was tested against the full
+  suite before the bound moved: its breaking changes (mapbox traces, decimal-fraction
+  ``rgb()`` strings, ``hsv()``, Kaleido < 1.0, figure_factory) touch nothing here. #116.
+
+### Fixed
+- **A missing value in a factor column no longer makes a two-factor study fail.** With one
+  factor, rows with a blank factor value were dropped silently; with two or more, the
+  composite subgroup label was built before that drop and ``formulate`` raised
+  ``ValidationError: Cannot build RSG ... missing values in factor columns``. The same
+  file formulated with either factor alone and failed with both (a 85,101-row survey
+  file with 7,980 blank ``SURVEY QUESTION`` rows). Rows with no value in any factor
+  column now leave the analysis before the label is built, for any number of factors,
+  and the library says so with a ``ProcessBehaviorWarning`` naming the count per
+  factor. Response and time missing values are handled as before.
+- **``evaluate`` no longer raises on a constant column.** Binning a column with no spread
+  (every value identical) returned the documented no-spread result for ``equal_freq`` but
+  raised ``ValueError: Bin edges must be unique`` from ``pd.cut`` for ``equal_width`` and
+  ``sd``, because their fitted edges were identical yet finite and slipped past the guard.
+  The derivations module promises ``evaluate`` never raises on a routine state; a constant
+  column is one. All three methods now return the same no-spread result, whose ``fitted``
+  dict also carries ``n_bins: 0``, ``edges: []`` and ``labels: []`` so callers see one
+  shape. Explicit ``breaks`` on a constant column still bin. Found through the app on a
+  single-time-point file whose TIME column was a constant.
+
+## [0.2.1] - 2026-09-09
+
+### Fixed
+- **A short series no longer returns an unqualified all-clear from
+  ``detect_signals``.** ``SignalConfig.min_observations`` (default 20) was
+  unreachable: ``SignalDetector`` read a hardcoded per-rule table and never
+  consulted the config, so ``SignalConfig(min_observations=30)`` changed nothing.
+  Separately, the detector already recorded which rules it skipped for length
+  (``rules_skipped``, added in 0.2.0) but ``SignalResult.summary`` ignored that and
+  printed ``✓ No signals detected`` regardless. On a four-point X chart six of the
+  eight rules cannot fire, and the one that can is weakened by any trend in the
+  data, so the checkmark described an examination that had mostly not happened.
+
+  Now: the per-rule table is the *structural* minimum (``RULE_MIN_OBSERVATIONS``,
+  a rule is skipped below it, as before) and ``min_observations`` is the *advisory*
+  minimum. Below it the detector emits a ``ProcessBehaviorWarning`` naming both
+  numbers (one per chart evaluated; silence it with
+  ``warnings.simplefilter('ignore', ProcessBehaviorWarning)`` once a pipeline has
+  accounted for it) and the result is marked partial even when every runnable
+  rule ran.
+  ``SignalResult`` gains ``rules_evaluated``, ``rules_applicable``,
+  ``n_observations``, ``min_observations``, ``below_min_observations`` and
+  ``evaluation_note``; ``is_partial`` / ``evaluation_status`` now also reflect the
+  advisory threshold. A partial evaluation prints
+  ``⚠ Partial evaluation in X: 2 of 8 rules applicable at n=4 (...). No signals
+  from the rules evaluated.`` and the checkmark line is reserved for a complete
+  evaluation. Which rules run, and what they flag, is unchanged. Excel export's
+  Summary sheet adds evaluation status. Reported privately (GHSA-hw63-2x95-fmpv)
+  and in #114.
+- ``SECURITY.md`` supported-versions table said 0.1.x while the prose said 0.2.x.
+  The table now matches the prose.
+
+### Removed
+- **Seven never-called utilities from ``datasets.synthetic``** — ``make_edge_cases``
+  (unseeded, non-deterministic), ``compare_sds_characteristics`` (its docstring
+  table was factually wrong), ``validate_sds_detection`` (vacuous: it compared
+  ``observed_sds`` to the very value it was handed, so it always returned True),
+  ``generate_test_suite``, ``get_sds_info`` + ``print_sds_summary`` (a second,
+  drifting copy of ``SDSRegistry`` metadata), and ``make_large_dataset``. Zero
+  callers existed anywhere in the package, tests, docs, or examples.
+- ``SDSRegistry.print_all_analysis_plans`` and ``SDSRegistry.get_capability_matrix``
+  (same finding: no callers).
+- Dead branches: the Excel exporter's ``_write_stratified_summary_tab`` (unreachable
+  since stratified charts moved to the single-entry ``strata`` payload) and its
+  Series/scalar effects arms; the plotter's legacy underscore-name stratification
+  arm and unused ``_get_data_legend_name``; the ``Study`` arm of the loss
+  function's ``_coerce_ads`` (``assess_loss`` takes an ``AnalysisDataSet``).
+
+### CI / Infrastructure
+- **The Bishop validation gate now bites.** ``validation/e2e_bishop_report.py``
+  exits nonzero when any of its 280 assertions diverge from the reference values
+  (previously it only rendered PASS/FAIL into the report), the publish workflow
+  runs the same gate before any release, the four reference artifacts are
+  SHA-256-pinned by ``tests/test_reference_integrity.py`` and check out
+  byte-exact on every platform, and CODEOWNERS routes any change to the gate's
+  inputs through the maintainer.
+
 ## [0.2.0] - 2026-08-31
 
 ### Removed
@@ -755,7 +869,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.2.0...HEAD
+[Unreleased]: https://github.com/cnicholas/processbehavior/compare/v0.3.0...HEAD
+[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
 [0.2.0]: https://github.com/cnicholas/processbehavior/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/cnicholas/processbehavior/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/cnicholas/processbehavior/releases/tag/v0.1.0

{processbehavior-0.2.0 → processbehavior-0.3.0}/CONTRIBUTING.md

@@ -164,8 +164,12 @@ Releases are published to PyPI by the `Publish` workflow on tag push.
    in `CHANGELOG.md` and update the compare links at the bottom.
 3. Bump the version in `processbehavior/__init__.py` (`__version__`).
    `pyproject.toml` reads it via `[tool.hatch.version]`.
-4. Commit with subject `Release vX.Y.Z`, push to `main`.
-5. Tag and push:
+4. Run `python validation/e2e_bishop_report.py` and commit the regenerated
+   `docs/reference/validation.md`. Its header carries the version string, and
+   the publish workflow fails if the committed page has drifted from what the
+   validator writes.
+5. Commit with subject `Release vX.Y.Z`, push to `main`.
+6. Tag and push:
    ```bash
    git tag -s vX.Y.Z -m "Release vX.Y.Z"
    git push origin vX.Y.Z
@@ -173,7 +177,7 @@ Releases are published to PyPI by the `Publish` workflow on tag push.
    The tag push triggers `.github/workflows/publish.yml`, which builds,
    verifies with `twine check`, and uploads to PyPI via OIDC trusted
    publishing — no API tokens.
-6. Verify the release on https://pypi.org/project/processbehavior/ and run
+7. Verify the release on https://pypi.org/project/processbehavior/ and run
    `pip install processbehavior==X.Y.Z` in a fresh venv to confirm the
    README quickstart still runs end-to-end.
 

{processbehavior-0.2.0 → processbehavior-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: processbehavior
-Version: 0.2.0
+Version: 0.3.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
@@ -28,7 +28,7 @@ Requires-Python: >=3.10
 Requires-Dist: natsort>=8.0.0
 Requires-Dist: numpy>=1.23
 Requires-Dist: pandas<3,>=2.0
-Requires-Dist: plotly<7,>=5.18
+Requires-Dist: plotly<8,>=5.18
 Requires-Dist: typing-extensions>=4.0; python_version < '3.11'
 Provides-Extra: dev
 Requires-Dist: filelock>=3.20.3; extra == 'dev'
@@ -86,6 +86,7 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/processbehavior.svg)](https://pypi.org/project/processbehavior/)
 [![Python versions](https://img.shields.io/pypi/pyversions/processbehavior.svg)](https://pypi.org/project/processbehavior/)
 [![CI](https://github.com/cnicholas/processbehavior/actions/workflows/ci.yml/badge.svg)](https://github.com/cnicholas/processbehavior/actions/workflows/ci.yml)
+[![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.

{processbehavior-0.2.0 → processbehavior-0.3.0}/README.md

@@ -3,6 +3,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/processbehavior.svg)](https://pypi.org/project/processbehavior/)
 [![Python versions](https://img.shields.io/pypi/pyversions/processbehavior.svg)](https://pypi.org/project/processbehavior/)
 [![CI](https://github.com/cnicholas/processbehavior/actions/workflows/ci.yml/badge.svg)](https://github.com/cnicholas/processbehavior/actions/workflows/ci.yml)
+[![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.

{processbehavior-0.2.0 → processbehavior-0.3.0}/SECURITY.md

@@ -2,13 +2,13 @@
 
 ## Supported versions
 
-processbehavior is in **alpha** (0.1.x). Only the most recent 0.1.x release
-receives security fixes. 0.2.x is the supported line; 0.1.x is not patched.
+processbehavior is in **alpha**. Only the most recent 0.2.x release receives
+security fixes; 0.1.x is not patched.
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 0.1.x   | :white_check_mark: |
-| < 0.1   | :x:                |
+| 0.2.x   | :white_check_mark: |
+| < 0.2   | :x:                |
 
 ## Reporting a vulnerability
 

{processbehavior-0.2.0 → processbehavior-0.3.0}/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.2.0'
+__version__ = '0.3.0'
 
 # Result object
 from processbehavior.analysis_result import AnalysisResult

{processbehavior-0.2.0 → processbehavior-0.3.0}/processbehavior/analysis_dataset.py

@@ -183,7 +183,7 @@ class AnalysisDataSet:
             - n_cell_min: minimum observations per cell
             - n_cell_max: maximum observations per cell
             - K_obs: number of unique factor levels observed
-            - r2_method: 'exact', 'ma2', or 'hybrid'
+            - r2_method: 'exact' or 'ma2'
             Returns None if structure stats haven't been computed.
         """
         if self._structure_stats is None:

{processbehavior-0.2.0 → processbehavior-0.3.0}/processbehavior/analysis_result.py

@@ -1029,11 +1029,16 @@ class AnalysisResult:
         >>> from processbehavior.signals import SignalConfig
         >>> config = SignalConfig(
         ...     enabled_rules=['rule_1', 'rule_2'],
-        ...     min_observations=30,
+        ...     min_observations=30,   # below 30 points the result is marked partial
         ...     ignore_first_n=5
         ... )
         >>> signals = result.detect_signals(config=config)
 
+        A short series never returns an unqualified all-clear: when rules were
+        skipped for length, or the series is below ``min_observations``,
+        ``signals.is_partial`` is True and ``signals.summary`` says which rules
+        were evaluated.
+
         Access violations:
 
         >>> signals.by_rule['rule_2']  # Rule 2 violations

{processbehavior-0.2.0 → processbehavior-0.3.0}/processbehavior/data_preparation.py

@@ -16,6 +16,7 @@ Follows the Pythonic Hadley philosophy:
 from __future__ import annotations
 
 import logging
+import warnings
 from functools import reduce
 from typing import TYPE_CHECKING
 
@@ -24,7 +25,7 @@ import pandas as pd
 from natsort import natsorted
 from pandas.api.types import is_numeric_dtype
 
-from .exceptions import ColumnNotFoundError, FactorNotFoundError, ValidationError
+from .exceptions import ColumnNotFoundError, FactorNotFoundError, ProcessBehaviorWarning, ValidationError
 
 if TYPE_CHECKING:
     from .formulation_spec import FormulationSpec
@@ -281,6 +282,13 @@ class DataPreparation:
 
         # Add composite grouping variable if needed
         if spec.has_grouping:
+            # A row with no value in a factor column belongs to no cell, so it leaves the
+            # analysis here — for one factor or many. The single-factor path used to drop
+            # such rows silently via the rsg dropna below; the multi-factor path raised
+            # from _add_composite_column before reaching it, so the same file formulated
+            # with one factor and failed with two (Tom's survey file, 7,980 blank
+            # SURVEY QUESTION rows). Both paths now drop first and say so.
+            out = self._drop_rows_missing_factor_values(out, spec)
             out = self._add_grouping_column(out, spec)
 
             # Drop rows with missing values in analysis-critical columns BEFORE
@@ -533,6 +541,30 @@ class DataPreparation:
     # Private Helper Methods
     # ========================================================================
 
+    def _drop_rows_missing_factor_values(self, df: pd.DataFrame, spec: FormulationSpec) -> pd.DataFrame:
+        """
+        Drop rows with a missing value in any factor column, and report it.
+
+        Reported as a ``ProcessBehaviorWarning`` (the house style for "the
+        library changed your data on your behalf"), naming the count per
+        factor, so an analyst sees that 7,980 rows left the study rather than
+        discovering a smaller N later.
+        """
+        factor_cols = spec.rsg_vars_list
+        missing = df[factor_cols].isna()
+        if not missing.any().any():
+            return df
+        per_col = {col: int(n) for col, n in missing.sum().items() if n}
+        n_rows = int(missing.any(axis=1).sum())
+        warnings.warn(
+            f'Dropped {n_rows:,} of {len(df):,} rows with no value in a factor column: '
+            + ', '.join(f'{col} ({n:,} missing)' for col, n in per_col.items())
+            + '. A row with no factor value belongs to no cell, so it is excluded from the analysis.',
+            ProcessBehaviorWarning,
+            stacklevel=6,
+        )
+        return df.loc[~missing.any(axis=1)]
+
     def _add_grouping_column(self, df: pd.DataFrame, spec: FormulationSpec) -> pd.DataFrame:
         """
         Add composite grouping column (e.g., 'lane_head').

{processbehavior-0.2.0 → processbehavior-0.3.0}/processbehavior/datasets/__init__.py

@@ -6,18 +6,13 @@ from __future__ import annotations
 
 from .loaders import load_coffee_shop
 from .synthetic import (
-    compare_sds_characteristics,
-    generate_test_suite,
-    get_sds_info,
     make_design,
-    make_edge_cases,
     make_sds1,
     make_sds2,
     make_sds3,
     make_sds4,
     make_sds5,
     make_sds6,
-    print_sds_summary,
 )
 
 __all__ = [
@@ -28,10 +23,5 @@ __all__ = [
     'make_sds5',
     'make_sds6',
     'make_design',
-    'make_edge_cases',
     'load_coffee_shop',
-    'compare_sds_characteristics',
-    'generate_test_suite',
-    'get_sds_info',
-    'print_sds_summary',
 ]