process-improve 1.97.0__tar.gz → 1.97.2__tar.gz

{process_improve-1.97.0 → process_improve-1.97.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: process-improve
-Version: 1.97.0
+Version: 1.97.2
 Summary: Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis.
 Keywords: Designed Experiments,Latent Variables,PCA,PLS,Multivariate Data Analysis,Batch data analysis
 Author: Kevin Dunn
@@ -42,7 +42,7 @@ 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.4 ; 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'

{process_improve-1.97.0 → process_improve-1.97.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "process-improve"
-version = "1.97.0"
+version = "1.97.2"
 description = "Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis."
 readme = "README.md"
 license = "MIT"
@@ -74,7 +74,7 @@ dev = [
     "coverage>=7.13.1",
     "hypothesis>=6.100",
     "matplotlib-stubs>=0.3.11",
-    "mypy>=1.19.1,<2.4",
+    "mypy>=1.19.1,<2.5",
     "pandas-stubs>=2.3.3.260113",
     "plotly-stubs>=0.0.6",
     "pre-commit>=4.5.1",
@@ -108,7 +108,7 @@ dev = [
     "coverage>=7.13.1",
     "hypothesis>=6.100",
     "matplotlib-stubs>=0.3.11",
-    "mypy>=1.19.1,<2.4",
+    "mypy>=1.19.1,<2.5",
     "pandas-stubs>=2.3.3.260113",
     "plotly-stubs>=0.0.6",
     "pre-commit>=4.5.1",

{process_improve-1.97.0 → process_improve-1.97.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "process-improve"
-version = "1.97.0"
+version = "1.97.2"
 description = 'Designed Experiments; Latent Variables (PCA, PLS, multivariate methods with missing data); Process Monitoring; Batch data analysis.'
 readme = "README.md"
 license = "MIT"
@@ -122,7 +122,7 @@ dev = [
     "coverage>=7.13.1",
     "hypothesis>=6.100",
     "matplotlib-stubs>=0.3.11",
-    "mypy>=1.19.1,<2.4",
+    "mypy>=1.19.1,<2.5",
     "pandas-stubs>=2.3.3.260113",
     "plotly-stubs>=0.0.6",
     "pre-commit>=4.5.1",
@@ -157,7 +157,7 @@ dev = [
     "coverage>=7.13.1",
     "hypothesis>=6.100",
     "matplotlib-stubs>=0.3.11",
-    "mypy>=1.19.1,<2.4",
+    "mypy>=1.19.1,<2.5",
     "pandas-stubs>=2.3.3.260113",
     "plotly-stubs>=0.0.6",
     "pre-commit>=4.5.1",

{process_improve-1.97.0 → process_improve-1.97.2}/src/process_improve/_extras.py

@@ -58,11 +58,16 @@ def require_extra(missing: str, extra: str) -> ImportError:
 class _MissingExtra:
     """Stand-in for an optional module that was not installed.
 
-    Attribute access raises :class:`AttributeError` (Python's special-method
-    convention -- ``hasattr(stub, 'Figure')`` returns ``False``) with the
-    canonical "install the extra" remediation message in the body. Direct
-    *calls* on the stub raise :class:`ImportError` because that is the
-    natural error class for "you need to install this dependency".
+    Using the stub in any way that needs the real package raises
+    :class:`ImportError` with the canonical "install the extra" message, so a
+    missing ``plotting`` extra fails the same way as a missing ``expt`` extra.
+    Attribute access returns a child stub that remembers the dotted path, so
+    ``go.Figure(...)`` and ``go.layout.Template(...)`` raise ``ImportError`` at
+    the call, and indexing (``pio.templates[name]``) raises it too.
+
+    Dunder lookups (``__array__``, ``__deepcopy__``, ...) raise
+    :class:`AttributeError` instead, so protocol probes such as ``copy``,
+    ``pickle`` and numpy see a missing attribute, per the Python data model.
 
     Lets a module top-level write::
 
@@ -75,21 +80,32 @@ class _MissingExtra:
     who never touch the optional surface.
     """
 
-    __slots__ = ("_extra", "_missing")
+    __slots__ = ("_extra", "_missing", "_path")
 
-    def __init__(self, missing: str, extra: str) -> None:
+    def __init__(self, missing: str, extra: str, path: str = "") -> None:
         self._missing = missing
         self._extra = extra
-
-    def __getattr__(self, name: str) -> object:
-        # __getattr__ must raise AttributeError so ``hasattr`` and friends
-        # behave per the Python data model (CodeQL py/non-standard-exception
-        # -raised-in-special-method). The install-hint message is preserved
-        # in the exception text.
-        raise AttributeError(f"{_extra_message(self._missing, self._extra)}\n(Attempted attribute access: {name!r}.)")
+        self._path = path
+
+    def _error(self) -> ImportError:
+        hint = f"\n(Attempted to use {self._path!r}.)" if self._path else ""
+        return ImportError(f"{_extra_message(self._missing, self._extra)}{hint}")
+
+    def __getattr__(self, name: str) -> _MissingExtra:
+        if name.startswith("__") and name.endswith("__"):
+            # __getattr__ must raise AttributeError for protocol lookups so
+            # ``hasattr`` and friends behave per the data model (CodeQL
+            # py/non-standard-exception-raised-in-special-method).
+            raise AttributeError(
+                f"{_extra_message(self._missing, self._extra)}\n(Attempted attribute access: {name!r}.)"
+            )
+        return _MissingExtra(self._missing, self._extra, f"{self._path}.{name}" if self._path else name)
 
     def __call__(self, *_args: object, **_kwargs: object) -> object:
-        # __call__ has no equivalent convention; raise ImportError here
-        # because callers that try to use the stub directly are asking
-        # for the missing package.
-        raise require_extra(self._missing, self._extra)
+        raise self._error()
+
+    def __getitem__(self, _key: object) -> object:
+        raise self._error()
+
+    def __setitem__(self, _key: object, _value: object) -> None:
+        raise self._error()

{process_improve-1.97.0 → process_improve-1.97.2}/src/process_improve/bivariate/_elbow_peak.py

@@ -15,9 +15,6 @@ def find_elbow_point(x: np.ndarray, y: np.ndarray, max_iter: int = 41) -> int |
     """
     Find the elbow point when plotting numeric entries in `x` vs numeric values in list `y`.
 
-    Return the index into the vectors `x` and `y` [the vectors must have the same length], where
-    the elbow point occurs.
-
     Using a robust linear fit, sorts the samples in X (independent variable)
     and takes the first 5 samples from the left, and the last 5 from the right,
     then fits two linear regressions and computes the intersection of the two
@@ -32,6 +29,18 @@ def find_elbow_point(x: np.ndarray, y: np.ndarray, max_iter: int = 41) -> int |
     Will probably not work well on few data points. If so, try fitting a spline
     to the raw data and then repeat with the interpolated data.
 
+    Parameters
+    ----------
+    x : np.ndarray
+        Independent-variable values. Must have the same length as `y`. NaN
+        entries are dropped pairwise with `y` before fitting; more than 10
+        finite pairs must remain.
+    y : np.ndarray
+        Dependent-variable values. Must have the same length as `x`.
+    max_iter : int, optional
+        Number of evenly spaced window sizes to sweep when accumulating
+        intersection points. Default is 41.
+
     Returns
     -------
     int or float
@@ -40,6 +49,12 @@ def find_elbow_point(x: np.ndarray, y: np.ndarray, max_iter: int = 41) -> int |
         Returns ``np.nan`` when the intersection sweep produced only
         NaNs (for example, when every candidate line pair was
         near-parallel), so no consensus intersection could be formed.
+
+    Raises
+    ------
+    ValueError
+        If `x` and `y` have different lengths, or if 10 or fewer finite
+        pairs remain after NaN entries are dropped.
     """
     start = 5
     # assert divmod(max_iter, 2)[1]  # must be odd number; to ensure we calculate the median later

{process_improve-1.97.0 → process_improve-1.97.2}/src/process_improve/config.py

@@ -167,8 +167,10 @@ class Settings:
     """Single-instance configuration store.
 
     Every attribute is a knob; reads are cached after the first access.
-    Call :meth:`reload` after mutating ``os.environ`` (typically inside a
-    test fixture); call :meth:`override` to set a single knob from code.
+    To set a single knob from code, assign to its property (each knob has a
+    setter, e.g. ``settings.tool_timeout = 30.0``). Call :meth:`reload` after
+    mutating ``os.environ`` (typically inside a test fixture); call
+    :meth:`as_dict` for a snapshot of every knob's current value.
     """
 
     __slots__ = ("_cache",)

{process_improve-1.97.0 → process_improve-1.97.2}/src/process_improve/experiments/_tools/evaluate_design.py

@@ -83,6 +83,15 @@ class EvaluateDesignInput(BaseModel):
         ge=0,
         description="Seed for the region sampler (default: 42).",
     )
+    categorical_coding: Literal["effect", "treatment"] = Field(
+        "effect",
+        description=(
+            "How a categorical (label) factor is coded. 'effect' (default): sum-to-zero effect coding, the "
+            "usual convention in DoE software and the coding generate_design's optimal designs use. "
+            "'treatment': 0/1 dummy coding against the first level. A-, E-optimality, VIF, condition number, "
+            "power and the alias matrix depend on the coding; prediction variance and D rankings do not."
+        ),
+    )
 
 
 @tool_spec(
@@ -139,6 +148,7 @@ def evaluate_design_tool(spec: EvaluateDesignInput) -> dict[str, Any]:
             sigma=spec.sigma,
             region=region,
             random_state=spec.random_state,
+            categorical_coding=spec.categorical_coding,
         )
         return clean(result)
     except _TOOL_EXPECTED_EXCEPTIONS as e:

{process_improve-1.97.0 → process_improve-1.97.2}/src/process_improve/experiments/augment.py

@@ -24,7 +24,7 @@ import logging
 import warnings
 from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 import pandas as pd
@@ -41,6 +41,9 @@ from process_improve.experiments.evaluate import (
 )
 from process_improve.experiments.models import validate_formula_is_safe, validate_identifier_is_safe
 
+if TYPE_CHECKING:
+    from process_improve.experiments.designs_constrained import _Region
+
 logger = logging.getLogger(__name__)
 
 # ---------------------------------------------------------------------------
@@ -557,23 +560,51 @@ def _model_rows(rhs: str, factor_names: list[str], existing: pd.DataFrame, candi
     return rows[: len(existing)], rows[len(existing) :]
 
 
+#: Target models whose columns ``designs_constrained.model_matrix`` builds directly, without patsy.
+_NAMED_MODELS = ("main_effects", "interactions", "quadratic")
+
+
+def _exchange_rows(
+    region: _Region, model: str, rhs: str, factor_names: list[str], existing: pd.DataFrame
+) -> tuple[np.ndarray, Callable[[np.ndarray, np.ndarray], np.ndarray]]:
+    """Return the existing runs' model rows, and a function giving the model rows of coded candidate points.
+
+    A named model is expanded with numpy (the same columns as its patsy formula, in
+    another order, which no criterion depends on), which keeps the exchange's polish
+    cheap; a custom formula goes through patsy, built together with the existing runs
+    so stateful transforms share their scale.
+    """
+    from process_improve.experiments.designs_constrained import model_matrix  # noqa: PLC0415
+
+    if model in _NAMED_MODELS:
+        coded = existing[factor_names].to_numpy(dtype=float)
+        fixed = model_matrix(region, coded, np.empty((len(coded), 0), dtype=int), model)
+        return fixed, lambda points, cats: model_matrix(region, points, cats, model)
+    fixed = _model_rows(rhs, factor_names, existing, np.empty((0, len(factor_names))))[0]
+    return fixed, lambda points, _cats: _model_rows(rhs, factor_names, existing, points)[1]
+
+
 def _augment_add_runs_optimal(ctx: _AugmentContext) -> dict[str, Any]:
     """Add D-optimal runs to the existing design, which stays fixed.
 
     The runs come from a Fedorov exchange over a candidate grid in coded units, with
-    the existing runs as fixed rows. Unlike a one-run-at-a-time greedy search, the
-    exchange can start from a design that cannot yet estimate the target model, as
-    every screening design aimed at a quadratic model is. When the requested runs
-    cannot supply the rank the existing runs lack, more are added, and the
-    explanation says so. Candidates may repeat, which replicates a run where the
-    criterion wants it.
+    the existing runs as fixed rows. For a quadratic model on a 3-level or sampled grid,
+    a coordinate exchange on a 5-level lattice then polishes the design from each start
+    (see ``select_runs``). Unlike a one-run-at-a-time greedy search, the exchange can
+    start from a design that cannot yet estimate the target model, as every screening
+    design aimed at a quadratic model is. When the requested runs cannot supply the
+    rank the existing runs lack, more are added, and the explanation says so.
+    Candidates may repeat, which replicates a run where the criterion wants it.
     """
     from process_improve.experiments.designs_constrained import (  # noqa: PLC0415
+        CandidatePool,
         Criterion,
+        PolishLattice,
         _budget_for_fixed_runs,
         _Region,
         build_candidates,
-        fedorov_exchange,
+        polish_levels,
+        select_runs,
     )
     from process_improve.experiments.factor import Factor  # noqa: PLC0415
 
@@ -586,16 +617,22 @@ def _augment_add_runs_optimal(ctx: _AugmentContext) -> dict[str, Any]:
 
     region = _Region([Factor(name=n, low=-1, high=1) for n in ctx.factor_names], [], [])
     grid_model = model if model in ("main_effects", "interactions") else "quadratic"
-    coded, _cats, _counts = build_candidates(region, None, grid_model)
-    f_fixed, f_cand = _model_rows(rhs, ctx.factor_names, df, coded)
+    coded, cats, counts = build_candidates(region, None, grid_model)
+    f_fixed, rows_of = _exchange_rows(region, model, rhs, ctx.factor_names, df)
+    f_cand = rows_of(coded, cats)
     n_parameters = f_cand.shape[1]
     if np.linalg.matrix_rank(np.vstack([f_fixed, f_cand])) < n_parameters:
         raise ValueError(f"The candidate grid cannot support the {model!r} model; use a simpler target_model.")
 
     total = _budget_for_fixed_runs(f_fixed, n_parameters, len(df) + ctx.n_additional_runs)
     n_new = total - len(df)
-    rows, _value = fedorov_exchange(f_cand, n_new, f_fixed, check_random_state(ctx.random_state), Criterion.d())
-    new_runs_df = pd.DataFrame(coded[rows], columns=ctx.factor_names)
+    levels = polish_levels(counts)
+    lattice = PolishLattice(levels, rows_of) if grid_model == "quadratic" and levels is not None else None
+    pool = CandidatePool(coded, cats, f_cand, lattice)
+    _rows, new_coded, _cats, _value = select_runs(
+        pool, n_new, f_fixed, check_random_state(ctx.random_state), Criterion.d()
+    )
+    new_runs_df = pd.DataFrame(new_coded, columns=ctx.factor_names)
     augmented = pd.concat([df, new_runs_df], ignore_index=True)
 
     notes = [

{process_improve-1.97.0 → process_improve-1.97.2}/src/process_improve/experiments/designs.py

@@ -678,7 +678,8 @@ def generate_design(  # noqa: PLR0913
         ``Constraint(expression="3*T + 5*D <= 600")``; a dict of ``Constraint`` fields or
         a bare expression string is accepted too. Honoured by the optimal
         families (``"d_optimal"``, chosen automatically when constraints are given,
-        ``"i_optimal"``, ``"a_optimal"`` and ``"e_optimal"``), whose runs are selected
+        ``"i_optimal"``, ``"a_optimal"``, ``"e_optimal"``, ``"g_optimal"`` and
+        ``"k_optimal"``), whose runs are selected
         from a candidate set of feasible points; by ``"mixture"`` (linear constraints
         in the proportions); and by the ``"sobol"``, ``"halton"``, ``"maximin"`` and
         ``"maxpro"`` space-filling designs. Other design types do not enforce them and set
@@ -695,7 +696,8 @@ def generate_design(  # noqa: PLR0913
         Ignored by the classical (non-optimal) design families.
     fixed_runs : pandas.DataFrame or None
         Runs to hold fixed while the optimizer fills the rest (design augmentation), for the
-        optimal families only (``"d_optimal"``, ``"i_optimal"``, ``"a_optimal"``, ``"e_optimal"``). One row per
+        optimal families only (``"d_optimal"``, ``"i_optimal"``, ``"a_optimal"``, ``"e_optimal"``,
+        ``"g_optimal"``, ``"k_optimal"``). One row per
         fixed run, one column per factor, in the same coding as the returned design: continuous
         factors in coded ``[-1, 1]`` units, categorical factors as level labels.
         The fixed runs occupy the first rows of the result and ``budget`` counts them, so