views-baseline 1.0.0__py3-none-any.whl

views_baseline/evaluation/closeness.py

@@ -0,0 +1,152 @@
+"""Closeness-to-conflictology measurement harness (ADR-022 / epic #33 S3).
+
+Operationalises "I couldn't tell which model the 1000 draws came from" as a
+distributional two-sample comparison between two ``dict[str, PredictionFrame]``:
+
+- per (cell, target): 1-Wasserstein, energy distance, and a 1-NN **C2ST** accuracy
+  (0.5 = indistinguishable);
+- a **same-model null** (conflictology two seeds) as the finite-N noise floor;
+- **stratification** by activity regime (zero / low / high), target, and level;
+- an **equivalence** verdict against a pre-registered margin ``delta`` (not a p-value).
+
+This module is *not* in the model path — it only consumes PredictionFrames.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.stats import energy_distance, wasserstein_distance
+
+# Activity strata by the reference (conflictology) per-cell mean, in raw counts.
+_LOW_HIGH_CUT = 1.0  # mean < this (and not all-zero) = "low"; >= this = "high"
+
+
+def c2st_1nn(a: np.ndarray, b: np.ndarray, rng: np.random.Generator | None = None) -> float:
+    """Leave-one-out 1-NN classifier two-sample accuracy in 1-D.
+
+    Pools the two balanced samples, labels them, and for each point asks whether its
+    nearest neighbour shares its label. ``0.5`` ⇒ indistinguishable, ``1.0`` ⇒
+    perfectly separable. Pure numpy, O(n log n). Ties (e.g. constant/degenerate
+    cells) are broken by a random permutation before the stable sort, so identical
+    samples score ~0.5 rather than spuriously ~1.0.
+    """
+    rng = np.random.default_rng(0) if rng is None else rng
+    a = np.asarray(a, dtype=np.float64).ravel()
+    b = np.asarray(b, dtype=np.float64).ravel()
+    x = np.concatenate([a, b])
+    y = np.concatenate([np.zeros(len(a)), np.ones(len(b))])
+    n = len(x)
+    if n < 2:
+        return 0.5
+    perm = rng.permutation(n)  # randomise tie order
+    x, y = x[perm], y[perm]
+    order = np.argsort(x, kind="mergesort")  # stable → ties keep the random order
+    xs, ys = x[order], y[order]
+    dl = np.empty(n)
+    dl[0] = np.inf
+    dl[1:] = xs[1:] - xs[:-1]
+    dr = np.empty(n)
+    dr[-1] = np.inf
+    dr[:-1] = xs[1:] - xs[:-1]
+    idx = np.arange(n)
+    nn = np.where(dl <= dr, idx - 1, idx + 1)
+    return float((ys[nn] == ys).mean())
+
+
+def _cell_map(pf) -> dict:
+    """Map (unit, time) -> row index for a PredictionFrame."""
+    time = np.asarray(pf.index.time)
+    unit = np.asarray(pf.index.unit)
+    return {(int(u), int(t)): i for i, (u, t) in enumerate(zip(unit, time))}
+
+
+def _stratum(ref_samples: np.ndarray) -> str:
+    m = float(np.mean(ref_samples))
+    if m == 0.0:
+        return "zero"
+    return "low" if m < _LOW_HIGH_CUT else "high"
+
+
+def compare_models(model: dict, reference: dict, seed: int = 0) -> dict:
+    """Per-cell distances between ``model`` and ``reference`` (e.g. conflictology).
+
+    Both are ``dict[str, PredictionFrame]`` with ``.values`` shape ``(N, S)``. Cells
+    are aligned by ``(unit, time)``; the stratum is assigned from the *reference*
+    per-cell mean. ``seed`` makes the C2ST tie-breaking reproducible. Returns
+    ``{target: {"wasserstein","energy","c2st","stratum","level"}}`` with numpy arrays
+    over the common cells.
+    """
+    rng = np.random.default_rng(seed)
+    out = {}
+    for target, ref_pf in reference.items():
+        mod_pf = model[target]
+        ref_map, mod_map = _cell_map(ref_pf), _cell_map(mod_pf)
+        common = [k for k in ref_map if k in mod_map]
+        w = np.empty(len(common))
+        e = np.empty(len(common))
+        c = np.empty(len(common))
+        strat = np.empty(len(common), dtype=object)
+        for j, key in enumerate(common):
+            ra = np.asarray(ref_pf.values[ref_map[key]], dtype=np.float64).ravel()
+            ma = np.asarray(mod_pf.values[mod_map[key]], dtype=np.float64).ravel()
+            w[j] = wasserstein_distance(ma, ra)
+            e[j] = energy_distance(ma, ra)
+            c[j] = c2st_1nn(ma, ra, rng)
+            strat[j] = _stratum(ra)
+        out[target] = {
+            "wasserstein": w,
+            "energy": e,
+            "c2st": c,
+            "stratum": strat,
+            "level": ref_pf.index.level.name,
+        }
+    return out
+
+
+def summarize(metrics: dict) -> dict:
+    """Stratified summary: per (target, stratum) → median / p90 / p99 of each metric."""
+    rows = {}
+    for target, m in metrics.items():
+        for stratum in ("zero", "low", "high", "all"):
+            mask = np.ones(len(m["c2st"]), bool) if stratum == "all" else (m["stratum"] == stratum)
+            if not mask.any():
+                continue
+            rows[(target, stratum)] = {
+                "n": int(mask.sum()),
+                "wasserstein": _pcts(m["wasserstein"][mask]),
+                "energy": _pcts(m["energy"][mask]),
+                "c2st": _pcts(m["c2st"][mask]),
+            }
+    return rows
+
+
+def _pcts(a: np.ndarray) -> dict:
+    return {
+        "median": float(np.median(a)),
+        "p90": float(np.percentile(a, 90)),
+        "p99": float(np.percentile(a, 99)),
+    }
+
+
+def equivalence(candidate: dict, null: dict, delta: dict) -> dict:
+    """Per (target, stratum) equivalence verdict.
+
+    A candidate is *equivalent to conflictology* in a stratum when its median C2ST is
+    within ``0.5 + delta["c2st"]`` AND its median Wasserstein is within the same-model
+    null median plus ``delta["wasserstein"]``.
+    """
+    verdict = {}
+    for key, cand in candidate.items():
+        null_row = null.get(key)
+        c2st_ok = cand["c2st"]["median"] <= 0.5 + delta["c2st"]
+        w_ref = null_row["wasserstein"]["median"] if null_row else 0.0
+        w_ok = cand["wasserstein"]["median"] <= w_ref + delta["wasserstein"]
+        verdict[key] = {
+            "equivalent": bool(c2st_ok and w_ok),
+            "c2st_median": cand["c2st"]["median"],
+            "c2st_ok": bool(c2st_ok),
+            "wasserstein_median": cand["wasserstein"]["median"],
+            "wasserstein_null_median": w_ref,
+            "wasserstein_ok": bool(w_ok),
+        }
+    return verdict

views_baseline/infrastructure/exceptions.py

@@ -0,0 +1,10 @@
+class ReproducibilityError(Exception):
+    """Base class for all reproducibility gate failures."""
+
+    pass
+
+
+class MissingHyperparameterError(ReproducibilityError):
+    """Raised when a mandatory hyperparameter is missing from the config."""
+
+    pass

views_baseline/infrastructure/reproducibility_gate.py

@@ -0,0 +1,112 @@
+import logging
+
+from .exceptions import MissingHyperparameterError
+
+logger = logging.getLogger(__name__)
+
+
+class ReproducibilityGate:
+    """
+    Canonical hyperparameter contract for views-baseline models.
+
+    Defines which configuration keys are required by all baseline models
+    (CORE_GENOME) and which are required per algorithm (ALGORITHM_GENOMES).
+    The audit_manifest() method enforces these contracts at runtime.
+
+    This class is importable by downstream packages (e.g. views-models)
+    so they can validate their config_hyperparameters.py files statically.
+    """
+
+    class Config:
+        """Gates related to configuration and hyperparameter integrity."""
+
+        # Core keys required by ALL baseline models regardless of algorithm.
+        CORE_GENOME = ["steps", "time_steps", "prediction_format"]
+
+        # Algorithm-specific keys (audited only when the algorithm matches).
+        ALGORITHM_GENOMES = {
+            "ZeroModel": [],
+            "LocfModel": [],
+            "AverageModel": ["window_months"],
+            "ConflictologyModel": ["window_months", "n_samples", "seed"],
+            "MixtureBaseline": ["window_months", "lambda_mix", "n_samples", "seed"],
+            # Parametric climatology (ADR-022): `family` and `transform` join `seed` as
+            # required, audited reproducibility keys — no magic defaults (ADR-021).
+            "ParametricConflictology": [
+                "window_months", "n_samples", "seed", "family", "transform",
+            ],
+            "ParametricHurdleConflictology": [
+                "window_months", "n_samples", "seed", "family", "transform",
+            ],
+        }
+
+        @staticmethod
+        def audit_manifest(config: dict) -> None:
+            """
+            Verify that all mandatory hyperparameters are present and non-None.
+
+            Checks in order:
+            1. All CORE_GENOME keys are present.
+            2. The algorithm is registered in ALGORITHM_GENOMES.
+            3. All algorithm-specific keys are present.
+            4. No required key has a value of None.
+
+            Raises MissingHyperparameterError on any violation.
+            """
+            # 1. Audit Core Genome
+            missing_core = [
+                k
+                for k in ReproducibilityGate.Config.CORE_GENOME
+                if k not in config
+            ]
+            if missing_core:
+                msg = (
+                    "REPRODUCIBILITY CONTRACT VIOLATED: "
+                    f"Missing core parameters: {missing_core}"
+                )
+                logger.error(msg)
+                raise MissingHyperparameterError(msg)
+
+            # 2. Identify algorithm and check it is registered
+            if "algorithm" not in config:
+                msg = (
+                    "REPRODUCIBILITY CONTRACT VIOLATED: "
+                    "Missing required key: 'algorithm'"
+                )
+                logger.error(msg)
+                raise MissingHyperparameterError(msg)
+
+            algo = config["algorithm"]
+            algo_genomes = ReproducibilityGate.Config.ALGORITHM_GENOMES
+            if algo not in algo_genomes:
+                available = list(algo_genomes.keys())
+                msg = (
+                    "REPRODUCIBILITY CONTRACT VIOLATED: "
+                    f"Unknown algorithm '{algo}'. "
+                    f"Available: {available}"
+                )
+                logger.error(msg)
+                raise MissingHyperparameterError(msg)
+
+            # 3. Audit algorithm-specific keys
+            algo_keys = algo_genomes[algo]
+            missing_algo = [k for k in algo_keys if k not in config]
+            if missing_algo:
+                msg = (
+                    "REPRODUCIBILITY CONTRACT VIOLATED: "
+                    f"Algorithm '{algo}' requires missing parameters: {missing_algo}"
+                )
+                logger.error(msg)
+                raise MissingHyperparameterError(msg)
+
+            # 4. Reject None values for all required keys
+            all_required = list(ReproducibilityGate.Config.CORE_GENOME) + algo_keys
+            explicit_nones = [k for k in all_required if config.get(k) is None]
+            if explicit_nones:
+                msg = (
+                    "REPRODUCIBILITY CONTRACT VIOLATED: "
+                    f"Mandatory parameters set to None: {explicit_nones}. "
+                    "Implicit defaults are forbidden."
+                )
+                logger.error(msg)
+                raise MissingHyperparameterError(msg)

views_baseline/manager/baseline_manager.py

@@ -0,0 +1,152 @@
+import logging
+import pickle
+
+from views_pipeline_core.files.utils import generate_model_file_name, read_dataframe
+from views_pipeline_core.managers.model import ForecastingModelManager, ModelPathManager
+from views_pipeline_core.modules.dataloaders.datafactory_contract import (
+    DATA_FORMAT_DATAFRAME,
+    DATA_FORMAT_FEATURE_FRAME,
+)
+from views_pipeline_core.modules.dataloaders.frame_cache import load_frame_cache
+
+from views_baseline.infrastructure.reproducibility_gate import ReproducibilityGate
+from views_baseline.model.catalog import BaselineModelCatalog
+
+logger = logging.getLogger(__name__)
+
+
+class BaselineForecastingModelManager(ForecastingModelManager):
+    """
+    Baseline Forecasting Model Manager
+    """
+
+    def __init__(
+        self,
+        model_path: ModelPathManager,
+        wandb_notifications: bool = False,
+        use_prediction_store: bool = False,
+    ) -> None:
+        """
+        Initialize Baseline Forecasting Model Manager.
+        """
+        super().__init__(model_path, wandb_notifications, use_prediction_store)
+
+        logger.info("Initializing BaselineModelManager")
+
+    def _train_model_artifact(self):
+        """
+        Fit the baseline model and save it as a pickle artifact.
+
+        Although baselines are stateless and deterministic, the downstream
+        ensemble manager requires an artifact file to exist so it can
+        resolve timestamps via get_latest_model_artifact_path().
+        """
+        self.model, _ = self._setup_model_and_data()
+        path_artifacts = self._model_path.artifacts
+        run_type = self.config["run_type"]
+        model_filename = generate_model_file_name(run_type, file_extension=".pkl")
+        with open(path_artifacts / model_filename, "wb") as f:
+            pickle.dump(self.model, f)
+        logger.info(f"Saved baseline artifact: {model_filename}")
+        return self.model
+
+    def _load_source(self):
+        """Load the fit/predict input for the current partition, dispatching on declared format.
+
+        Frame-native seam (issue #64). A model that declares ``data_format: feature_frame``
+        is served the pipeline-core FeatureFrame directory cache directly, so the
+        ``FeatureFrame`` flows straight into ``fit``/``predict`` with no pandas in the
+        manager — the models have consumed either shape since ADR-019/epic #47. Every other
+        model keeps the byte-identical pandas-parquet path (``read_dataframe``).
+
+        Dispatch is on the declared ``_data_format`` (set by the base manager during data
+        fetching; absent → ``dataframe``, i.e. legacy behavior). The frame branch resolves
+        the cache through the LOUD ``_get_cached_frame_path()`` getter, which raises if the
+        frame cache was never populated. There is deliberately NO silent
+        ``getattr(..., None)`` fallback from the frame path back to pandas: a frames-declared
+        config that has lost its cache must fail loud, never silently degrade to a pandas run
+        (pipeline-core register C-214).
+        """
+        if getattr(self, "_data_format", DATA_FORMAT_DATAFRAME) == DATA_FORMAT_FEATURE_FRAME:
+            return load_frame_cache(self._get_cached_frame_path())
+        return read_dataframe(self._get_cached_data_path())
+
+    def _setup_model_and_data(self):
+        """
+        Instantiate the baseline model via the catalog, load data, fit, and return both.
+        """
+        ReproducibilityGate.Config.audit_manifest(self.config)
+        loa = self.config["level"]
+        partition_dict = self._data_loader.partition_dict
+        catalog = BaselineModelCatalog(
+            config=self.config, partition_dict=partition_dict, loa=loa
+        )
+        model = catalog.get_model(self.config["algorithm"])
+        logger.info(f"Model type is {self.config['algorithm']}")
+        df_source = self._load_source()
+        model.fit(df_source)
+        return model, df_source
+
+    def _generate_predictions(self, model, df, eval_type):
+        """
+        Generate predictions for all sequence numbers in an evaluation.
+
+        All models return Dict[str, PredictionFrame], so this accumulates
+        into Dict[str, list[PredictionFrame]] across sequence numbers.
+        """
+        sequence_numbers = self._resolve_evaluation_sequence_number(eval_type)
+        output_length = self.config["time_steps"]
+
+        predictions = {}
+        for seq_num in range(sequence_numbers):
+            pf_dict = model.predict(
+                df=df, sequence_number=seq_num, output_length=output_length
+            )
+            for target, pf in pf_dict.items():
+                predictions.setdefault(target, []).append(pf)
+        return predictions
+
+    def _evaluate_model_artifact(self, eval_type: str, artifact_name: str = None):
+        """
+        Evaluate trained model artifact.
+        """
+        logger.info("Evaluating baseline model artifact")
+        if artifact_name:
+            path_artifact = self._model_path.artifacts / artifact_name
+        else:
+            path_artifact = self._model_path.get_latest_model_artifact_path(
+                run_type=self.config["run_type"]
+            )
+        self._config_manager.add_config({"timestamp": path_artifact.stem[-15:]})
+        self.model, df_source = self._setup_model_and_data()
+        logger.info(f"Generating predictions for {eval_type} evaluation")
+        return self._generate_predictions(self.model, df_source, eval_type)
+
+    def _forecast_model_artifact(self, artifact_name: str = None):
+        """
+        Generate forecasts using trained model artifact.
+        """
+        logger.info("Generating forecasts")
+        if artifact_name:
+            path_artifact = self._model_path.artifacts / artifact_name
+        else:
+            path_artifact = self._model_path.get_latest_model_artifact_path(
+                run_type=self.config["run_type"]
+            )
+        self._config_manager.add_config({"timestamp": path_artifact.stem[-15:]})
+        self.model, df_source = self._setup_model_and_data()
+        output_length = self.config["time_steps"]
+
+        return self.model.predict(
+            df=df_source, sequence_number=0, output_length=output_length
+        )
+
+    def _evaluate_sweep(self, eval_type: str, model):
+        """
+        Evaluate a baseline model during a WandB sweep iteration.
+
+        The model has already been fitted by _train_model_artifact().
+        We load the data and generate predictions using it.
+        """
+        df_source = self._load_source()
+        return self._generate_predictions(model, df_source, eval_type)

views_baseline/model/__init__.py

@@ -0,0 +1 @@
+

views_baseline/model/catalog.py

@@ -0,0 +1,120 @@
+from views_baseline.infrastructure.reproducibility_gate import ReproducibilityGate
+from views_baseline.model.models.distributional import (
+    ConflictologyModel,
+    MixtureBaseline,
+    ParametricConflictology,
+    ParametricHurdleConflictology,
+)
+from views_baseline.model.models.point import AverageModel, LocfModel, ZeroModel
+
+
+class BaselineModelCatalog:
+    # Single source of truth lives in ReproducibilityGate.Config.ALGORITHM_GENOMES.
+    # This alias keeps the catalog's get_model() validation unchanged.
+    MODEL_GENOMES = ReproducibilityGate.Config.ALGORITHM_GENOMES
+
+    def __init__(self, config: dict, partition_dict: dict, loa: str):
+        """
+        Catalog of available baseline models.
+        """
+        self.config = config
+        self.partition_dict = partition_dict
+        self.loa = loa
+
+        self.models = {
+            "ZeroModel": self._get_zero_model,
+            "LocfModel": self._get_locf_model,
+            "AverageModel": self._get_average_model,
+            "ConflictologyModel": self._get_conflictology_model,
+            "MixtureBaseline": self._get_mixture_model,
+            "ParametricConflictology": self._get_parametric_conflictology,
+            "ParametricHurdleConflictology": self._get_parametric_hurdle,
+        }
+
+    def get_model(self, model_name: str):
+        """
+        Returns an initialized model instance.
+        Validates that required config keys for the model are present.
+        """
+        if model_name not in self.models:
+            raise ValueError(
+                f"Model '{model_name}' is not in the catalog. "
+                f"Available: {self.list_models()}"
+            )
+        missing = [k for k in self.MODEL_GENOMES[model_name] if k not in self.config]
+        if missing:
+            raise ValueError(
+                f"Model '{model_name}' requires config keys {missing} "
+                f"but they are missing"
+            )
+        return self.models[model_name]()
+
+    def list_models(self):
+        return list(self.models.keys())
+
+    def _get_zero_model(self):
+        return ZeroModel(
+            targets=self.config["targets"], partition_dict=self.partition_dict, loa=self.loa
+        )
+
+    def _get_locf_model(self):
+        return LocfModel(
+            targets=self.config["targets"], partition_dict=self.partition_dict, loa=self.loa
+        )
+
+    def _get_average_model(self):
+        return AverageModel(
+            targets=self.config["targets"],
+            window_months=self.config["window_months"],
+            partition_dict=self.partition_dict,
+            loa=self.loa,
+        )
+
+    def _get_conflictology_model(self):
+        return ConflictologyModel(
+            targets=self.config["targets"],
+            window_months=self.config["window_months"],
+            partition_dict=self.partition_dict,
+            loa=self.loa,
+            n_samples=self.config["n_samples"],
+            seed=self.config["seed"],  # required + audited genome key (ADR-021); no silent default
+        )
+
+    def _get_mixture_model(self):
+        return MixtureBaseline(
+            targets=self.config["targets"],
+            window_months=self.config["window_months"],
+            lambda_mix=self.config["lambda_mix"],
+            n_samples=self.config["n_samples"],
+            partition_dict=self.partition_dict,
+            loa=self.loa,
+            seed=self.config["seed"],  # required + audited genome key (ADR-021); no silent default
+        )
+
+    def _get_parametric_conflictology(self):
+        # family/transform/seed are required, audited genome keys (ADR-021/ADR-022); the
+        # constructor fails loud on an unsupported family or an illegal family×transform.
+        return ParametricConflictology(
+            targets=self.config["targets"],
+            window_months=self.config["window_months"],
+            partition_dict=self.partition_dict,
+            loa=self.loa,
+            n_samples=self.config["n_samples"],
+            family=self.config["family"],
+            transform=self.config["transform"],
+            seed=self.config["seed"],
+        )
+
+    def _get_parametric_hurdle(self):
+        # family/transform/seed are required, audited genome keys (ADR-021/ADR-022); the
+        # constructor fails loud on a non-continuous family or an illegal family×transform.
+        return ParametricHurdleConflictology(
+            targets=self.config["targets"],
+            window_months=self.config["window_months"],
+            partition_dict=self.partition_dict,
+            loa=self.loa,
+            n_samples=self.config["n_samples"],
+            family=self.config["family"],
+            transform=self.config["transform"],
+            seed=self.config["seed"],
+        )

views_baseline/model/defaults.py

@@ -0,0 +1,9 @@
+"""Package-level default sentinels for baseline models.
+
+Zero-Magic / Explicit-Defaults (ADR-021): the single source of truth for the
+default RNG seed. It is a **sentinel for direct/test construction only** —
+production configs MUST declare ``seed`` (a required, audited genome key). The
+catalog reads ``config["seed"]`` strictly and never falls back to this constant.
+"""
+
+DEFAULT_SEED = 42

views_baseline/model/distributions/__init__.py

@@ -0,0 +1,64 @@
+"""Distribution family + transform registries for the parametric climatology models.
+
+A **strategy registry** (ADR-022) split across three cohesive leaves:
+
+* :mod:`transforms` — `TRANSFORMS`, `clamp_log`/`clamp_floor`, `EMIT_*` (pure log math).
+* :mod:`families` — per-family `fit_`/`sample_` (method-of-moments; point-mass fallback).
+* :mod:`registry` — `fit_family`/`sample_family` dispatch + `validate_family_transform`.
+
+This package re-exports the stable public surface so importers depend on
+``views_baseline.model.distributions`` and are insulated from the internal split.
+Pure package: numpy + scipy only; no pandas, no views-frames, no model imports.
+"""
+
+from views_baseline.model.distributions.families import (
+    CONTINUOUS_FAMILIES,
+    FAMILIES,
+    NATIVE_ZERO_FAMILIES,
+    fit_gamma,
+    fit_gumbel,
+    fit_lognormal,
+    fit_nb,
+    fit_zinb,
+    sample_gamma,
+    sample_gumbel,
+    sample_lognormal,
+    sample_nb,
+    sample_zinb,
+)
+from views_baseline.model.distributions.registry import (
+    fit_family,
+    sample_family,
+    validate_family_transform,
+)
+from views_baseline.model.distributions.transforms import (
+    EMIT_FLOOR,
+    EMIT_LOG_CEIL,
+    TRANSFORMS,
+    clamp_floor,
+    clamp_log,
+)
+
+__all__ = [
+    "CONTINUOUS_FAMILIES",
+    "EMIT_FLOOR",
+    "EMIT_LOG_CEIL",
+    "FAMILIES",
+    "NATIVE_ZERO_FAMILIES",
+    "TRANSFORMS",
+    "clamp_floor",
+    "clamp_log",
+    "fit_family",
+    "fit_gamma",
+    "fit_gumbel",
+    "fit_lognormal",
+    "fit_nb",
+    "fit_zinb",
+    "sample_family",
+    "sample_gamma",
+    "sample_gumbel",
+    "sample_lognormal",
+    "sample_nb",
+    "sample_zinb",
+    "validate_family_transform",
+]