trade-study 0.1.0__py3-none-any.whl

trade_study/__init__.py

@@ -0,0 +1,54 @@
+"""Multi-objective trade-study orchestration.
+
+Scoring, Pareto optimization, and Bayesian stacking.
+"""
+
+from ._pareto import extract_front, hypervolume, igd_plus, pareto_rank
+from ._scoring import coverage_curve, score
+from ._version import __version__
+from .design import Factor, FactorType, build_grid, reduce_factors, screen
+from .io import load_results, save_results
+from .protocols import (
+    Annotation,
+    Direction,
+    Observable,
+    ResultsTable,
+    Scorer,
+    Simulator,
+    TrialResult,
+)
+from .runner import run_adaptive, run_grid
+from .stacking import ensemble_predict, stack_bayesian, stack_scores
+from .study import Phase, Study, top_k_pareto_filter
+
+__all__ = [
+    "Annotation",
+    "Direction",
+    "Factor",
+    "FactorType",
+    "Observable",
+    "Phase",
+    "ResultsTable",
+    "Scorer",
+    "Simulator",
+    "Study",
+    "TrialResult",
+    "__version__",
+    "build_grid",
+    "coverage_curve",
+    "ensemble_predict",
+    "extract_front",
+    "hypervolume",
+    "igd_plus",
+    "load_results",
+    "pareto_rank",
+    "reduce_factors",
+    "run_adaptive",
+    "run_grid",
+    "save_results",
+    "score",
+    "screen",
+    "stack_bayesian",
+    "stack_scores",
+    "top_k_pareto_filter",
+]

trade_study/_pareto.py

