process-improve 2.1.0__tar.gz → 2.2.2__tar.gz

{process_improve-2.1.0 → process_improve-2.2.2}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: process-improve
-Version: 2.1.0
+Version: 2.2.2
 Summary: Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis.
 Keywords: Designed Experiments,Design of Experiments,DoE,Optimal Design,Response Surface,Latent Variables,PCA,PLS,Multivariate Data Analysis,Chemometrics,Process Monitoring,Batch data analysis
 Author: Kevin Dunn
 Author-email: Kevin Dunn <kgdunn@gmail.com>
 License-Expression: MIT
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -39,24 +39,6 @@ Requires-Dist: openpyxl>=3.1.5 ; extra == 'batch'
 Requires-Dist: ruptures>=1.1.9 ; extra == 'batch'
 Requires-Dist: scikit-image>=0.25.2 ; extra == 'batch'
 Requires-Dist: osqp>=1.0 ; extra == 'control'
-Requires-Dist: coverage>=7.13.1 ; extra == 'dev'
-Requires-Dist: hypothesis>=6.100 ; extra == 'dev'
-Requires-Dist: matplotlib-stubs>=0.3.11 ; extra == 'dev'
-Requires-Dist: mypy>=1.19.1,<2.5 ; extra == 'dev'
-Requires-Dist: pandas-stubs>=2.3.3.260113 ; extra == 'dev'
-Requires-Dist: plotly-stubs>=0.0.6 ; extra == 'dev'
-Requires-Dist: pre-commit>=4.5.1 ; extra == 'dev'
-Requires-Dist: pytest>=9.0.2 ; extra == 'dev'
-Requires-Dist: pytest-benchmark>=4.0.0 ; extra == 'dev'
-Requires-Dist: pytest-cov>=7.0.0 ; extra == 'dev'
-Requires-Dist: pytest-xdist>=3.8.0 ; extra == 'dev'
-Requires-Dist: pydata-sphinx-theme>=0.16.1 ; extra == 'dev'
-Requires-Dist: ruff>=0.11.0,<0.17 ; extra == 'dev'
-Requires-Dist: sphinx>=8.1.3 ; extra == 'dev'
-Requires-Dist: nbsphinx>=0.9.5 ; extra == 'dev'
-Requires-Dist: ipykernel>=6.29 ; extra == 'dev'
-Requires-Dist: tqdm-stubs>=0.2.1 ; extra == 'dev'
-Requires-Dist: watchdog>=6.0.0 ; extra == 'dev'
 Requires-Dist: numba>=0.63.1 ; extra == 'fast'
 Requires-Dist: mcp>=2.0 ; extra == 'mcp'
 Requires-Dist: matplotlib>=3.10.8 ; extra == 'plotting'
@@ -74,7 +56,6 @@ Project-URL: Changelog, https://github.com/kgdunn/process-improve/blob/main/CHAN
 Provides-Extra: all
 Provides-Extra: batch
 Provides-Extra: control
-Provides-Extra: dev
 Provides-Extra: fast
 Provides-Extra: mcp
 Provides-Extra: plotting

