chap-core 2.2.0__tar.gz → 2.3.0__tar.gz

{chap_core-2.2.0 → chap_core-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: chap_core
-Version: 2.2.0
+Version: 2.3.0
 Summary: Climate Health Analysis Platform (CHAP)
 Keywords: chap_core
 Author: Chap Team

{chap_core-2.2.0 → chap_core-2.3.0}/chap_core/assessment/evaluation.py

@@ -11,7 +11,7 @@ from abc import ABC, abstractmethod
 from collections.abc import Iterable
 from dataclasses import dataclass
 from pathlib import Path
-from typing import TYPE_CHECKING, cast
+from typing import cast
 
 import numpy as np
 import pandas as pd
@@ -19,14 +19,7 @@ import pandera.pandas as pa
 import xarray as xr
 from packaging.version import Version
 
-from chap_core.assessment.weather_providers import (
-    DEFAULT_WEATHER_PROVIDER_ID,
-    LEGACY_WEATHER_PROVIDER_ID,
-)
-
-if TYPE_CHECKING:
-    from chap_core.api_types import BacktestParams
-
+from chap_core.api_types import BacktestParams
 from chap_core.assessment.flat_representations import (
     FlatForecasts,
     FlatObserved,
@@ -34,10 +27,14 @@ from chap_core.assessment.flat_representations import (
     convert_backtest_to_flat_forecasts,
     max_horizon_distance,
 )
+from chap_core.assessment.weather_providers import (
+    DEFAULT_WEATHER_PROVIDER_ID,
+    LEGACY_WEATHER_PROVIDER_ID,
+)
 from chap_core.data import DataSet as _DataSet
 from chap_core.database.dataset_tables import DataSet, Observation, ObservationBase
 from chap_core.database.model_templates_and_config_tables import ConfiguredModelDB
-from chap_core.database.tables import Backtest, BacktestForecast
+from chap_core.database.tables import Backtest, BacktestForecast, BacktestSpecification
 from chap_core.datatypes import SamplesWithTruth
 from chap_core.external.model_configuration import ModelTemplateConfigV2
 from chap_core.rest_api.data_models import BacktestCreate
@@ -284,8 +281,8 @@ class Evaluation(EvaluationBase):
     def future_weather_provider(self) -> str:
         """Id of the future-weather provider these results were produced with.
 
-        The backtest row is the single source of truth, so database persistence
-        and NetCDF exports cannot disagree.
+        The backtest's specification is the single source of truth, so database
+        persistence and NetCDF exports cannot disagree.
         """
         return self._backtest.future_weather_provider
 
@@ -311,12 +308,22 @@ class Evaluation(EvaluationBase):
         info: BacktestCreate,
         historical_observations: list[Observation] | None = None,
         historical_context_periods: int = 0,
+        specification: BacktestSpecification | None = None,
     ) -> "Evaluation":
         info.created = datetime.datetime.now()
+        # The parameters live on the specification now and are computed fields on
+        # Backtest, reading through the link. Excluding them here keeps that explicit;
+        # passing them would be silently ignored rather than rejected.
         backtest = Backtest(
-            **info.model_dump()
+            **info.model_dump(exclude=set(BacktestParams.model_fields))
             | {"model_db_id": configured_model.id, "model_template_version": configured_model.model_template.version}
         )
+        # Callers persisting the backtest pass the deduplicated row resolved against the
+        # database. The CLI paths build an in-memory evaluation only, so a detached
+        # specification carrying the same parameters is enough for them.
+        backtest.specification = specification or BacktestSpecification(
+            dataset_id=info.dataset_id, **info.model_dump(include=set(BacktestParams.model_fields))
+        )
         org_units = set()
         split_points = set()
         observations = []
@@ -393,7 +400,7 @@ class Evaluation(EvaluationBase):
         configured_model: ConfiguredModelDB,
         estimator,
         dataset: _DataSet,
-        backtest_params: "BacktestParams",
+        backtest_params: BacktestParams,
         backtest_name: str = "evaluation",
         historical_context_years: int = 6,
     ) -> "Evaluation":