@@ -0,0 +1,128 @@
+"""Pareto front extraction and performance indicators.
+
+Wraps pymoo for non-dominated sorting and hypervolume computation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from .protocols import Direction
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def extract_front(
+    scores: NDArray[np.floating[Any]],
+    directions: list[Direction],
+) -> NDArray[np.intp]:
+    """Extract Pareto-optimal indices from a score matrix.
+
+    Args:
+        scores: Array of shape (n_trials, n_objectives).
+        directions: Optimization direction for each objective.
+
+    Returns:
+        Integer array of row indices on the Pareto front.
+    """
+    from pymoo.util.nds.non_dominated_sorting import (  # type: ignore[import-untyped]
+        NonDominatedSorting,
+    )
+
+    # pymoo assumes minimization; flip maximize objectives
+    obj = scores.copy()
+    for j, d in enumerate(directions):
+        if d == Direction.MAXIMIZE:
+            obj[:, j] = -obj[:, j]
+
+    nds = NonDominatedSorting()
+    fronts = nds.do(obj)
+    return np.asarray(fronts[0], dtype=np.intp)
+
+
+def pareto_rank(
+    scores: NDArray[np.floating[Any]],
+    directions: list[Direction],
+) -> NDArray[np.intp]:
+    """Assign Pareto rank to each trial (0 = front, 1 = next layer, ...).
+
+    Args:
+        scores: Array of shape (n_trials, n_objectives).
+        directions: Optimization direction for each objective.
+
+    Returns:
+        Integer array of ranks, shape (n_trials,).
+    """
+    from pymoo.util.nds.non_dominated_sorting import (
+        NonDominatedSorting,
+    )
+
+    obj = scores.copy()
+    for j, d in enumerate(directions):
+        if d == Direction.MAXIMIZE:
+            obj[:, j] = -obj[:, j]
+
+    nds = NonDominatedSorting()
+    fronts = nds.do(obj)
+    ranks = np.empty(len(scores), dtype=np.intp)
+    for rank, front in enumerate(fronts):
+        ranks[front] = rank
+    return ranks
+
+
+def hypervolume(
+    front: NDArray[np.floating[Any]],
+    ref_point: NDArray[np.floating[Any]],
+    directions: list[Direction] | None = None,
+) -> float:
+    """Compute hypervolume indicator for a Pareto front.
+
+    Args:
+        front: Array of shape (n_points, n_objectives) on the front.
+        ref_point: Reference point (should dominate all front points after
+            direction normalization).
+        directions: If provided, flips maximize objectives before computing.
+
+    Returns:
+        Hypervolume value.
+    """
+    from pymoo.indicators.hv import HV  # type: ignore[import-untyped]
+
+    obj = front.copy()
+    rp = ref_point.copy()
+    if directions is not None:
+        for j, d in enumerate(directions):
+            if d == Direction.MAXIMIZE:
+                obj[:, j] = -obj[:, j]
+                rp[j] = -rp[j]
+    return float(HV(ref_point=rp)(obj))
+
+
+def igd_plus(
+    front: NDArray[np.floating[Any]],
+    reference: NDArray[np.floating[Any]],
+    directions: list[Direction] | None = None,
+) -> float:
+    """Compute IGD+ indicator.
+
+    Args:
+        front: Obtained Pareto front.
+        reference: Reference Pareto front.
+        directions: Optimization directions.
+
+    Returns:
+        IGD+ value (lower is better).
+    """
+    from pymoo.indicators.igd_plus import IGDPlus  # type: ignore[import-untyped]
+
+    obj = front.copy()
+    ref = reference.copy()
+    if directions is not None:
+        for j, d in enumerate(directions):
+            if d == Direction.MAXIMIZE:
+                obj[:, j] = -obj[:, j]
+                ref[:, j] = -ref[:, j]
+    return float(IGDPlus(ref)(obj))

trade_study/_scoring.py

@@ -0,0 +1,213 @@
+"""Scoring functions wrapping scoringrules and scipy.
+
+Provides a uniform ``score(metric, predictions, truth)`` interface
+for all proper scoring rules and calibration diagnostics.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+
+def score(
+    metric: str,
+    predictions: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+    *,
+    alpha: float | NDArray[np.floating[Any]] | None = None,
+    level: float = 0.95,
+) -> float:
+    """Compute a scalar scoring rule.
+
+    Args:
+        metric: One of "crps", "wis", "interval", "energy",
+            "rmse", "mae", "coverage", "brier".
+        predictions: Model predictions (ensemble members, quantiles, etc.).
+        truth: Known ground truth values.
+        alpha: Significance level for interval-based scores.
+        level: Nominal coverage level for coverage metric.
+
+    Returns:
+        Scalar score value.
+
+    Raises:
+        ValueError: If the metric name is not recognized.
+    """
+    simple = {
+        "crps": _crps,
+        "energy": _energy,
+        "brier": _brier,
+        "rmse": _rmse,
+        "mae": _mae,
+    }
+    if metric in simple:
+        return simple[metric](predictions, truth)
+    if metric == "wis":
+        return _wis(predictions, truth, alpha=alpha)
+    if metric == "interval":
+        return _interval(predictions, truth, alpha=alpha)
+    if metric == "coverage":
+        return _coverage(predictions, truth, level=level)
+    msg = f"Unknown metric: {metric!r}"
+    raise ValueError(msg)
+
+
+def _crps(
+    ensemble: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+) -> float:
+    """CRPS via scoringrules.
+
+    Returns:
+        Mean CRPS across observations.
+    """
+    import scoringrules as sr  # type: ignore[import-untyped]
+
+    return float(np.mean(sr.crps_ensemble(truth, ensemble)))
+
+
+def _wis(
+    predictions: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+    *,
+    alpha: float | NDArray[np.floating[Any]] | None = None,
+) -> float:
+    """Weighted interval score via scoringrules.
+
+    Returns:
+        Mean WIS across observations.
+    """
+    import scoringrules as sr
+
+    if alpha is None:
+        alpha = np.array([0.02, 0.05, 0.1, 0.2, 0.5])
+    return float(
+        np.mean(
+            sr.weighted_interval_score(
+                truth,
+                predictions[..., 0],
+                predictions[..., 1],
+                predictions[..., 2],
+                alpha,
+            ),
+        ),
+    )
+
+
+def _interval(
+    predictions: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+    *,
+    alpha: float | NDArray[np.floating[Any]] | None = None,
+) -> float:
+    """Interval score via scoringrules.
+
+    Returns:
+        Mean interval score across observations.
+    """
+    import scoringrules as sr
+
+    if alpha is None:
+        alpha = 0.05
+    return float(
+        np.mean(
+            sr.interval_score(truth, predictions[..., 0], predictions[..., 1], alpha),
+        ),
+    )
+
+
+def _coverage(
+    predictions: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+    *,
+    level: float = 0.95,
+) -> float:
+    """Empirical coverage rate at a given nominal level.
+
+    Returns:
+        Fraction of truth values within the predicted interval.
+    """
+    cov_alpha = 1.0 - level
+    lower = np.quantile(predictions, cov_alpha / 2, axis=-1)
+    upper = np.quantile(predictions, 1 - cov_alpha / 2, axis=-1)
+    return float(np.mean((truth >= lower) & (truth <= upper)))
+
+
+def _energy(
+    ensemble: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+) -> float:
+    """Energy score via scoringrules.
+
+    Returns:
+        Mean energy score across observations.
+    """
+    import scoringrules as sr
+
+    return float(np.mean(sr.es_ensemble(truth, ensemble)))
+
+
+def _brier(
+    predictions: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+) -> float:
+    """Brier score via scoringrules.
+
+    Returns:
+        Mean Brier score across observations.
+    """
+    import scoringrules as sr
+
+    return float(np.mean(sr.brier_score(truth, predictions)))
+
+
+def _rmse(
+    predictions: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+) -> float:
+    """Root mean squared error.
+
+    Returns:
+        RMSE value.
+    """
+    return float(np.sqrt(np.mean((predictions - truth) ** 2)))
+
+
+def _mae(
+    predictions: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+) -> float:
+    """Mean absolute error.
+
+    Returns:
+        MAE value.
+    """
+    return float(np.mean(np.abs(predictions - truth)))
+
+
+def coverage_curve(
+    posteriors: NDArray[np.floating[Any]],
+    truth: NDArray[np.floating[Any]],
+    levels: NDArray[np.floating[Any]] | None = None,
+) -> tuple[NDArray[np.floating[Any]], NDArray[np.floating[Any]]]:
+    """Compute empirical coverage across nominal levels.
+
+    Args:
+        posteriors: Posterior samples, shape (n_obs, n_samples).
+        truth: True values, shape (n_obs,).
+        levels: Nominal coverage levels (default: 0.05 to 0.99).
+
+    Returns:
+        Tuple of (nominal_levels, empirical_coverage).
+    """
+    if levels is None:
+        levels = np.linspace(0.05, 0.99, 50)
+    empirical = np.array([
+        _coverage(posteriors, truth, level=float(lv)) for lv in levels
+    ])
+    return levels, empirical

