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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: chap_core
-Version: 2.2.0
+Version: 2.3.1
 Summary: Climate Health Analysis Platform (CHAP)
 Keywords: chap_core
 Author: Chap Team
@@ -52,7 +52,7 @@ Requires-Dist: gunicorn>=25.3.0
 Requires-Dist: optuna>=4.9.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: alembic>=1.18.4
-Requires-Dist: chapkit>=1.0.0,<2
+Requires-Dist: chapkit>=2.1.0,<3
 Requires-Dist: cryptography>=46.0.7
 Requires-Dist: croniter>=6.2.2
 Requires-Dist: stumpy>=1.14.1

chap_core-2.3.1/chap_core/assessment/causal_plot.py

@@ -0,0 +1,246 @@
+"""Side-by-side and overlaid comparison plots for causal counterfactual analysis."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import altair as alt
+import numpy as np
+import pandas as pd
+
+from chap_core.assessment.backtest_plots.evaluation_plot import EvaluationPlot
+from chap_core.plotting.backtest_plot import clean_time
+
+if TYPE_CHECKING:
+    from chap_core.assessment.backtest_plots import ChartType
+
+_QUANTILES = (0.1, 0.25, 0.5, 0.75, 0.9)
+_ORIGINAL_LABEL = "Original"
+_COUNTERFACTUAL_LABEL = "Counterfactual"
+_OBSERVED_LABEL = "Observed (pre-split)"
+_DEFAULT_X_LABEL = "Time period"
+_DEFAULT_Y_LABEL = "Disease cases"
+
+
+def _mark_type(layer) -> str | None:
+    mark = getattr(layer, "mark", None)
+    return getattr(mark, "type", mark)
+
+
+def _set_axis_titles(chart: ChartType, x_label: str, y_label: str) -> None:
+    """Set axis titles on every layer of a layered chart.
+
+    Vega-Lite ignores `title` in axis config, so `configure_axisX` / `configure_axisY`
+    cannot be used to label the axes. Every layer needs the same explicit title, or
+    Vega-Lite merges the per-layer field names into titles like "q_10, q_25".
+    """
+    for layer in chart.layer:
+        encoding = getattr(layer, "encoding", None)
+        for channel, label in (("x", x_label), ("y", y_label)):
+            channel_def = getattr(encoding, channel, None)
+            if channel_def is not None and channel_def is not alt.Undefined:
+                channel_def.title = label
+
+
+def _chart_for_location(
+    flat_evaluation,
+    location: str,
+    title: str,
+    *,
+    x_label: str,
+    y_label: str,
+    show_confidence_intervals: bool = True,
+) -> ChartType:
+    obs = pd.DataFrame(flat_evaluation.observations)
+    forecasts = pd.DataFrame(flat_evaluation.forecasts)
+    historical = None
+    if flat_evaluation.historical_observations is not None:
+        hist = pd.DataFrame(flat_evaluation.historical_observations)
+        loc_hist = hist[hist["location"] == location]
+        historical = loc_hist if not loc_hist.empty else None
+    chart = (
+        EvaluationPlot()
+        .plot(
+            obs[obs["location"] == location],
+            forecasts[forecasts["location"] == location],
+            historical,
+        )
+        .properties(title=title)
+    )
+    if not show_confidence_intervals:
+        chart.layer = [layer for layer in chart.layer if _mark_type(layer) != "errorband"]
+    _set_axis_titles(chart, x_label, y_label)
+    return chart
+
+
+def plot_counterfactual(
+    eval_original,
+    eval_cf,
+    counterfactual_columns: list[str] | None = None,
+    *,
+    title: str | None = None,
+    x_label: str | None = None,
+    y_label: str | None = None,
+    original_label: str = _ORIGINAL_LABEL,
+    counterfactual_label: str = _COUNTERFACTUAL_LABEL,
+    show_confidence_intervals: bool = True,
+) -> ChartType:
+    """Return a per-location vconcat of side-by-side Altair charts comparing original vs counterfactual."""
+    x_label = x_label if x_label is not None else _DEFAULT_X_LABEL
+    y_label = y_label if y_label is not None else _DEFAULT_Y_LABEL
+    locations = sorted(pd.DataFrame(eval_original.to_flat().observations)["location"].unique())
+    flat_evaluation = eval_original.to_flat()
+    flat_evaluation_cf = eval_cf.to_flat()
+
+    rows = []
+    for loc in locations:
+        orig_chart = _chart_for_location(
+            flat_evaluation,
+            loc,
+            original_label,
+            x_label=x_label,
+            y_label=y_label,
+            show_confidence_intervals=show_confidence_intervals,
+        )
+        cf_chart = _chart_for_location(
+            flat_evaluation_cf,
+            loc,
+            counterfactual_label,
+            x_label=x_label,
+            y_label=y_label,
+            show_confidence_intervals=show_confidence_intervals,
+        )
+        rows.append(alt.hconcat(orig_chart, cf_chart).resolve_scale(y="shared"))
+
+    return alt.vconcat(*rows).properties(
+        title=_compose_title(title, counterfactual_columns, original_label, counterfactual_label)
+    )
+
+
+def _compose_title(
+    title: str | None,
+    counterfactual_columns: list[str] | None,
+    original_label: str,
+    counterfactual_label: str,
+) -> str:
+    if title is not None:
+        return title
+    subtitle = f" ({', '.join(counterfactual_columns)})" if counterfactual_columns else ""
+    return f"Causal Analysis: {original_label} vs {counterfactual_label}{subtitle}"
+
+
+def _location_quantiles(forecasts: pd.DataFrame, location: str, series: str) -> pd.DataFrame:
+    """Per-time-period forecast quantiles for one location, tagged with a series label."""
+    subset = forecasts[forecasts["location"] == location]
+    grouped = subset.groupby("time_period")["forecast"].quantile(np.array(_QUANTILES)).unstack()
+    grouped.columns = [f"q_{int(q * 100)}" for q in _QUANTILES]
+    grouped = grouped.reset_index()
+    grouped["time_period"] = grouped["time_period"].astype(str).apply(clean_time)
+    grouped["series"] = series
+    return grouped
+
+
+def _location_observed(flat_evaluation, location: str) -> pd.DataFrame | None:
+    """Observed disease_cases for one location, restricted to the pre-split historical window."""
+    if flat_evaluation.historical_observations is None:
+        return None
+    df = pd.DataFrame(flat_evaluation.historical_observations)
+    df = df[df["location"] == location]
+    if df.empty:
+        return None
+    df = df.copy()
+    df["time_period"] = df["time_period"].astype(str).apply(clean_time)
+    df["series"] = _OBSERVED_LABEL
+    return df
+
+
+def _x(x_label: str) -> alt.X:
+    return alt.X("time_period:T", title=x_label)
+
+
+def _y(field: str, y_label: str) -> alt.Y:
+    return alt.Y(f"{field}:Q", scale=alt.Scale(zero=False), title=y_label)
+
+
+def _color(color_scale: alt.Scale) -> alt.Color:
+    return alt.Color("series:N", scale=color_scale, legend=alt.Legend(title=None))
+
+
+def _overlay_for_location(
+    quantiles: pd.DataFrame,
+    observed: pd.DataFrame | None,
+    location: str,
+    x_label: str,
+    y_label: str,
+    color_scale: alt.Scale,
+    show_confidence_intervals: bool = True,
+) -> ChartType:
+    median_line = (
+        alt.Chart(quantiles).mark_line().encode(x=_x(x_label), y=_y("q_50", y_label), color=_color(color_scale))
+    )
+    layers = []
+    if show_confidence_intervals:
+        layers.append(
+            alt.Chart(quantiles)
+            .mark_errorband(opacity=0.15)
+            .encode(x=_x(x_label), y=_y("q_10", y_label), y2="q_90:Q", color=_color(color_scale))
+        )
+        layers.append(
+            alt.Chart(quantiles)
+            .mark_errorband(opacity=0.3)
+            .encode(x=_x(x_label), y=_y("q_25", y_label), y2="q_75:Q", color=_color(color_scale))
+        )
+    layers.append(median_line)
+    if observed is not None and not observed.empty:
+        layers.append(
+            alt.Chart(observed)
+            .mark_line(strokeDash=[4, 2])
+            .encode(x=_x(x_label), y=_y("disease_cases", y_label), color=_color(color_scale))
+        )
+    return alt.layer(*layers).properties(title=location)
+
+
+def plot_counterfactual_overlayed(
+    eval_original,
+    eval_cf,
+    counterfactual_columns: list[str] | None = None,
+    *,
+    title: str | None = None,
+    x_label: str | None = None,
+    y_label: str | None = None,
+    original_label: str = _ORIGINAL_LABEL,
+    counterfactual_label: str = _COUNTERFACTUAL_LABEL,
+    show_confidence_intervals: bool = True,
+) -> ChartType:
+    """Return a per-location vconcat of single overlaid charts: original vs counterfactual forecasts
+    on shared axes, with the observed line drawn only up to the split point."""
+    x_label = x_label if x_label is not None else _DEFAULT_X_LABEL
+    y_label = y_label if y_label is not None else _DEFAULT_Y_LABEL
+    flat_original = eval_original.to_flat()
+    flat_cf = eval_cf.to_flat()
+    original_forecasts = pd.DataFrame(flat_original.forecasts)
+    cf_forecasts = pd.DataFrame(flat_cf.forecasts)
+    locations = sorted(original_forecasts["location"].unique())
+
+    color_scale = alt.Scale(
+        domain=[original_label, counterfactual_label, _OBSERVED_LABEL],
+        range=["#1f77b4", "#d62728", "#333333"],
+    )
+
+    rows = []
+    for loc in locations:
+        quantiles = pd.concat(
+            [
+                _location_quantiles(original_forecasts, loc, original_label),
+                _location_quantiles(cf_forecasts, loc, counterfactual_label),
+            ],
+            ignore_index=True,
+        )
+        observed = _location_observed(flat_original, loc)
+        rows.append(
+            _overlay_for_location(quantiles, observed, loc, x_label, y_label, color_scale, show_confidence_intervals)
+        )
+
+    return alt.vconcat(*rows).properties(
+        title=_compose_title(title, counterfactual_columns, original_label, counterfactual_label)
+    )

{chap_core-2.2.0 → chap_core-2.3.1}/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
@@ -49,6 +46,15 @@ except ImportError:
     CHAP_VERSION = "unknown"
 
 
+def _recorded_version(version: str | None) -> str | None:
+    """The version to persist: a real release version, or None for the "unknown" a dev checkout reports."""
+    return None if version in (None, "unknown") else version
+
+
+# Version stored on every backtest this process produces.
+RECORDED_CHAP_VERSION = _recorded_version(CHAP_VERSION)
+
+
 def _flat_data_to_xarray(flat_data: "FlatEvaluationData", model_metadata: dict) -> xr.Dataset:
     """
     Convert FlatEvaluationData to xarray.Dataset.