@@ -689,7 +696,13 @@ class Evaluation(EvaluationBase):
             split_periods=split_periods,
             forecasts=[],
             dataset_id=0,
-            future_weather_provider=str(ds.attrs["future_weather_provider"]),
+            # The stored file carries no parameters beyond the provider, so this is a
+            # detached placeholder that keeps the parameter properties readable.
+            specification=BacktestSpecification(
+                dataset_id=0,
+                org_units=org_units,
+                future_weather_provider=str(ds.attrs["future_weather_provider"]),
+            ),
         )
 
         forecasts_df = pd.DataFrame(cast("pd.DataFrame", flat_data.forecasts))

{chap_core-2.2.0 → chap_core-2.3.0}/chap_core/assessment/metrics/__init__.py

@@ -83,13 +83,11 @@ def _discover_metrics():
         above_truth,
         crps,
         crps_norm,
-        example_metric,
         mae,
         mape,
         outbreak_detection,
         percentile_coverage,
         rmse,
-        test_metrics,
         winkler_score,
     )
 
@@ -101,7 +99,6 @@ _discover_metrics()
 from chap_core.assessment.metrics.above_truth import RatioAboveTruthMetric
 from chap_core.assessment.metrics.crps import CRPSLog1pMetric, CRPSMetric
 from chap_core.assessment.metrics.crps_norm import CRPSNormMetric