{process_improve-2.1.0 → process_improve-2.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "process-improve"
-version = "2.1.0"
+version = "2.2.2"
 description = "Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis."
 readme = "README.md"
 license = "MIT"
@@ -20,7 +20,7 @@ keywords = [
     "Batch data analysis",
 ]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
@@ -74,26 +74,6 @@ all = [
     "scikit-image>=0.25.2",
     "seaborn>=0.13.2",
 ]
-dev = [
-    "coverage>=7.13.1",
-    "hypothesis>=6.100",
-    "matplotlib-stubs>=0.3.11",
-    "mypy>=1.19.1,<2.5",
-    "pandas-stubs>=2.3.3.260113",
-    "plotly-stubs>=0.0.6",
-    "pre-commit>=4.5.1",
-    "pytest>=9.0.2",
-    "pytest-benchmark>=4.0.0",
-    "pytest-cov>=7.0.0",
-    "pytest-xdist>=3.8.0",
-    "pydata-sphinx-theme>=0.16.1",
-    "ruff>=0.11.0,<0.17",
-    "sphinx>=8.1.3",
-    "nbsphinx>=0.9.5",
-    "ipykernel>=6.29",
-    "tqdm-stubs>=0.2.1",
-    "watchdog>=6.0.0",
-]
 
 [project.scripts]
 process-improve-mcp = "process_improve.mcp_server:main"
@@ -321,3 +301,32 @@ known-third-party = [
     "pytest",
     "pandas",
 ]
+
+[tool.mutmut]
+source_paths = ["src"]
+only_mutate = [
+    "src/process_improve/multivariate/_limits.py",
+    "src/process_improve/monitoring/metrics.py",
+    "src/process_improve/monitoring/evop.py",
+    "src/process_improve/monitoring/control_charts.py",
+]
+pytest_add_cli_args = [
+    "-o",
+    "addopts=",
+    "-p",
+    "no:cacheprovider",
+]
+pytest_add_cli_args_test_selection = [
+    "tests/test_multivariate_limits.py",
+    "tests/test_multivariate.py",
+    "tests/test_audit_regressions_multivariate.py",
+    "tests/test_multiblock_validation.py",
+    "tests/test_multivariate_introspection.py",
+    "tests/test_monitoring.py",
+    "tests/test_monitoring_helpers.py",
+    "tests/test_audit_regressions_univariate_monitoring.py",
+    "tests/test_evop.py",
+    "tests/test_control_chart_cusum.py",
+    "tests/test_control_chart_ewma.py",
+    "tests/test_control_chart_hw_golden.py",
+]

{process_improve-2.1.0 → process_improve-2.2.2}/pyproject.toml.orig

@@ -1,13 +1,13 @@
 [project]
 name = "process-improve"
-version = "2.1.0"
+version = "2.2.2"
 description = 'Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis.'
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.11"
 keywords = ["Designed Experiments", "Design of Experiments", "DoE", "Optimal Design", "Response Surface", "Latent Variables", "PCA", "PLS", "Multivariate Data Analysis", "Chemometrics", "Process Monitoring", "Batch data analysis"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Science/Research",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
@@ -108,27 +108,6 @@ all = [
     "seaborn>=0.13.2",
 ]
 
-dev = [
-    "coverage>=7.13.1",
-    "hypothesis>=6.100",
-    "matplotlib-stubs>=0.3.11",
-    "mypy>=1.19.1,<2.5",
-    "pandas-stubs>=2.3.3.260113",
-    "plotly-stubs>=0.0.6",
-    "pre-commit>=4.5.1",
-    "pytest>=9.0.2",
-    "pytest-benchmark>=4.0.0",
-    "pytest-cov>=7.0.0",
-    "pytest-xdist>=3.8.0",
-    "pydata-sphinx-theme>=0.16.1",
-    "ruff>=0.11.0,<0.17", # upper-bound so a future ruff release cannot silently break the lint gate (see mypy)
-    "sphinx>=8.1.3",
-    "nbsphinx>=0.9.5",
-    "ipykernel>=6.29",
-    "tqdm-stubs>=0.2.1",
-    "watchdog>=6.0.0",
-]
-
 [project.scripts]
 process-improve-mcp = "process_improve.mcp_server:main"
 
@@ -147,6 +126,8 @@ requires = ["uv_build>=0.7.2,<0.14"]
 build-backend = "uv_build"
 
 [dependency-groups]
+# The contributors' tools. A dependency group rather than an extra, so the
+# published wheel does not offer them to users (#513).
 dev = [
     "coverage>=7.13.1",
     "hypothesis>=6.100",
@@ -468,3 +449,31 @@ docstring-quotes = "double"
 
 [tool.ruff.lint.isort]
 known-third-party=["pytest", "pandas"]
+
+# Mutation testing: see "Mutation testing" in CONTRIBUTING.md. Modules join `only_mutate` one at a
+# time, each with no survivor, starting with those whose numbers users act on; the tests listed
+# are those that reach them.
+[tool.mutmut]
+source_paths = ["src"]
+only_mutate = [
+    "src/process_improve/multivariate/_limits.py",
+    "src/process_improve/monitoring/metrics.py",
+    "src/process_improve/monitoring/evop.py",
+    "src/process_improve/monitoring/control_charts.py",
+]
+# The runner drops pytest.ini's addopts: no xdist workers and no coverage inside each mutant run.
+pytest_add_cli_args = ["-o", "addopts=", "-p", "no:cacheprovider"]
+pytest_add_cli_args_test_selection = [
+    "tests/test_multivariate_limits.py",
+    "tests/test_multivariate.py",
+    "tests/test_audit_regressions_multivariate.py",
+    "tests/test_multiblock_validation.py",
+    "tests/test_multivariate_introspection.py",
+    "tests/test_monitoring.py",
+    "tests/test_monitoring_helpers.py",
+    "tests/test_audit_regressions_univariate_monitoring.py",
+    "tests/test_evop.py",
+    "tests/test_control_chart_cusum.py",
+    "tests/test_control_chart_ewma.py",
+    "tests/test_control_chart_hw_golden.py",
+]

process_improve-2.2.2/src/process_improve/_tool_registry.py

@@ -0,0 +1,205 @@
+"""(c) Kevin Dunn, 2010-2026. MIT License.
+
+The ``@tool_spec`` decorator, the registry it fills, and ``clean``.
+
+These are the parts of :mod:`process_improve.tool_spec` that every ``tools.py``
+module imports. They live apart from tool discovery, which names every
+``tools.py`` module, so that a tool module depends on this file alone and not,
+through discovery, on every other tool module. ``tool_spec.py`` re-exports all
+of it, and callers import it from there.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from pydantic import BaseModel
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+#: Maps tool name -> decorated callable.  Populated by ``@tool_spec``.
+_TOOL_REGISTRY: dict[str, Callable[..., Any]] = {}
+
+
+# ---------------------------------------------------------------------------
+# RNG metadata validation
+# ---------------------------------------------------------------------------
+
+
+def _validate_rng_metadata(name: str, rng: dict[str, Any]) -> None:
+    """Reject ``rng`` payloads that don't match the published contract.
+
+    The contract is intentionally narrow so downstream consumers (the
+    factorial reproducible-export service) can introspect specs without
+    defensive type-checking. See ``CLAUDE.md`` for the full schema.
+    """
+    if not isinstance(rng, dict):
+        raise TypeError(f"@tool_spec(name={name!r}): 'rng' must be a dict, got {type(rng).__name__}.")
+    if "uses_rng" not in rng or not isinstance(rng["uses_rng"], bool):
+        raise ValueError(f"@tool_spec(name={name!r}): 'rng' must have a boolean 'uses_rng' key.")
+    allowed_keys = {"uses_rng", "seed_param", "default_seed", "note"}
+    extra = set(rng) - allowed_keys
+    if extra:
+        raise ValueError(
+            f"@tool_spec(name={name!r}): unknown keys in 'rng': {sorted(extra)}. Allowed: {sorted(allowed_keys)}."
+        )
+    if not rng["uses_rng"]:
+        # Deterministic tools shouldn't carry a seed_param / default_seed.
+        if rng.get("seed_param") is not None or rng.get("default_seed") is not None:
+            raise ValueError(
+                f"@tool_spec(name={name!r}): 'seed_param' / 'default_seed' must be omitted when uses_rng is False."
+            )
+        return
+    seed_param = rng.get("seed_param")
+    if seed_param is not None and not isinstance(seed_param, str):
+        raise TypeError(
+            f"@tool_spec(name={name!r}): 'seed_param' must be a string or None, got {type(seed_param).__name__}."
+        )
+    default_seed = rng.get("default_seed")
+    if default_seed is not None and not isinstance(default_seed, int):
+        raise TypeError(
+            f"@tool_spec(name={name!r}): 'default_seed' must be an int or None, got {type(default_seed).__name__}."
+        )
+    if seed_param is None and default_seed is not None:
+        raise ValueError(f"@tool_spec(name={name!r}): 'default_seed' requires a 'seed_param' name.")
+
+
+# ---------------------------------------------------------------------------
+# Decorator
+# ---------------------------------------------------------------------------
+
+
+def tool_spec(  # noqa: PLR0913
+    name: str,
+    description: str,
+    *,
+    input_model: type[BaseModel],
+    examples: str = "",
+    category: str = "",
+    rng: dict[str, Any] | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Mark a function as an agent-callable tool.
+
+    Parameters
+    ----------
+    name:
+        Unique tool name exposed to the LLM (snake_case).
+    description:
+        Natural-language description of what the tool does and when to use it.
+    input_model:
+        A :class:`pydantic.BaseModel` subclass describing the tool's
+        input. The model is the single source of truth for both the
+        function's Python signature and the MCP JSON Schema (derived
+        via :meth:`BaseModel.model_json_schema`). Every input model
+        **must** set ``model_config = ConfigDict(extra="forbid")`` so
+        unknown keys are rejected (closes the SEC-15
+        kwarg-injection vector at the schema layer).
+
+        The decorated function then receives the parsed model as its
+        single positional argument::
+
+            class FooInput(BaseModel):
+                model_config = ConfigDict(extra="forbid")
+                values: list[float] = Field(..., min_length=2)
+
+            @tool_spec(name="foo", description="...", input_model=FooInput)
+            def foo(spec: FooInput) -> dict:
+                return {"n": len(spec.values)}
+    examples:
+        Optional natural-language -> tool-call mappings appended to
+        ``description`` so the LLM sees worked examples.
+    category:
+        Optional category string (e.g. ``"univariate"``). Used for
+        filtering with :func:`get_tool_specs`.
+    rng:
+        Optional reproducibility metadata; see :func:`_validate_rng_metadata`
+        for the contract.
+
+    Returns
+    -------
+    Callable
+        The original function, with an attached ``_tool_spec`` dict
+        and ``_input_model`` attribute.
+    """
+    if rng is not None:
+        _validate_rng_metadata(name, rng)
+
+    if not (isinstance(input_model, type) and issubclass(input_model, BaseModel)):
+        raise TypeError(
+            f"@tool_spec(name={name!r}): input_model must be a pydantic BaseModel subclass; got {input_model!r}."
+        )
+    extra_policy = input_model.model_config.get("extra")
+    if extra_policy != "forbid":
+        raise ValueError(
+            f"@tool_spec(name={name!r}): input_model {input_model.__name__} "
+            "must set model_config = ConfigDict(extra='forbid') so unknown "
+            "kwargs are rejected (ENG-04 / SEC-15 contract)."
+        )
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        """Attach the assembled tool spec to ``func`` and return it unchanged."""
+        full_description = description
+        if examples:
+            full_description = f"{description}\n\nExamples\n--------\n{examples}"
+
+        spec: dict[str, Any] = {
+            "name": name,
+            "description": full_description,
+            "input_schema": input_model.model_json_schema(),
+        }
+        if category:
+            spec["category"] = category
+        if rng is not None:
+            spec["rng"] = dict(rng)
+
+        func._tool_spec = spec  # type: ignore[attr-defined]
+        func._input_model = input_model  # type: ignore[attr-defined]
+        _TOOL_REGISTRY[name] = func
+        return func
+
+    return decorator
+
+
+# ---------------------------------------------------------------------------
+# Serialisation helper
+# ---------------------------------------------------------------------------
+
+
+def clean(value: Any) -> Any:  # noqa: PLR0911, ANN401
+    """Recursively convert numpy scalars / arrays to plain Python types.
+
+    All ``tools.py`` modules should call ``clean(result)`` before returning
+    so that every tool output is JSON-serialisable.
+    """
+    if isinstance(value, dict):
+        # Keys need unwrapping too: json.dumps rejects numpy scalar keys (a
+        # dict keyed by np.int64 group labels from a pandas groupby is the
+        # common case), and previously they leaked through untouched. Only
+        # numpy scalars are unwrapped - other key types pass through so
+        # hashability is never at risk.
+        return {(k.item() if isinstance(k, np.generic) else k): clean(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple, set, frozenset)):
+        return [clean(v) for v in value]
+    # np.bool_ subclasses neither np.integer nor Python bool, and json.dumps
+    # rejects it; it must be tested before the numeric branches.
+    if isinstance(value, np.bool_):
+        return bool(value)
+    if isinstance(value, np.integer):
+        return int(value)
+    if isinstance(value, np.floating):
+        v = float(value)
+        return None if math.isnan(v) or math.isinf(v) else v
+    if isinstance(value, float):
+        return None if math.isnan(value) or math.isinf(value) else value
+    if isinstance(value, np.ndarray):
+        return clean(value.tolist())
+    if isinstance(value, np.generic):
+        # Catch-all for the remaining numpy scalar types (datetime64,
+        # complex, str_, ...): unwrap to the closest Python equivalent.
+        return clean(value.item())
+    return value

{process_improve-2.1.0 → process_improve-2.2.2}/src/process_improve/batch/_batch_plots.py

@@ -42,8 +42,7 @@ if typing.TYPE_CHECKING:
 
 _UNFOLDED_INDEX_ERROR = (
     "needs the 2-level (tag, sequence) index that process_improve.batch.dict_to_wide produces. "
-    "When scaling the unfolded matrix yourself, re-attach ``wide.columns`` after MCUVScaler, "
-    "which drops the multi-level labels."
+    "Fit the model to that matrix, or to MCUVScaler's output of it, which keeps the index."
 )
 
 
@@ -203,8 +202,7 @@ def unfolded_contribution_plot(
         ``t2_contributions`` on :class:`process_improve.batch.BatchPCA` or
         :class:`process_improve.batch.BatchPLS`, or of the standalone
         :mod:`process_improve.multivariate` functions on a model fitted to a
-        :func:`process_improve.batch.dict_to_wide` matrix whose column index
-        was re-attached after scaling.
+        :func:`process_improve.batch.dict_to_wide` matrix, scaled or not.
     batch_id : Hashable, optional
         Which batch (row) to plot. Defaults to the first row.
     by_tag : bool, default=False

{process_improve-2.1.0 → process_improve-2.2.2}/src/process_improve/batch/features.py

@@ -50,10 +50,12 @@ def _prepare_data(  # noqa: C901, PLR0912
     if phase_col is None:
         phase_col = "__phase_grouper__"
 
+    # The fake grouping columns are added with `assign`, which returns a new frame: an
+    # in-place `insert` added them to the caller's DataFrame as well.
     if phase_col not in df:
         # Cannot use "None" or 'nan'; else it won't group in the
         # groupby([batch_col, phase_col]) statement below.
-        df.insert(0, phase_col, "NoPhases")
+        df = df.assign(**{phase_col: "NoPhases"})
 
     # If no batch_col: add a fake column with all the same values
     if batch_col not in df or batch_col is None:
@@ -61,7 +63,7 @@ def _prepare_data(  # noqa: C901, PLR0912
         if batch_col not in df:
             # Cannot use "None" or 'nan'; else it won't group in the
             # groupby([batch_col, phase_col]) statement below.
-            df.insert(0, batch_col, 1)
+            df = df.assign(**{batch_col: 1})
 
     if tags is None:
         tags = list(df.columns)
@@ -226,12 +228,18 @@ def f_iqr(
     The difference between the 75th percentile and the 25th percentile of a
     sample this is the 25 % trimmed range, an example of an L - estimator.
 
-    See also: f_std
+    Missing values are omitted, as ``f_std`` and ``f_robust_mad`` omit them.
+
+    See also: f_std, f_robust_mad
     """
     base_name = "iqr"
+
+    def _iqr(col: pd.Series) -> float:
+        return float(iqr(col, nan_policy="omit"))
+
     prepared, tags, output, _ = _prepare_data(data, tags, batch_col, phase_col)
     f_names = [(tag + "_" + base_name) for tag in tags]
-    output = prepared.agg(iqr)
+    output = prepared.agg(_iqr)
     return output.rename(columns=dict(zip(tags, f_names, strict=False)))
 
 
@@ -282,8 +290,6 @@ def f_sum(
 
     If the x-axis (time) data are evenly-spaced, then this is directly
     proportional to the area under the trace (curve/trajectory).
-
-    See also: f_cumsum
     """
     base_name = "sum"
     prepared, tags, output, _ = _prepare_data(data, tags, batch_col, phase_col)
@@ -310,6 +316,9 @@ def f_area(
     The spacing of the x-axis is taken into account, so, this will produce
     accurate areas if the data are not evenly-spaced in time along the x-axis.
 
+    A datetime or timedelta time axis is measured in seconds, so the area is in the tag's
+    units multiplied by seconds. A numeric time axis is used in its own units.
+
     The area is calculated using the trapezoidal rule.
 
     See also: f_sum, f_cumsum
@@ -323,7 +332,13 @@ def f_area(
     for batch_id, this_batch in prepared:
         # Average width of the base * height. For time series, the average width of the base is
         # the same as the sampling intervals. Therefore the diff of the index.
-        half_base_factor = np.diff(this_batch.index)
+        time_axis = this_batch.index
+        if isinstance(time_axis, pd.DatetimeIndex | pd.TimedeltaIndex):
+            # A plain diff gives timedelta64 widths, which made the area a timedelta that a
+            # float column cannot hold. Seconds keep it a number in a stated unit.
+            half_base_factor = np.asarray(pd.TimedeltaIndex(time_axis[1:] - time_axis[:-1]).total_seconds())
+        else:
+            half_base_factor = np.diff(time_axis)
         for tag in tags:
             # Now the sum makes sense: gets the area under the curve by adding
             # up the smaller trapezoids: consider the trapezoids as rotated by 90 degrees.
@@ -433,7 +448,7 @@ def f_rupture(
     ``display`` helper that uses matplotlib; plotting belongs to the caller, and the rest
     of this project plots with plotly.
 
-    See also: f_elbow, f_cross
+    See also: f_elbow, f_crossing
     """
     default_settings: dict = {"model": "rbf", "penalty": None, "min_size": 2, "jump": 5}
     if settings:
@@ -779,8 +794,10 @@ def f_crossing(  # noqa: PLR0913
 
     f_name = tag + "_" + base_name
 
-    def _cross_first(x: pd.DataFrame) -> np.ndarray | list:
-        return cross(x[tag], threshold, direction, only_index=only_index, first_point_only=True)
+    def _cross_first(x: pd.DataFrame) -> np.ndarray | list | float:
+        crossing = cross(x[tag], threshold, direction, only_index=only_index, first_point_only=True)
+        # `cross` returns an empty array when there is no crossing; the documented feature is NaN.
+        return np.nan if np.size(crossing) == 0 else crossing
 
     # pandas-stubs' DFCallable1 protocol does not include ``np.ndarray`` among the allowed
     # return types, although groupby.apply accepts array-returning callables at runtime.
@@ -806,7 +823,7 @@ def f_elbow(  # noqa: PLR0913
     The elbow is calculated against whichever variable is given by `x_axis_tag` (usually a time-
     based tag).
 
-    The function returns the *value* on the x-axis where the elbox occurs. Sometimes you might
+    The function returns the *value* on the x-axis where the elbow occurs. Sometimes you might
     want the *index* of the value, so you can also find the corresponding y-axis value. Use
     `only_index=True` for such cases.
     """

{process_improve-2.1.0 → process_improve-2.2.2}/src/process_improve/batch/preprocessing.py

@@ -582,6 +582,10 @@ _HUBER_CUTOFF = 1.345
 #: Smallest batch weight :func:`_batch_weights` will return, so no batch is ever silenced.
 _MIN_BATCH_WEIGHT = 1e-3
 
+#: Iterations of :func:`batch_dtw` that align every batch to the ``reference_batch``. Each later
+#: iteration aligns to the average trajectory of the iteration before it.
+_ITERATIONS_ON_THE_REFERENCE_BATCH = 3
+
 
 def _batch_weights(aligned_batches: dict, batch_weighting: str) -> np.ndarray:
     """
@@ -818,6 +822,11 @@ def batch_dtw(  # noqa: PLR0915
                 "interpolate_method": "cubic",         # any scipy.interpolate.interp1d method
             }
 
+        Every batch is aligned to ``reference_batch`` in the first three iterations. From
+        the fourth iteration on, the reference is the average trajectory of the iteration
+        before, so the result depends less on which batch was chosen as the reference. The
+        number three is fixed, not a setting.
+
         The default settings resample the time axis to 100 points, starting at 0 and ending
         at 99, so each point is one percent of the batch's duration however long the batch
         actually ran. Lower the delta for a finer axis (``0.5`` gives 200 points, ``0.25``
@@ -932,7 +941,12 @@ def batch_dtw(  # noqa: PLR0915
     average_batch = None
     delta_weight: np.floating | np.ndarray = np.linalg.norm(weight_vector)
     iter_step = 0
-    while (np.linalg.norm(delta_weight) > settings["tolerance"]) and (iter_step <= settings["maximum_iterations"]):
+    # The first iteration runs whatever the tolerance: it is the one that aligns the batches,
+    # and everything after the loop reads its results. A tolerance at or above the norm of
+    # the unit weights (the square root of the number of columns) used to skip it entirely.
+    while iter_step == 0 or (
+        (np.linalg.norm(delta_weight) > settings["tolerance"]) and (iter_step <= settings["maximum_iterations"])
+    ):
         if settings["show_progress"]:
             print(f"Iter = {iter_step} and norm = {np.linalg.norm(delta_weight)}")  # noqa: T201
 
@@ -946,7 +960,7 @@ def batch_dtw(  # noqa: PLR0915
         weight_matrix = np.diag(weight_vector)
         weight_history = np.vstack((weight_history, weight_vector.copy()))
 
-        if iter_step > 3:
+        if iter_step > _ITERATIONS_ON_THE_REFERENCE_BATCH:
             refbatch_sc = average_batch
 
         aligned_batches, average_batch = one_iteration_dtw(
@@ -1029,9 +1043,10 @@ def batch_dtw(  # noqa: PLR0915
         result.synced = synced_interpolated
         aligned_df_collection.append(synced_interpolated)
 
-    # Make the batch_id label consistent
+    # Each frame's batch_id column already holds its own dictionary key. Casting the whole
+    # column to the type of the last key turned an integer key into a string one whenever
+    # the keys were of mixed types, so the caller could no longer look its batch up.
     aligned_df = pd.concat(aligned_df_collection)
-    aligned_df["batch_id"] = aligned_df["batch_id"].astype(type(batch_id))
 
     last_average_batch = reverse_scaling(dict(avg=cast("pd.DataFrame", average_batch)), scale_df)["avg"]
     aligned_batch_dfdict = melted_to_dict(aligned_df, batch_id_col="batch_id")
@@ -1083,6 +1098,12 @@ def resample_to_reference(
     -------
     dict
         Batch data, in the standard format.
+
+    Raises
+    ------
+    ValueError
+        If a batch, the reference among them, has fewer than 2 rows: there is nothing to
+        interpolate between.
     """
     default_settings = {
         "interpolate_kind": "cubic",  # must be a valid "scipy.interpolate.interp1d" `kind`
@@ -1090,6 +1111,14 @@ def resample_to_reference(
     if settings:
         default_settings.update(settings)
     settings = default_settings
+    # Each batch's time axis is scaled to [0, 1] by dividing by its last row number, which is
+    # 0 for a single row: the division gave NaN and scipy then refused an "all-nan" axis.
+    too_short = {batch_id: batch.shape[0] for batch_id, batch in batches.items() if batch.shape[0] < 2}
+    if too_short:
+        raise ValueError(
+            f"resample_to_reference needs at least 2 rows in every batch, to interpolate between; "
+            f"these batches have fewer (batch: rows): {too_short}."
+        )
     out = {}
     target_time = np.arange(0, batches[reference_batch].shape[0])
     target_time = target_time / target_time[-1]