processbehavior 0.2.1__tar.gz → 0.3.0__tar.gz

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

@@ -7,6 +7,63 @@ 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
@@ -812,7 +869,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.2.1...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

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

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

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

{processbehavior-0.2.1 → 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.1 → 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.1 → processbehavior-0.3.0}/processbehavior/datasets/synthetic.py

@@ -416,13 +416,13 @@ def make_sds3(  # noqa: C901
     Characteristics:
     ---------------
     - Some cells have n=1, others have n≥2
-    - Requires hybrid R2 estimation
+    - Mixed cell sizes: R2 by MA2 across the full sequence
     - Reflects real-world data collection reality
     - Most challenging to analyze correctly
 
     Use Cases:
     ---------
-    - Testing hybrid variance estimation algorithms
+    - Testing R2 selection with mixed cell sizes
     - Demonstrating real-world data structures
     - Validating robustness to missing data
     - Development of SDS detection logic

{processbehavior-0.2.1 → processbehavior-0.3.0}/processbehavior/derivations.py

@@ -473,11 +473,23 @@ def _evaluate_bin(spec: Derivation, col: pd.Series) -> EvalResult:
 
     edges, fit_msg = _fit_edges(spec, x[present])
 
-    # Degenerate fit (no spread) — cannot bin.
-    if len(edges) < 2 or any(not math.isfinite(e) for e in edges[1:-1]):
+    # Degenerate fit (no spread) — cannot bin. A constant column produces three shapes,
+    # one per method: a single edge (equal_freq, after np.unique collapses the quantiles),
+    # identical finite edges (equal_width, linspace(lo, lo)), and a zero-sigma sd fit
+    # ([-inf, mu, mu, mu, mu, inf]). pd.cut raises "Bin edges must be unique" on the latter
+    # two, and evaluate() promises never to raise on a routine state, so all three return
+    # the same no-spread result. User-supplied breaks are validated ascending elsewhere and
+    # bin a constant column fine (everything lands in one interval), so they never trip this.
+    degenerate = (
+        len(edges) < 2
+        or any(not math.isfinite(e) for e in edges[1:-1])
+        or any(b <= a for a, b in zip(edges, edges[1:], strict=False))  # not strictly increasing
+    )
+    if degenerate:
         return EvalResult(
             values=pd.Series(pd.Categorical([np.nan] * len(x)), index=x.index),
-            n_invalid=0, invalid_index=empty_index, fitted={'method': params['method']},
+            n_invalid=0, invalid_index=empty_index,
+            fitted={'method': params['method'], 'n_bins': 0, 'edges': [], 'labels': []},
             message='column has no spread; cannot bin',
         )
 

{processbehavior-0.2.1 → processbehavior-0.3.0}/processbehavior/residual_calculator.py

@@ -338,14 +338,14 @@ def calculate_r2(df: pd.DataFrame, y: str, r2_method: R2Method, n_per_cell: pd.S
     R2 is the ONLY structure-dependent residual. The method is determined by
     observed cell sizes (via SDSRegistry.get_r2_method()):
 
-    - exact (state 1): R2 = Y - Ȳ_kt (Eq 59), all cells have n >= 2
-    - ma2 (states 2 & 3): R2 = (Y_j - Y_{j-1}) / 2 (Eq 13.8-13.9),
+    - exact (ADS 1): R2 = Y - Ȳ_kt (Eq 59), every cell has n >= 2
+    - ma2 (ADS 2 and 3): R2 = (Y_j - Y_{j-1}) / 2 (Eq 13.7-13.9),
       any cell has n = 1
 
     When any cell has n=1, MA2 is applied to ALL observations across the
-    entire canonical-sorted stream — no grouping by rsg_key, no hybrid
-    per-cell selection. Bishop Eq 13.7-13.9 specify j=2,...,J with no
-    grouping; only j=1 gets R2=0.
+    entire canonical-sorted stream — no grouping by rsg_key, no per-cell
+    selection between exact and MA2. Bishop Eq 13.7-13.9 specify j=2,...,J
+    with no grouping; only j=1 has no value.
 
     Parameters
     ----------
@@ -354,8 +354,9 @@ def calculate_r2(df: pd.DataFrame, y: str, r2_method: R2Method, n_per_cell: pd.S
     y : str
         Name of response variable
     r2_method : R2Method
-        'exact', 'ma2', or 'hybrid' — retained for API compatibility.
-        Branching is driven by n_per_cell.
+        'exact' or 'ma2', as chosen by SDSRegistry.get_r2_method(). Kept for
+        callers and logging; the branch below re-derives it from n_per_cell so
+        the two can never disagree.
     n_per_cell : pd.Series, optional
         Pre-computed observations per cell. Pass from ADS to avoid recomputation.
 
@@ -427,7 +428,7 @@ def calculate_vas_residuals(
     spec : FormulationSpec
         Analysis specification
     r2_method : R2Method
-        'exact', 'ma2', or 'hybrid' - determines R2 calculation
+        'exact' or 'ma2' - determines R2 calculation
     n_per_cell : pd.Series, optional
         Pre-computed observations per cell. Pass from ADS to avoid recomputation.
     ybar_kt : pd.Series, optional

{processbehavior-0.2.1 → processbehavior-0.3.0}/processbehavior/sds_detector.py

@@ -39,7 +39,7 @@ SDSReasonType = Literal[
 ]
 
 # R2 calculation method - structure-driven, not SDS-driven
-R2Method = Literal['exact', 'ma2', 'hybrid']
+R2Method = Literal['exact', 'ma2']
 
 
 @dataclass(frozen=True)
@@ -116,7 +116,7 @@ class SDSAnalysisPlan:
     residuals_available : list[str]
         Which residuals can be calculated
     residual_calculation_method : str
-        How R2 is calculated ('exact', 'moving_average', 'hybrid', or 'none')
+        How R2 is calculated ('exact', 'ma2', or 'none')
     main_effects_supported : bool
         Whether main effect calculations are supported
     interaction_effects_supported : bool
@@ -158,7 +158,7 @@ class SDSAnalysisPlan:
     # VAS residual capabilities
     vas_residuals_supported: bool
     residuals_available: list[str]
-    residual_calculation_method: str  # 'exact', 'moving_average', 'hybrid', 'none'
+    residual_calculation_method: str  # 'exact', 'ma2', 'none'
 
     # Effects and interactions
     main_effects_supported: bool
@@ -383,7 +383,7 @@ class SDSRegistry:
 
     **SDS 3**: Semi-Complete - Partial replication
         - Min N_kt = 1 and Max N_kt ≥ 2 (mixed)
-        - Hybrid variance estimation
+        - R2 by moving average across the full sequence (any singleton forces MA2)
 
     **Incomplete** (has empty cells, requires sampling plan to detect):
 
@@ -664,7 +664,7 @@ class SDSRegistry:
         >>> info['description']
         'Full replication (all cells n≥2)'
         >>> info['r2_method']
-        'within_cell'
+        'exact'
         >>> info['capabilities']
         ['full_vas', 'all_residuals', 'interactions', 'main_effects']
         """
@@ -680,7 +680,7 @@ class SDSRegistry:
             1: {
                 'description': 'Full replication (all cells n≥2)',
                 'replication_type': 'full',
-                'r2_method': 'within_cell',
+                'r2_method': 'exact',
                 'capabilities': ['full_vas', 'all_residuals', 'interactions', 'main_effects'],
                 'interaction_analysis': True,
                 'variance_decomposition': True,
@@ -688,7 +688,7 @@ class SDSRegistry:
             2: {
                 'description': 'No replication (all cells n=1)',
                 'replication_type': 'none',
-                'r2_method': 'moving_average',
+                'r2_method': 'ma2',
                 'capabilities': ['all_residuals', 'limited_interactions', 'main_effects'],
                 'interaction_analysis': 'limited',
                 'variance_decomposition': True,
@@ -696,7 +696,7 @@ class SDSRegistry:
             3: {
                 'description': 'Partial replication (mixed n=1 and n≥2)',
                 'replication_type': 'partial',
-                'r2_method': 'hybrid',
+                'r2_method': 'ma2',  # Any singleton: MA2 over the full sequence (Bishop Eq 13.7-13.9)
                 'capabilities': ['all_residuals', 'partial_interactions', 'main_effects'],
                 'interaction_analysis': 'partial',
                 'variance_decomposition': True,
@@ -720,7 +720,7 @@ class SDSRegistry:
             6: {
                 'description': 'Incomplete grid with singletons (has 0s, 1s, and ≥2s)',
                 'replication_type': 'partial',
-                'r2_method': 'hybrid',
+                'r2_method': 'ma2',
                 'capabilities': ['partial_vas', 'main_effects', 'stratification'],
                 'interaction_analysis': False,
                 'variance_decomposition': True,
@@ -751,23 +751,24 @@ class SDSRegistry:
         Returns
         -------
         R2Method
-            'exact' if all cells have replication (n_cell_min >= 2)
-            'ma2' if all cells are singletons (n_cell_max == 1)
-            'hybrid' for mixed replication (exact where n >= 2, MA2 where n = 1)
+            'exact' if every cell has replication (n_cell_min >= 2)
+            'ma2' if any cell is a singleton (n_cell_min == 1), whether all
+            cells are singletons (ADS 2) or only some (ADS 3)
 
         Notes
         -----
         Deterministic rule based on Bishop methodology:
-        - Eq 59 (exact): R2 = Y - Ȳ_kt, requires replication
-        - Eq 66 (MA2): R2 = (Y_j - Y_{j-1}) / 2, for singletons
-        - Hybrid: exact where replicated, MA2 where singleton
+        - Eq 59 (exact): R2 = Y - Ȳ_kt, requires replication in every cell
+        - Eq 13.7-13.9 (MA2): R2 = (Y_j - Y_{j-1}) / 2 over the whole ordered
+          sequence, j = 2..J, with no grouping by cell. Once any cell is a
+          singleton this applies to every observation; the replicated cells'
+          within-cell deviations are not used for R2. There is no per-cell
+          mixing of the two (the earlier "hybrid" was removed in cb037f8, and
+          the ADS 3 reference assertions validate the ungrouped MA2).
         """
         if stats.n_cell_min >= 2:
             return 'exact'
-        elif stats.n_cell_max == 1:
-            return 'ma2'
-        else:
-            return 'hybrid'
+        return 'ma2'
 
     def validate_sds_for_analysis(self, sds: int, analysis_type: str) -> bool:
         """
@@ -1296,7 +1297,7 @@ class SDSRegistry:
                 invalid_charts=[],
                 vas_residuals_supported=True,
                 residuals_available=['R1', 'R2', 'R3', 'R4', 'R5', 'R6'],
-                residual_calculation_method='moving_average',
+                residual_calculation_method='ma2',
                 main_effects_supported=True,
                 interaction_effects_supported=True,
                 supports_stratification=True,
@@ -1324,7 +1325,7 @@ class SDSRegistry:
                 invalid_charts=[],
                 vas_residuals_supported=True,
                 residuals_available=['R1', 'R2', 'R3', 'R4', 'R5', 'R6'],
-                residual_calculation_method='hybrid',
+                residual_calculation_method='ma2',
                 main_effects_supported=True,
                 interaction_effects_supported=True,
                 supports_stratification=True,
@@ -1335,7 +1336,8 @@ class SDSRegistry:
                     'Pilot studies with targeted replication',
                 ],
                 limitations=[
-                    'R2 uses hybrid calculation (exact where possible, approximate elsewhere)',
+                    'R2 uses the 2-point moving average over the full sequence (Bishop Eq 13.7-13.9); '
+                    'the replicated cells contribute no separate within-cell estimate',
                     'Variance estimates less precise than SDS 1',
                     'May have unequal subgroup sizes',
                 ],

processbehavior-0.3.0/processbehavior/series_length.py

@@ -0,0 +1,105 @@
+"""
+Series-length precision of the sigma estimate.
+
+One fact for the design report: where the sigma behind the natural process
+limits comes from at the observed structure and series length. No threshold,
+label, or warning is attached; the analyst weighs it (Bishop: judgment belongs
+to the analyst, not to a rule).
+
+Two sources of sigma:
+
+- Every cell replicated (ADS 1): within-cell deviation. The number of time
+  periods does not enter; T = 1 is a complete study.
+- Any singleton cell (ADS 2, ADS 3): the 2-point moving range over the ordered
+  sequence, T - 1 ranges for T time points.
+
+The sentence names the source and the count. The within-cell degrees of freedom
+and the 80% interval of the moving-range estimate at this T
+(``MR_SIGMA_INTERVAL_80``, from #114) ride on the result for callers who want
+them; the report does not print them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .spc_constants import MR_SIGMA_INTERVAL_80
+
+_TABLE_MAX = max(MR_SIGMA_INTERVAL_80)
+
+
+@dataclass(frozen=True)
+class SeriesLengthPrecision:
+    """
+    Where sigma comes from, and how precise it is, at the observed series length.
+
+    Attributes
+    ----------
+    T : int or None
+        Distinct time points on the analysis dataset; None when no time variable.
+    n_moving_ranges : int or None
+        T - 1 when the moving range carries sigma and T >= 2; else None.
+    within_cell_df : int
+        Sum over cells of (N_kt - 1); 0 when no cell is replicated.
+    sigma_from_time : bool
+        True when sigma rests on moving ranges (any singleton cell); False when
+        it rests on within-cell replication.
+    mr_interval_80 : tuple of (float, float) or None
+        (p10, p90) of the moving-range sigma estimate relative to the truth on a
+        stable process, from ``MR_SIGMA_INTERVAL_80``; only when
+        ``sigma_from_time`` and 3 <= T <= 30.
+    description : str
+        The sentence printed in the design report, e.g.
+        ``T=4. Sigma for X/mR rests on 3 moving ranges.`` Empty when there is
+        nothing to say (no time variable and no replication).
+    """
+
+    T: int | None
+    n_moving_ranges: int | None
+    within_cell_df: int
+    sigma_from_time: bool
+    mr_interval_80: tuple[float, float] | None
+    description: str
+
+
+def assess_series_length(T: int | None, within_cell_df: int, sigma_from_time: bool) -> SeriesLengthPrecision:
+    """
+    Build the precision statement for a study.
+
+    The sentence names only the source of sigma at this structure and T. The
+    numbers behind it (``within_cell_df``, ``mr_interval_80``) ride on the
+    result for callers who want them; the report does not print them.
+
+    Parameters
+    ----------
+    T : int or None
+        Distinct time points on the analysis dataset (None if no time variable).
+    within_cell_df : int
+        Sum over cells of (N_kt - 1) on the analysis dataset.
+    sigma_from_time : bool
+        True when the limits rest on the moving range (any singleton cell).
+
+    Returns
+    -------
+    SeriesLengthPrecision
+    """
+    if not sigma_from_time:
+        if T is None:
+            description = 'Sigma rests on within-cell replication.'
+        else:
+            description = f'T={T}. Sigma rests on within-cell replication.'
+        return SeriesLengthPrecision(T, None, within_cell_df, False, None, description)
+
+    if T is None:
+        return SeriesLengthPrecision(None, None, within_cell_df, True, None, '')
+
+    n_mr = T - 1 if T >= 2 else 0
+    interval = MR_SIGMA_INTERVAL_80.get(T) if T <= _TABLE_MAX else None
+
+    if T < 2:
+        description = f'T={T}. Sigma for X/mR rests on the moving range, which needs at least 2 time points.'
+    elif T == 2:
+        description = 'T=2. Sigma for X/mR rests on a single moving range.'
+    else:
+        description = f'T={T}. Sigma for X/mR rests on {n_mr} moving ranges.'
+    return SeriesLengthPrecision(T, n_mr, within_cell_df, True, interval, description)

{processbehavior-0.2.1 → processbehavior-0.3.0}/processbehavior/spc_constants.py

@@ -690,3 +690,47 @@ RESIDUAL_ALIASES: dict[str, str] = {
     'design_condition_main_effects': 'R5',
     'design_factor_main_effects': 'R6',
 }
+
+
+# ============================================================================
+# Series-length precision of the moving-range sigma estimate
+# ============================================================================
+
+# 80% interval (p10, p90) of MRbar/d2 relative to the true sigma, for a stable
+# normal process observed at n points, n = 3..30. Generated by
+# validation/short_series_bands.py (seed 20260903, 100,000 replicates, an
+# independent stream per n), contributed by @rabujamra in #114 / PR #119. Read
+# as: at n=4, 80% of moving-range sigma estimates fall between 0.43x and 1.68x
+# the truth. The spread narrows monotonically with n, so the n=30 row bounds
+# every longer series. Stated as a fact in the design report; the library
+# attaches no threshold, label, or warning to it.
+MR_SIGMA_INTERVAL_80: dict[int, tuple[float, float]] = {
+    3: (0.337, 1.810),
+    4: (0.430, 1.676),
+    5: (0.488, 1.593),
+    6: (0.528, 1.526),
+    7: (0.565, 1.484),
+    8: (0.595, 1.453),
+    9: (0.618, 1.418),
+    10: (0.637, 1.396),
+    11: (0.656, 1.375),
+    12: (0.670, 1.360),
+    13: (0.680, 1.344),
+    14: (0.694, 1.330),
+    15: (0.703, 1.315),
+    16: (0.714, 1.310),
+    17: (0.722, 1.300),
+    18: (0.730, 1.288),
+    19: (0.739, 1.280),
+    20: (0.745, 1.274),
+    21: (0.749, 1.266),
+    22: (0.756, 1.258),
+    23: (0.761, 1.253),
+    24: (0.766, 1.249),
+    25: (0.771, 1.243),
+    26: (0.775, 1.238),
+    27: (0.780, 1.234),
+    28: (0.784, 1.229),
+    29: (0.787, 1.224),
+    30: (0.790, 1.220),
+}

{processbehavior-0.2.1 → processbehavior-0.3.0}/processbehavior/study.py

@@ -29,6 +29,7 @@ from typing import TYPE_CHECKING, Literal
 from .exceptions import ChartNotAvailableError, FactorNotFoundError, ValidationError
 from .residual_calculator import resolve_r6_groupby
 from .sds_detector import SDSRegistry
+from .series_length import SeriesLengthPrecision, assess_series_length
 from .spc_constants import (
     ALL_RESIDUALS,
     RESIDUAL_ALIASES,
@@ -173,6 +174,7 @@ class DesignReport:
     _pds_result: SDSResult | None = None  # Plan Design State
     _ods_result: SDSResult | None = None  # Observed Design State
     _ads_result: SDSResult | None = None  # Analytical Design State
+    _series_length: SeriesLengthPrecision | None = None  # Where sigma comes from, and how precise
 
     @property
     def factors_table(self) -> pd.DataFrame:
@@ -765,6 +767,12 @@ class DesignReport:
         lines.append('')
         lines.append(f'  Structure: {self.structure_summary}')
 
+        # Series length: where sigma comes from at this structure and T. A fact beside the
+        # design state, not a verdict on it — ADS 2 is ADS 2 whether T is 4 or 400 (#114).
+        # No threshold, label, or warning is attached.
+        if self._series_length is not None and self._series_length.description:
+            lines.append(f'  Series length: {self._series_length.description}')
+
         # Available analyses (derived from ADS)
         if self._ads_result and self._ads_result.sds > 0:
             lines.extend(self._repr_available_analyses())
@@ -1111,6 +1119,39 @@ class Study:
         """
         return self.analytical_design_state.reason
 
+    @property
+    def series_length(self) -> SeriesLengthPrecision:
+        """
+        Where sigma comes from at this structure and series length.
+
+        A fact stated beside the design state, not a judgment on it: no
+        threshold, label, or warning. With any singleton cell the limits rest on
+        T - 1 moving ranges; with every cell replicated they rest on within-cell
+        replication and T does not enter. The result also carries
+        ``within_cell_df`` and, for the moving-range case, ``mr_interval_80``
+        (from ``MR_SIGMA_INTERVAL_80``) for callers who want the numbers; the
+        report prints only the sentence.
+
+        Returns
+        -------
+        SeriesLengthPrecision
+        """
+        ads_df = self._ads.analysis_dataset
+        T = None
+        if self._spec.time_var and self._spec.time_var in ads_df.columns:
+            T = int(ads_df[self._spec.time_var].nunique())
+        within_cell_df = 0
+        if 'cell_key' in ads_df.columns and len(ads_df):
+            sizes = ads_df.groupby('cell_key', observed=True).size()
+            within_cell_df = int((sizes - 1).sum())
+        sigma_from_time = self.analytical_design_state.sds != 1
+        return assess_series_length(T, within_cell_df, sigma_from_time)
+
+    @property
+    def series_length_description(self) -> str:
+        """The series-length sentence printed in the design report (may be empty)."""
+        return self.series_length.description
+
     @property
     def ads_description(self) -> str:
         """
@@ -1667,6 +1708,7 @@ class Study:
             _pds_result=self._pds_result,
             _ods_result=self._sds_result,
             _ads_result=self._ads.analytical_design_state,
+            _series_length=self.series_length,
         )
 
     def capability(

{processbehavior-0.2.1 → processbehavior-0.3.0}/pyproject.toml

@@ -44,7 +44,7 @@ dependencies = [
   "numpy>=1.23",
   "pandas>=2.0,<3",
   "natsort>=8.0.0",
-  "plotly>=5.18,<7",
+  "plotly>=5.18,<8",
   # NotRequired (used in processbehavior.types) is only in typing from 3.11;
   # on 3.10 it comes from typing_extensions.
   "typing_extensions>=4.0; python_version < '3.11'",