-from chap_core.assessment.metrics.example_metric import ExampleMetric
 from chap_core.assessment.metrics.mae import MAEMetric
 from chap_core.assessment.metrics.mape import MAPEMetric
 from chap_core.assessment.metrics.outbreak_detection import (
@@ -116,7 +113,6 @@ from chap_core.assessment.metrics.percentile_coverage import (
     PercentileCoverageMetric,
 )
 from chap_core.assessment.metrics.rmse import RMSEMetric
-from chap_core.assessment.metrics.test_metrics import SampleCountMetric
 from chap_core.assessment.metrics.winkler_score import (
     WinklerScore10_90Log1pMetric,
     WinklerScore10_90Metric,
@@ -139,7 +135,6 @@ __all__ = [
     "Coverage25_75Metric",
     "DataDimension",
     "DeterministicMetric",
-    "ExampleMetric",
     "MAEMetric",
     "MAPEMetric",
     "Metric",
@@ -151,7 +146,6 @@ __all__ = [
     "ProbabilisticMetric",
     "RMSEMetric",
     "RatioAboveTruthMetric",
-    "SampleCountMetric",
     "SensitivityMetric",
     "SpecificityMetric",
     "WinklerScore10_90Log1pMetric",

{chap_core-2.2.0 → chap_core-2.3.0}/chap_core/assessment/metrics/mape.py

@@ -18,8 +18,8 @@ class MAPEMetric(DeterministicMetric):
     """
     Mean Absolute Percentage Error metric.
 
-    Computes the average of the absolute error for each entry. When aggregated using
-    MEAN, this produces the MAPE (mean of absolute percentage error).
+    Computes the absolute percentage error at the detailed level. When aggregated
+    using MEAN, this produces the MAPE (mean of absolute percentage errors).
 
     Usage:
         mape = MAPEMetric()
@@ -32,12 +32,12 @@ class MAPEMetric(DeterministicMetric):
         metric_id="mape",
         metric_name="MAPE",
         aggregation_op=AggregationOp.MEAN,
-        description="Mean Absolute Percentage Error - measures average absolute prediction error",
+        description="Mean Absolute Percentage Error - average absolute error as percent of observed",
         optimization_direction=OptimizationDirection.MINIMIZE,
     )
 
     def compute_point_metric(self, forecast: float, observed: float) -> float:
-        """Compute absolute error for a single forecast/observation pair."""
+        """Compute absolute percentage error for a single forecast/observation pair."""
         if observed == 0.0:
             return np.nan
         return abs(observed - forecast) / abs(observed) * 100.0

{chap_core-2.2.0 → chap_core-2.3.0}/chap_core/assessment/metrics/outbreak_detection.py

@@ -20,8 +20,9 @@ from chap_core.assessment.metrics.base import (
 
 # The outbreak metrics score forecasts against seasonal thresholds, computed by the
 # threshold strategy module.
-from chap_core.assessment.thresholds.seasonal import _extract_month, compute_seasonal_thresholds
+from chap_core.assessment.thresholds.seasonal import compute_seasonal_thresholds
 from chap_core.time_period import TimePeriod
+from chap_core.time_period.vectorized import extract_month
 
 
 def _get_thresholds(metric_instance: Metric) -> pd.DataFrame:
@@ -68,7 +69,7 @@ class SensitivityMetric(Metric):
             return empty
 
         obs = observations[["location", "time_period", "disease_cases"]].copy()
-        obs["month"] = _extract_month(obs["time_period"])
+        obs["month"] = extract_month(obs["time_period"])
         obs = obs.merge(thresholds, on=["location", "month"], how="left")
 
         # Keep only condition-positive rows (actual outbreaks)
@@ -78,7 +79,7 @@ class SensitivityMetric(Metric):
 
         # Merge forecasts with thresholds
         fc = forecasts.copy()
-        fc["month"] = _extract_month(fc["time_period"])
+        fc["month"] = extract_month(fc["time_period"])
         fc = fc.merge(thresholds, on=["location", "month"], how="left")
 
         # Compute alert per (location, time_period, horizon_distance)
@@ -121,7 +122,7 @@ class SpecificityMetric(Metric):
             return empty
 
         obs = observations[["location", "time_period", "disease_cases"]].copy()
-        obs["month"] = _extract_month(obs["time_period"])
+        obs["month"] = extract_month(obs["time_period"])
         obs = obs.merge(thresholds, on=["location", "month"], how="left")
 
         # Keep only condition-negative rows (no outbreak)
@@ -131,7 +132,7 @@ class SpecificityMetric(Metric):
 
         # Merge forecasts with thresholds
         fc = forecasts.copy()
-        fc["month"] = _extract_month(fc["time_period"])
+        fc["month"] = extract_month(fc["time_period"])
         fc = fc.merge(thresholds, on=["location", "month"], how="left")
 
         # Compute alert per (location, time_period, horizon_distance)
@@ -174,7 +175,7 @@ class OutbreakAccuracyMetric(Metric):
             return empty
 
         obs = observations[["location", "time_period", "disease_cases"]].copy()
-        obs["month"] = _extract_month(obs["time_period"])
+        obs["month"] = extract_month(obs["time_period"])
         obs = obs.merge(thresholds, on=["location", "month"], how="left")
         obs = obs.dropna(subset=["threshold"])
         if obs.empty:
@@ -184,7 +185,7 @@ class OutbreakAccuracyMetric(Metric):
 
         # Merge forecasts with thresholds
         fc = forecasts.copy()
-        fc["month"] = _extract_month(fc["time_period"])
+        fc["month"] = extract_month(fc["time_period"])
         fc = fc.merge(thresholds, on=["location", "month"], how="left")
 
         # Compute alert per (location, time_period, horizon_distance)

{chap_core-2.2.0 → chap_core-2.3.0}/chap_core/assessment/thresholds/__init__.py

@@ -2,28 +2,49 @@
 
 Each strategy is a single class registered with the :func:`threshold` decorator,
 mirroring the ``@backtest_plot`` registry. New strategies are added by writing a
-class and importing its module from :func:`_discover_strategies` — the endpoint
+class with a typed params model, importing its module from
+:func:`_discover_strategies`, and adding the params model to
+:data:`~chap_core.assessment.thresholds.params.ThresholdParams` — the endpoint
 code never needs editing.
 """
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, get_args
+
 from chap_core.assessment.thresholds.base import ThresholdStrategyBase
 
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
 # Global registry for threshold strategies
 _threshold_strategies_registry: dict[str, type[ThresholdStrategyBase]] = {}
 
 
-def threshold(strategy_id: str, name: str, description: str = ""):
-    """Decorator to register a threshold strategy class."""
+def params_type_literal(params_model: type[BaseModel]) -> str:
+    """The value of a params model's required ``type: Literal[...]`` discriminator field."""
+    (literal,) = get_args(params_model.model_fields["type"].annotation)
+    return str(literal)
+
+
+def threshold(strategy_id: str, name: str, params_model: type[BaseModel], description: str = ""):
+    """Decorator to register a threshold strategy class with its typed params model."""
 
     def decorator(cls: type[ThresholdStrategyBase]) -> type[ThresholdStrategyBase]:
         if not issubclass(cls, ThresholdStrategyBase):
             raise TypeError(f"{cls.__name__} must inherit from ThresholdStrategyBase")
 
+        type_literal = params_type_literal(params_model)
+        if type_literal != strategy_id:
+            raise ValueError(
+                f"{params_model.__name__}.type literal {type_literal!r} does not match "
+                f"registered strategy id {strategy_id!r}"
+            )
+
         cls.id = strategy_id
         cls.name = name
         cls.description = description
+        cls.params_model = params_model
 
         _threshold_strategies_registry[strategy_id] = cls
         return cls
@@ -52,6 +73,7 @@ def list_threshold_strategies() -> list[dict]:
 
 def _discover_strategies():
     from chap_core.assessment.thresholds import (
+        percentile,
         seasonal,
     )
 

chap_core-2.3.0/chap_core/assessment/thresholds/base.py

@@ -0,0 +1,76 @@
+"""Base class for threshold (endemic channel) calculation strategies.
+
+A strategy turns a dataset's historical ``disease_cases`` observations into one
+or more threshold lines per requested ``(period_id, org_unit)``. Subclasses
+implement :meth:`compute`; registration happens via the :func:`threshold`
+decorator, which also binds the strategy's typed params model.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pandas as pd
+    from pydantic import BaseModel
+
+
+class ThresholdStrategyBase[ParamsT: BaseModel](ABC):
+    """Base class for threshold strategies.
+
+    Subclasses implement :meth:`compute`, which receives a flat DataFrame of
+    historical observations, the periods to produce thresholds for, and the
+    strategy's validated params model, and returns one row per
+    ``(period_id, location, line)``.
+    """
+
+    id: str = ""
+    name: str = ""
+    description: str = ""
+    params_model: type[ParamsT]
+
+    @abstractmethod
+    def compute(
+        self,
+        historical_observations: pd.DataFrame,
+        period_ids: list[str],
+        params: ParamsT,
+    ) -> pd.DataFrame:
+        """Compute thresholds for the requested periods.
+
+        Args:
+            historical_observations: DataFrame with columns
+                ``[location, time_period, disease_cases]``.
+            period_ids: Periods to produce thresholds for (e.g. ``["2024-01"]``).
+            params: Validated instance of :attr:`params_model`.
+
+        Returns:
+            DataFrame with columns ``[period_id, location, line, threshold]`` —
+            one row per ``(period_id, location, line)``, where ``line`` is the
+            zero-based index into ``params.lines``. Combinations the strategy
+            cannot compute may be omitted; the endpoint fills them with ``null``.
+        """
+
+
+def align_seasonal_to_periods(per_season: pd.DataFrame, period_ids: list[str]) -> pd.DataFrame:
+    """Merge per-season threshold lines onto the requested periods.
+
+    Args:
+        per_season: DataFrame with columns ``[location, month|week, line, threshold]``.
+        period_ids: Periods to produce thresholds for.
+
+    Returns:
+        DataFrame with columns ``[period_id, location, line, threshold]``.
+    """
+    import pandas as pd
+
+    from chap_core.time_period.vectorized import season_column
+
+    requested = pd.DataFrame({"period_id": period_ids})
+    season, buckets = season_column(requested["period_id"])
+    if season not in per_season.columns:
+        raise ValueError(f"period_ids are {season}-based but the dataset's time periods have a different frequency")
+    requested[season] = buckets
+    merged = requested.merge(per_season, on=season)
+    return merged[["period_id", "location", "line", "threshold"]]

chap_core-2.3.0/chap_core/assessment/thresholds/params.py

@@ -0,0 +1,82 @@
+"""Typed per-strategy parameter models for the thresholds API.
+
+Each strategy declares a pydantic model whose required ``type`` literal is the
+discriminator selecting the strategy, so the OpenAPI schema renders
+:data:`ThresholdParams` as a tagged union that generated clients can build a
+strategy picker and per-strategy params form from. ``type`` has no default on
+purpose: a default would make it optional in the schema, and an optional
+discriminator cannot tell the union members apart in generated code. The
+:func:`~chap_core.assessment.thresholds.threshold` registry decorator asserts
+each strategy's model literal matches its registered id.
+
+Line parameters (``std_multiplier``, ``quantile``) accept a scalar or a list;
+each list entry produces one threshold line in the response, computed over the
+same historical window. Every model exposes the normalized list as
+:attr:`ThresholdParamsBase.lines`, which the strategies compute from and the
+endpoint echoes so clients can label lines without knowing the strategy.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import Field
+
+from chap_core.database.base_tables import DBModel
+
+Fraction = Annotated[float, Field(ge=0.0, le=1.0)]
+
+
+class ThresholdParamsBase(DBModel):
+    """Common interface of the per-strategy params models."""
+
+    @property
+    def lines(self) -> list[float]:
+        """The line parameter as a list, one value per threshold line, in request order."""
+        raise NotImplementedError
+
+
+class SeasonalParams(ThresholdParamsBase):
+    """Parameters for the seasonal mean + k*std strategy."""
+
+    type: Literal["seasonal"]
+    std_multiplier: float | Annotated[list[float], Field(min_length=1)] = Field(
+        2.0,
+        description="Number of standard deviations above the seasonal mean. "
+        "A list produces one threshold line per entry.",
+    )
+
+    @property
+    def lines(self) -> list[float]:
+        return line_values(self.std_multiplier)
+
+
+class PercentileParams(ThresholdParamsBase):
+    """Parameters for the seasonal percentile (WHO endemic channel) strategy."""
+
+    type: Literal["percentile"]
+    quantile: Fraction | Annotated[list[Fraction], Field(min_length=1)] = Field(
+        0.75,
+        description="Percentile of historical same-season values, as a fraction in [0, 1]. "
+        "A list produces one threshold line per entry, e.g. `[0.25, 0.75]` for the endemic channel band.",
+    )
+    baseline_years: int | None = Field(
+        5,
+        ge=1,
+        description="Number of the most recent complete years in the dataset to compute the baseline from. "
+        "A partial final year is excluded. `null` uses all available history.",
+    )
+
+    @property
+    def lines(self) -> list[float]:
+        return line_values(self.quantile)
+
+
+ThresholdParams = Annotated[SeasonalParams | PercentileParams, Field(discriminator="type")]
+
+
+def line_values(scalar_or_list: float | list[float]) -> list[float]:
+    """Normalize a line parameter to the list of per-line values."""
+    if isinstance(scalar_or_list, list):
+        return scalar_or_list
+    return [scalar_or_list]

chap_core-2.3.0/chap_core/assessment/thresholds/percentile.py

@@ -0,0 +1,113 @@
+"""Percentile threshold strategy: WHO-style endemic channel from historical same-season values.
+
+Malaria surveillance programmes plot channel graphs from a percentile of the previous few
+complete years, reading a value above the upper line as an outbreak. A percentile is used
+rather than mean + k*std because case counts are heavily right-skewed and a single past
+epidemic year inflates the standard deviation far above any plausible endemic level.
+
+The channel is static: one dataset defines one threshold per (location, season), computed
+from the most recent complete years in the dataset, and the requested periods only select
+which rows come back. Past and future periods therefore share one line. A consequence is
+that a past period is scored against a baseline that includes it, so a historical epidemic
+partly raises the line it is plotted against. That is inherent to the endemic-channel idiom.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from chap_core.assessment.thresholds import threshold
+from chap_core.assessment.thresholds.base import ThresholdStrategyBase, align_seasonal_to_periods
+from chap_core.assessment.thresholds.params import PercentileParams
+from chap_core.time_period.vectorized import extract_year, season_column
+
+_FULL_YEAR_BUCKETS = {"month": 12, "week": 52}
+
+
+def last_complete_year(historical_observations: pd.DataFrame) -> int:
+    """Return the latest year in the data, or the year before it when the latest year is partial.
+
+    A year is complete when it has every season bucket (12 months or at least 52 weeks).
+    A live dataset's final year is usually in progress; including it would give the
+    early-season buckets one more observation than the late-season ones, and would let an
+    outbreak in progress raise the threshold it is about to be compared against.
+    """
+    years = extract_year(historical_observations["time_period"])
+    season, buckets = season_column(historical_observations["time_period"])
+    latest = int(years.max())
+    latest_buckets = pd.Index(buckets)[years == latest].nunique()
+    if latest_buckets < _FULL_YEAR_BUCKETS[season]:
+        return latest - 1
+    return latest
+
+
+def filter_to_baseline(historical_observations: pd.DataFrame, baseline_years: int | None) -> pd.DataFrame:
+    """Restrict observations to the most recent ``baseline_years`` complete years in the dataset.
+
+    The window is anchored on the dataset, not on the requested periods, so every requested
+    period, past or future, is compared against the same line. A partial final year is
+    excluded (see :func:`last_complete_year`). Pass ``None`` to use all available history.
+    """
+    if baseline_years is None:
+        return historical_observations
+
+    years = extract_year(historical_observations["time_period"])
+    last = last_complete_year(historical_observations)
+    first = last - baseline_years + 1
+    windowed = historical_observations[(years >= first) & (years <= last)]
+
+    if windowed.empty:
+        raise ValueError(
+            f"No complete years in the {baseline_years}-year baseline window {first}-{last}; "
+            f"the data covers {int(years.min())}-{int(years.max())}"
+        )
+    return windowed
+
+
+def compute_percentile_thresholds(historical_observations: pd.DataFrame, quantiles: list[float]) -> pd.DataFrame:
+    """Compute outbreak threshold lines as per-season percentiles of historical observations.
+
+    All quantiles are computed from one groupby pass over the same observations.
+
+    Args:
+        historical_observations: DataFrame with columns [location, time_period, disease_cases]
+        quantiles: Percentiles to take, as fractions (e.g. ``[0.25, 0.75]``).
+
+    Returns:
+        DataFrame with columns [location, month|week, line, threshold], where ``line``
+        is the index into ``quantiles``.
+    """
+    df = historical_observations.copy()
+    season, buckets = season_column(df["time_period"])
+    df[season] = buckets
+    unique_quantiles = list(dict.fromkeys(quantiles))
+    per_quantile = df.groupby(["location", season])["disease_cases"].quantile(pd.Series(unique_quantiles)).unstack()
+    lines = []
+    for i, quantile in enumerate(quantiles):
+        line = per_quantile[quantile].rename("threshold").reset_index()
+        line["line"] = i
+        lines.append(line)
+    return pd.concat(lines, ignore_index=True)[["location", season, "line", "threshold"]]
+
+
+@threshold(
+    "percentile",
+    "Seasonal percentile (WHO)",
+    PercentileParams,
+    "Outbreak threshold as a percentile of historical same-month (or same-week) values, over a "
+    "baseline window of the most recent complete years in the dataset. Defaults to the 75th "
+    "percentile over 5 years, the WHO "
+    "malaria channel practice. Robust to past epidemic years, which inflate mean + k*std.",
+)
+class PercentileThresholdStrategy(ThresholdStrategyBase[PercentileParams]):
+    """Registered strategy computing one line per requested quantile from a shared baseline window."""
+
+    def compute(
+        self,
+        historical_observations: pd.DataFrame,
+        period_ids: list[str],
+        params: PercentileParams,
+    ) -> pd.DataFrame:
+        windowed = filter_to_baseline(historical_observations, params.baseline_years)
+        per_season = compute_percentile_thresholds(windowed, params.lines)
+        return align_seasonal_to_periods(per_season, period_ids)

chap_core-2.3.0/chap_core/assessment/thresholds/seasonal.py

@@ -0,0 +1,66 @@
+"""Seasonal threshold strategy: mean + k*std over historical same-season (month or week) values."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from chap_core.assessment.thresholds import threshold
+from chap_core.assessment.thresholds.base import ThresholdStrategyBase, align_seasonal_to_periods
+from chap_core.assessment.thresholds.params import SeasonalParams
+from chap_core.time_period.vectorized import season_column
+
+
+def seasonal_stats(historical_observations: pd.DataFrame) -> tuple[str, pd.DataFrame]:
+    """Per-(location, season) mean and std of disease_cases.
+
+    Returns:
+        The season column name ("month" or "week") and a DataFrame with columns
+        ``[location, month|week, mean, std]``.
+    """
+    df = historical_observations.copy()
+    season, buckets = season_column(df["time_period"])
+    df[season] = buckets
+    grouped = df.groupby(["location", season])["disease_cases"].agg(["mean", "std"]).reset_index()
+    return season, grouped
+
+
+def compute_seasonal_thresholds(historical_observations: pd.DataFrame, k: float = 2.0) -> pd.DataFrame:
+    """Compute outbreak thresholds from historical observations.
+
+    Args:
+        historical_observations: DataFrame with columns [location, time_period, disease_cases]
+        k: Number of standard deviations above the mean (default 2.0).
+
+    Returns:
+        DataFrame with columns [location, month, threshold] for monthly data,
+        or [location, week, threshold] for weekly data.
+    """
+    season, grouped = seasonal_stats(historical_observations)
+    grouped["threshold"] = grouped["mean"] + k * grouped["std"]
+    return grouped[["location", season, "threshold"]]
+
+
+@threshold(
+    "seasonal",
+    "Seasonal mean + k*std",
+    SeasonalParams,
+    "Outbreak threshold as mean + k standard deviations of historical same-month (or same-week) values.",
+)
+class SeasonalThresholdStrategy(ThresholdStrategyBase[SeasonalParams]):
+    """Registered strategy computing one line per requested std multiplier from shared seasonal stats."""
+
+    def compute(
+        self,
+        historical_observations: pd.DataFrame,
+        period_ids: list[str],
+        params: SeasonalParams,
+    ) -> pd.DataFrame:
+        season, stats = seasonal_stats(historical_observations)
+        lines = []
+        for i, multiplier in enumerate(params.lines):
+            line = stats[["location", season]].copy()
+            line["line"] = i
+            line["threshold"] = stats["mean"] + multiplier * stats["std"]
+            lines.append(line)
+        per_season = pd.concat(lines, ignore_index=True)
+        return align_seasonal_to_periods(per_season, period_ids)

{chap_core-2.2.0 → chap_core-2.3.0}/chap_core/cli_endpoints/generate_modelcard.py

@@ -325,7 +325,6 @@ def _build_results_summary(backtest: Backtest) -> str:
             f"MAE (aggregate): {metrics.get('mae')}\n",
             f"Coverage within 10-90%: {metrics.get('coverage_10_90')}\n",
             f"Coverage within 25-75%: {metrics.get('coverage_25_75')}\n",
-            f"Sample count: {metrics.get('sample_count')}\n",
         ]
     )