@@ -284,8 +290,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,11 +317,25 @@ 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()
-            | {"model_db_id": configured_model.id, "model_template_version": configured_model.model_template.version}
+            **info.model_dump(exclude=set(BacktestParams.model_fields))
+            | {
+                "model_db_id": configured_model.id,
+                "model_template_version": configured_model.model_template.version,
+                "chap_version": RECORDED_CHAP_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()
@@ -393,7 +413,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 +709,15 @@ class Evaluation(EvaluationBase):
             split_periods=split_periods,
             forecasts=[],
             dataset_id=0,
-            future_weather_provider=str(ds.attrs["future_weather_provider"]),
+            # The version of the writer, not of the process importing the file.
+            chap_version=_recorded_version(ds.attrs.get("chap_version")),
+            # 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.1}/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.1}/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.3.1/chap_core/assessment/metrics/outbreak_detection.py

@@ -0,0 +1,201 @@
+"""
+Outbreak detection metrics: sensitivity, specificity, and accuracy.
+
+An "outbreak" is observed cases exceeding the seasonal baseline (mean + 2*std)
+for a given location and season bucket — calendar month for monthly data,
+epi-week for weekly. An "alert" is raised when more than
+:data:`ALERT_SAMPLE_FRACTION` of the forecast samples exceed that threshold.
+
+All three metrics score the same joined frame, built once by
+:func:`outbreak_and_alert`. They differ only in which rows they keep and what
+they compare, so the threshold and alert rules live in one place.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+from chap_core.assessment.metrics import metric
+from chap_core.assessment.metrics.base import (
+    AggregationOp,
+    Metric,
+    MetricSpec,
+    OptimizationDirection,
+)
+
+# The outbreak metrics score forecasts against seasonal thresholds, computed by the
+# threshold strategy module.
+from chap_core.assessment.thresholds.seasonal import compute_seasonal_thresholds
+from chap_core.time_period.vectorized import season_column
+
+if TYPE_CHECKING:
+    import pandera.pandas as pa
+
+    from chap_core.assessment.flat_representations import FlatObserved
+
+#: Fraction of forecast samples that must exceed the threshold for an alert to be raised.
+ALERT_SAMPLE_FRACTION = 0.5
+
+_OUTBREAK_COLUMNS = ["location", "time_period", "horizon_distance", "outbreak", "alert"]
+_METRIC_DIMENSIONS = ["location", "time_period", "horizon_distance"]
+
+
+def _season_of(thresholds: pd.DataFrame) -> str:
+    """The season bucket a threshold frame is keyed on."""
+    return "week" if "week" in thresholds.columns else "month"
+
+
+def has_season_buckets(observations: pd.DataFrame) -> bool:
+    """Whether the observations' time periods bucket into calendar months or epi-weeks."""
+    if observations.empty:
+        return False
+    try:
+        season_column(observations["time_period"])
+    except (ValueError, KeyError, TypeError):
+        return False
+    return True
+
+
+def outbreak_and_alert(
+    historical_observations: pd.DataFrame | None,
+    observations: pd.DataFrame,
+    forecasts: pd.DataFrame,
+) -> pd.DataFrame:
+    """Label every scored cell as outbreak and alert against the seasonal threshold.
+
+    Args:
+        historical_observations: Observations the threshold is computed from, with
+            columns ``[location, time_period, disease_cases]``. ``None`` yields an
+            empty frame — the metrics are not applicable without it.
+        observations: Observed cases to label, same columns.
+        forecasts: Forecast samples, with columns
+            ``[location, time_period, horizon_distance, sample, forecast]``.
+
+    Returns:
+        One row per ``(location, time_period, horizon_distance)`` that has both a
+        computable threshold and a forecast, with columns
+        ``[location, time_period, horizon_distance, outbreak, alert]``. ``outbreak``
+        is 1.0 where observed cases exceed the threshold; ``alert`` is 1.0 where more
+        than :data:`ALERT_SAMPLE_FRACTION` of the samples exceed it. Cells whose
+        threshold cannot be computed (a single historical value gives an undefined
+        standard deviation) are dropped.
+    """
+    empty = pd.DataFrame(columns=_OUTBREAK_COLUMNS)
+    if historical_observations is None or historical_observations.empty:
+        return empty
+    if observations.empty or forecasts.empty:
+        return empty
+
+    thresholds = compute_seasonal_thresholds(historical_observations)
+    if thresholds.empty:
+        return empty
+    season = _season_of(thresholds)
+
+    obs = observations[["location", "time_period", "disease_cases"]].copy()
+    obs_season, obs_buckets = season_column(obs["time_period"])
+    if obs_season != season:
+        # Historical and scored periods are at different frequencies; nothing to join on.
+        return empty
+    obs[season] = obs_buckets
+    obs = obs.merge(thresholds, on=["location", season], how="left").dropna(subset=["threshold"])
+    if obs.empty:
+        return empty
+    obs["outbreak"] = (obs["disease_cases"] > obs["threshold"]).astype(float)
+
+    fc = forecasts.copy()
+    fc[season] = season_column(fc["time_period"])[1]
+    fc = fc.merge(thresholds, on=["location", season], how="left")
+    fc["exceeds"] = (fc["forecast"] > fc["threshold"]).astype(float)
+    alert = fc.groupby(_METRIC_DIMENSIONS, as_index=False)["exceeds"].mean()
+    alert["alert"] = (alert["exceeds"] > ALERT_SAMPLE_FRACTION).astype(float)
+
+    merged = obs[["location", "time_period", "outbreak"]].merge(
+        alert[[*_METRIC_DIMENSIONS, "alert"]],
+        on=["location", "time_period"],
+        how="inner",
+    )
+    return pd.DataFrame(merged[_OUTBREAK_COLUMNS])
+
+
+def _as_metric(rows: pd.DataFrame, values: pd.Series) -> pd.DataFrame:
+    """Reshape a slice of the outbreak frame into the metric output contract."""
+    result = rows[_METRIC_DIMENSIONS].copy()
+    result["metric"] = values
+    return result
+
+
+class _OutbreakMetric(Metric):
+    """Shared applicability rule for metrics scored against a seasonal threshold."""
+
+    def is_applicable(self, observations: pa.typing.DataFrame[FlatObserved]) -> bool:
+        return self.historical_observations is not None and has_season_buckets(observations)
+
+    def _frame(self, observations: pd.DataFrame, forecasts: pd.DataFrame) -> pd.DataFrame:
+        return outbreak_and_alert(self.historical_observations, observations, forecasts)
+
+
+@metric()
+class SensitivityMetric(_OutbreakMetric):
+    """Sensitivity (true positive rate) for outbreak detection.
+
+    Measures the proportion of actual outbreaks that were correctly
+    predicted (alerted) by the forecast.
+    """
+
+    spec = MetricSpec(
+        metric_id="sensitivity",
+        metric_name="Sensitivity",
+        aggregation_op=AggregationOp.MEAN,
+        description="True positive rate for outbreak detection alerts",
+        optimization_direction=OptimizationDirection.MAXIMIZE,
+    )
+
+    def compute_detailed(self, observations: pd.DataFrame, forecasts: pd.DataFrame) -> pd.DataFrame:
+        frame = self._frame(observations, forecasts)
+        outbreaks = frame[frame["outbreak"] == 1.0]
+        return _as_metric(outbreaks, outbreaks["alert"])
+
+
+@metric()
+class SpecificityMetric(_OutbreakMetric):
+    """Specificity (true negative rate) for outbreak detection.
+
+    Measures the proportion of non-outbreak periods that were correctly
+    not alerted by the forecast.
+    """
+
+    spec = MetricSpec(
+        metric_id="specificity",
+        metric_name="Specificity",
+        aggregation_op=AggregationOp.MEAN,
+        description="True negative rate for outbreak detection alerts",
+        optimization_direction=OptimizationDirection.MAXIMIZE,
+    )
+
+    def compute_detailed(self, observations: pd.DataFrame, forecasts: pd.DataFrame) -> pd.DataFrame:
+        frame = self._frame(observations, forecasts)
+        quiet = frame[frame["outbreak"] == 0.0]
+        return _as_metric(quiet, 1.0 - quiet["alert"])
+
+
+@metric()
+class OutbreakAccuracyMetric(_OutbreakMetric):
+    """Accuracy for outbreak detection.
+
+    Measures the proportion of all periods where the alert status
+    correctly matches the outbreak status: (TP + TN) / (TP + TN + FP + FN).
+    """
+
+    spec = MetricSpec(
+        metric_id="outbreak_accuracy",
+        metric_name="Outbreak Accuracy",
+        aggregation_op=AggregationOp.MEAN,
+        description="Proportion of correctly classified outbreak/non-outbreak periods",
+        optimization_direction=OptimizationDirection.MAXIMIZE,
+    )
+
+    def compute_detailed(self, observations: pd.DataFrame, forecasts: pd.DataFrame) -> pd.DataFrame:
+        frame = self._frame(observations, forecasts)
+        return _as_metric(frame, (frame["alert"] == frame["outbreak"]).astype(float))