trade_study/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

trade_study/design.py

@@ -0,0 +1,309 @@
+"""Experimental design and factor screening.
+
+Wraps pyDOE3 for grid construction and SALib for sensitivity screening.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from itertools import product
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from numpy.typing import NDArray
+
+
+class FactorType(Enum):
+    """Type of design factor."""
+
+    CONTINUOUS = "continuous"
+    DISCRETE = "discrete"
+    CATEGORICAL = "categorical"
+
+
+@dataclass(frozen=True)
+class Factor:
+    """A single design factor.
+
+    Attributes:
+        name: Factor identifier (e.g. "alpha", "layer1_method").
+        factor_type: Continuous, discrete, or categorical.
+        levels: For categorical/discrete: list of allowed values.
+        bounds: For continuous: (low, high) tuple.
+    """
+
+    name: str
+    factor_type: FactorType
+    levels: list[Any] | None = None
+    bounds: tuple[float, float] | None = None
+
+    def __post_init__(self) -> None:
+        """Validate factor constraints.
+
+        Raises:
+            ValueError: If name is empty, continuous factor has missing or
+                invalid bounds, or discrete/categorical factor has empty
+                levels.
+        """
+        if not self.name:
+            msg = "Factor name must be a non-empty string"
+            raise ValueError(msg)
+        if self.factor_type == FactorType.CONTINUOUS:
+            if self.bounds is None:
+                msg = f"Continuous factor '{self.name}' requires bounds"
+                raise ValueError(msg)
+            lo, hi = self.bounds
+            if not (np.isfinite(lo) and np.isfinite(hi)):
+                msg = f"Continuous factor '{self.name}' bounds must be finite"
+                raise ValueError(msg)
+            if lo >= hi:
+                msg = f"Continuous factor '{self.name}' requires lo < hi"
+                raise ValueError(msg)
+        else:
+            if self.levels is None:
+                msg = f"Factor '{self.name}' of type {self.factor_type} requires levels"
+                raise ValueError(msg)
+            if len(self.levels) == 0:
+                msg = f"Factor '{self.name}' levels must be non-empty"
+                raise ValueError(msg)
+
+
+def build_grid(
+    factors: list[Factor],
+    *,
+    method: str = "full",
+    n_samples: int = 100,
+    seed: int = 42,
+    scramble: bool = True,
+) -> list[dict[str, Any]]:
+    """Build an experimental design grid.
+
+    Args:
+        factors: List of design factors.
+        method: Design method. One of:
+            - "full": Full factorial (categorical/discrete only).
+            - "lhs": Latin hypercube sampling (continuous factors, maps
+              categorical factors to uniform random selection).
+            - "sobol": Scrambled Sobol' sequence via ``scipy.stats.qmc``.
+            - "halton": Scrambled Halton sequence via ``scipy.stats.qmc``.
+        n_samples: Number of samples for LHS / QMC methods.
+        seed: Random seed.
+        scramble: Whether to apply scrambling to QMC sequences (Sobol /
+            Halton). Ignored for other methods.
+
+    Returns:
+        List of config dictionaries, one per design point.
+
+    Raises:
+        ValueError: If an unknown design method is specified.
+    """
+    if method == "full":
+        return _full_factorial(factors)
+    if method == "lhs":
+        return _latin_hypercube(factors, n_samples=n_samples, seed=seed)
+    if method in {"sobol", "halton"}:
+        return _qmc_sample(
+            factors,
+            n_samples=n_samples,
+            seed=seed,
+            qmc_method=method,
+            scramble=scramble,
+        )
+    msg = f"Unknown design method: {method!r}"
+    raise ValueError(msg)
+
+
+def _full_factorial(factors: list[Factor]) -> list[dict[str, Any]]:
+    """Full factorial over all factor levels.
+
+    Returns:
+        List of config dictionaries, one per design point.
+
+    Raises:
+        ValueError: If a factor has bounds instead of levels.
+    """
+    level_lists = []
+    for f in factors:
+        if f.levels is not None:
+            level_lists.append(f.levels)
+        elif f.bounds is not None:
+            msg = f"Full factorial requires levels, not bounds, for factor '{f.name}'"
+            raise ValueError(msg)
+    names = [f.name for f in factors]
+    return [dict(zip(names, combo, strict=True)) for combo in product(*level_lists)]
+
+
+def _latin_hypercube(
+    factors: list[Factor],
+    *,
+    n_samples: int,
+    seed: int,
+) -> list[dict[str, Any]]:
+    """Latin hypercube design via pyDOE3.
+
+    Returns:
+        List of config dictionaries, one per design point.
+    """
+    from pyDOE3 import lhs  # type: ignore[import-untyped]
+
+    n_factors = len(factors)
+    raw = lhs(n_factors, samples=n_samples, criterion="maximin", seed=seed)
+
+    configs: list[dict[str, Any]] = []
+    for row in raw:
+        cfg: dict[str, Any] = {}
+        for j, f in enumerate(factors):
+            if f.factor_type == FactorType.CONTINUOUS and f.bounds is not None:
+                lo, hi = f.bounds
+                cfg[f.name] = lo + row[j] * (hi - lo)
+            elif f.levels is not None:
+                idx = int(row[j] * len(f.levels))
+                idx = min(idx, len(f.levels) - 1)
+                cfg[f.name] = f.levels[idx]
+        configs.append(cfg)
+    return configs
+
+
+def _qmc_sample(
+    factors: list[Factor],
+    *,
+    n_samples: int,
+    seed: int,
+    qmc_method: str,
+    scramble: bool,
+) -> list[dict[str, Any]]:
+    """Quasi-Monte Carlo design via ``scipy.stats.qmc``.
+
+    Args:
+        factors: List of design factors.
+        n_samples: Number of sample points.
+        seed: Random seed for scrambling.
+        qmc_method: ``"sobol"`` or ``"halton"``.
+        scramble: Whether to apply scrambling.
+
+    Returns:
+        List of config dictionaries, one per design point.
+    """
+    from scipy.stats import qmc  # type: ignore[import-untyped]
+
+    n_factors = len(factors)
+    sampler: qmc.QMCEngine
+    if qmc_method == "sobol":
+        sampler = qmc.Sobol(d=n_factors, scramble=scramble, seed=seed)
+    else:
+        sampler = qmc.Halton(d=n_factors, scramble=scramble, seed=seed)
+    raw = sampler.random(n_samples)
+
+    configs: list[dict[str, Any]] = []
+    for row in raw:
+        cfg: dict[str, Any] = {}
+        for j, f in enumerate(factors):
+            if f.factor_type == FactorType.CONTINUOUS and f.bounds is not None:
+                lo, hi = f.bounds
+                cfg[f.name] = lo + row[j] * (hi - lo)
+            elif f.levels is not None:
+                idx = int(row[j] * len(f.levels))
+                idx = min(idx, len(f.levels) - 1)
+                cfg[f.name] = f.levels[idx]
+        configs.append(cfg)
+    return configs
+
+
+def screen(
+    run_fn: Callable[[dict[str, Any]], dict[str, float]],
+    factors: list[Factor],
+    *,
+    method: str = "morris",
+    n_trajectories: int = 100,
+    seed: int = 42,
+) -> dict[str, NDArray[np.floating[Any]]]:
+    """Screen factors for influence on observables via SALib.
+
+    Args:
+        run_fn: Callable that takes a config dict and returns a dict of
+            observable name → scalar score.
+        factors: List of continuous factors to screen.
+        method: Screening method ("morris" or "sobol").
+        n_trajectories: Number of Morris trajectories or Sobol samples.
+        seed: Random seed.
+
+    Returns:
+        Dictionary mapping observable names to arrays of factor importance
+        (mu_star for Morris, S1 for Sobol), one value per factor.
+
+    Raises:
+        NotImplementedError: If method is not "morris".
+        ValueError: If no continuous factors are provided.
+    """
+    from SALib.analyze import morris as morris_analyze  # type: ignore[import-untyped]
+    from SALib.sample import morris as morris_sample  # type: ignore[import-untyped]
+
+    if method != "morris":
+        msg = f"Screening method {method!r} not yet implemented"
+        raise NotImplementedError(msg)
+
+    continuous = [f for f in factors if f.factor_type == FactorType.CONTINUOUS]
+    if not continuous:
+        msg = "Screening requires at least one continuous factor"
+        raise ValueError(msg)
+
+    problem: dict[str, Any] = {
+        "num_vars": len(continuous),
+        "names": [f.name for f in continuous],
+        "bounds": [list(f.bounds) for f in continuous if f.bounds is not None],
+    }
+    param_values = morris_sample.sample(problem, n_trajectories, seed=seed)
+
+    # Evaluate model at each sample point
+    results_by_obs: dict[str, list[float]] = {}
+    for row in param_values:
+        cfg = dict(zip(problem["names"], row, strict=True))
+        scores = run_fn(cfg)
+        for obs_name, val in scores.items():
+            results_by_obs.setdefault(obs_name, []).append(val)
+
+    importance: dict[str, NDArray[np.floating[Any]]] = {}
+    for obs_name, vals in results_by_obs.items():
+        si = morris_analyze.analyze(
+            problem,
+            param_values,
+            np.array(vals),
+            seed=seed,
+        )
+        importance[obs_name] = np.asarray(si["mu_star"], dtype=np.float64)
+
+    return importance
+
+
+def reduce_factors(
+    factors: list[Factor],
+    importance: dict[str, NDArray[np.floating[Any]]],
+    *,
+    threshold: float = 0.1,
+) -> list[Factor]:
+    """Keep only factors whose max importance exceeds threshold.
+
+    Args:
+        factors: Original factor list.
+        importance: Output of ``screen()``.
+        threshold: Minimum importance to retain a factor.
+
+    Returns:
+        Reduced list of influential factors.
+    """
+    continuous = [f for f in factors if f.factor_type == FactorType.CONTINUOUS]
+    non_continuous = [f for f in factors if f.factor_type != FactorType.CONTINUOUS]
+
+    max_importance = np.zeros(len(continuous))
+    for arr in importance.values():
+        max_importance = np.maximum(max_importance, arr)
+
+    kept = [
+        f for f, imp in zip(continuous, max_importance, strict=True) if imp >= threshold
+    ]
+    return non_continuous + kept