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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: chap_core
-Version: 2.0.0
+Version: 2.2.0
 Summary: Climate Health Analysis Platform (CHAP)
 Keywords: chap_core
 Author: Chap Team
@@ -32,7 +32,8 @@ Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: requests>=2.34.2
 Requires-Dist: urllib3>=2.7.0
 Requires-Dist: rq>=2.9.0
-Requires-Dist: scikit-learn>=1.8.0
+Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: statsmodels>=0.14.6
 Requires-Dist: topojson>=1.10
 Requires-Dist: unidecode>=1.4.0
 Requires-Dist: uvicorn>=0.48.0
@@ -45,21 +46,19 @@ Requires-Dist: altair>=5.5.0
 Requires-Dist: virtualenv>=20.34.0
 Requires-Dist: geojson-pydantic>=2.1.1
 Requires-Dist: pandera>=0.31.1
-Requires-Dist: vegafusion>=2.0.3
 Requires-Dist: vl-convert-python>=1.9.0.post1
-Requires-Dist: pyarrow>=23.0.1
-Requires-Dist: numpy>=2.1.3
+Requires-Dist: numpy>=2.3.2
 Requires-Dist: gunicorn>=25.3.0
-Requires-Dist: optuna>=4.8.0
+Requires-Dist: optuna>=4.9.0
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: alembic>=1.18.4
-Requires-Dist: chapkit>=0.26.0
+Requires-Dist: chapkit>=1.0.0,<2
 Requires-Dist: cryptography>=46.0.7
 Requires-Dist: croniter>=6.2.2
 Requires-Dist: stumpy>=1.14.1
 Requires-Dist: pyts>=0.13.0
 Requires-Dist: fastdtw>=0.3.4
-Requires-Python: >=3.13, <3.14
+Requires-Python: >=3.13, <3.15
 Project-URL: Homepage, https://github.com/dhis2/chap-core
 Description-Content-Type: text/markdown
 

{chap_core-2.0.0 → chap_core-2.2.0}/chap_core/api_types.py

@@ -1,4 +1,5 @@
 from enum import StrEnum
+from pathlib import Path
 from typing import Any, Literal
 
 import numpy as np
@@ -16,8 +17,9 @@ from geojson_pydantic import (
     Point,
     Polygon,
 )
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
 
+from chap_core.assessment.weather_providers import DEFAULT_WEATHER_PROVIDER_ID, resolve_weather_provider
 from chap_core.database.base_tables import DBModel
 
 
@@ -124,6 +126,18 @@ class BacktestParams(DBModel):
         gt=0,
         description="Number of times the model is retrained, evenly spaced across the splits. 1 means train once.",
     )
+    future_weather_provider: str = Field(
+        default=DEFAULT_WEATHER_PROVIDER_ID,
+        description="Id of the registered future-weather provider supplying climate covariates for each "
+        "forecast window. Use the same provider here and on the prediction so backtest scores reflect "
+        "what the model will see in production. See GET /v1/analytics/weather-providers.",
+    )
+
+    @field_validator("future_weather_provider")
+    @classmethod
+    def _check_weather_provider(cls, value: str) -> str:
+        resolve_weather_provider(value)
+        return value
 
     @model_validator(mode="after")
     def _check_n_retrain(self) -> "BacktestParams":
@@ -209,11 +223,24 @@ class EstimatorOptions(BaseModel):
         default=EstimatorMode.NORMAL,
         description="Estimator mode: 'normal' = normal run, 'hpo' = hyperparameter optimization, 'ensemble' = ensemble learning.",
     )
+    search_space: Path | None = Field(
+        default=None,
+        description="YAML defining the HPO search space. If omitted, hpo_search_space from model's MLProject is used.",
+    )
     metric: str | None = Field(
         default=None,
         description="Metric used for HPO or ensemble. Default will be used if none provided. Ignored in normal mode.",
     )
     searcher: SearcherType | None = Field(
         default=None,
-        description="Searcher used for HPO. If not provided, a default RandomSearcher will be used. Ignored in normal and ensemble modes.",
+        description="Searcher used for HPO. If not provided, a default TPESearcher will be used. Ignored in normal and ensemble modes.",
+    )
+    max_trials: int | None = Field(
+        default=None,
+        gt=0,
+        description="Maximum HPO trials. If omitted, grid search is exhaustive while random/TPE use the default HPO trial count.",
+    )
+    seed: int | None = Field(
+        default=None,
+        description="Random seed used by stochastic search strategies.",
     )

{chap_core-2.0.0 → chap_core-2.2.0}/chap_core/assessment/backtest_plots/__init__.py

@@ -291,7 +291,6 @@ def _discover_plots():
     from chap_core.assessment.backtest_plots import (
         evaluation_plot,
         horizon_location_grid,
-        metrics_dashboard,
         predicted_vs_actual_linear_plot,
         predicted_vs_actual_plot,
         sample_bias_plot,

chap_core-2.2.0/chap_core/assessment/backtest_plots/db_dimensions.py

@@ -0,0 +1,167 @@
+"""Database-backed facet dimensions for backtest plots.
+
+These dimensions know how to (a) enumerate their available coordinate values with
+cheap database queries and (b) translate a requested coordinate into SQL filters,
+so a single subplot can be served by loading only the matching forecast rows
+instead of flattening the entire backtest in memory.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from sqlalchemy import false, tuple_
+from sqlmodel import select
+
+from chap_core.assessment.backtest_plots import FacetDimension
+from chap_core.assessment.flat_representations import (
+    FlatForecasts,
+    FlatObserved,
+    convert_backtest_observations_to_flat_observations,
+    convert_backtest_to_flat_forecasts,
+    horizon_diff,
+)
+from chap_core.database.dataset_manager import DataSetManager
+from chap_core.database.tables import BacktestForecast
+from chap_core.plotting.backtest_plot import clean_time
+from chap_core.time_period import TimePeriod
+
+if TYPE_CHECKING:
+    from sqlalchemy.sql.elements import ColumnElement
+    from sqlmodel import Session
+
+    from chap_core.assessment.evaluation import FlatEvaluationData
+    from chap_core.database.tables import Backtest
+
+
+class DBFacetDimension(FacetDimension):
+    """A facet dimension whose coordinates and filters can be served from the database."""
+
+    def distinct_values(self, session: Session, backtest: Backtest) -> list[Any]:
+        """Coordinate values available for this dimension, in display form."""
+        raise NotImplementedError
+
+    def forecast_filters(self, value: Any, session: Session, backtest: Backtest) -> list[ColumnElement]:
+        """SQL clauses narrowing `BacktestForecast` to the rows for `value`."""
+        return []
+
+
+class LocationDimension(DBFacetDimension):
+    """Facet by org unit (`location`), matching `BacktestForecast.org_unit` directly."""
+
+    def distinct_values(self, session: Session, backtest: Backtest) -> list[Any]:
+        if backtest.org_units:
+            return sorted(backtest.org_units)
+        rows = session.exec(
+            select(BacktestForecast.org_unit).where(BacktestForecast.backtest_id == backtest.id).distinct()
+        ).all()
+        return sorted(rows)
+
+    def forecast_filters(self, value: Any, session: Session, backtest: Backtest) -> list[ColumnElement]:
+        return [BacktestForecast.org_unit == value]
+
+
+def _split_display(last_seen_period: str) -> str:
+    """The split-period coordinate a forecast with this `last_seen_period` falls under.
+
+    Mirrors the plot's `clean_time(time_period - horizon * delta)`, which reduces to
+    `clean_time(last_seen_period - delta)`.
+    """
+    tp = TimePeriod.parse(last_seen_period)
+    return str(clean_time((tp - tp.time_delta).to_string()))
+
+
+def _distinct_last_seen(session: Session, backtest: Backtest) -> list[str]:
+    return list(
+        session.exec(
+            select(BacktestForecast.last_seen_period).where(BacktestForecast.backtest_id == backtest.id).distinct()
+        ).all()
+    )
+
+
+class SplitPeriodDimension(DBFacetDimension):
+    """Facet by split period, derived from `BacktestForecast.last_seen_period`."""
+
+    def distinct_values(self, session: Session, backtest: Backtest) -> list[Any]:
+        return sorted({_split_display(ls) for ls in _distinct_last_seen(session, backtest)})
+
+    def forecast_filters(self, value: Any, session: Session, backtest: Backtest) -> list[ColumnElement]:
+        matching = [ls for ls in _distinct_last_seen(session, backtest) if _split_display(ls) == value]
+        if not matching:
+            return [false()]
+        return [BacktestForecast.last_seen_period.in_(matching)]  # type: ignore[attr-defined]
+
+
+def _distinct_period_pairs(session: Session, backtest: Backtest) -> list[tuple[str, str]]:
+    rows = session.exec(
+        select(BacktestForecast.period, BacktestForecast.last_seen_period)
+        .where(BacktestForecast.backtest_id == backtest.id)
+        .distinct()
+    ).all()
+    return [(str(period), str(last_seen)) for period, last_seen in rows]
+
+
+class HorizonDistanceDimension(DBFacetDimension):
+    """Facet by 1-based horizon distance.
+
+    Coordinates run `1..max_horizon_distance` when the backtest records it, falling
+    back to deriving distinct horizons from the forecasts for legacy rows.
+    """
+
+    def distinct_values(self, session: Session, backtest: Backtest) -> list[Any]:
+        if backtest.max_horizon_distance is not None:
+            return list(range(1, backtest.max_horizon_distance + 1))
+        horizons = {horizon_diff(period, last_seen) for period, last_seen in _distinct_period_pairs(session, backtest)}
+        return sorted(horizons)
+
+    def forecast_filters(self, value: Any, session: Session, backtest: Backtest) -> list[ColumnElement]:
+        pairs = [
+            (period, last_seen)
+            for period, last_seen in _distinct_period_pairs(session, backtest)
+            if horizon_diff(period, last_seen) == int(value)
+        ]
+        if not pairs:
+            return [false()]
+        return [tuple_(BacktestForecast.period, BacktestForecast.last_seen_period).in_(pairs)]  # type: ignore[arg-type]
+
+
+def load_filtered_flat_data(
+    session: Session,
+    backtest: Backtest,
+    coords: dict[str, Any],
+    dimensions: list[FacetDimension],
+) -> FlatEvaluationData:
+    """Load only the forecast/observation rows matching `coords`, as flat frames.
+
+    Coordinates whose dimension is a `DBFacetDimension` are pushed down to SQL; any
+    other coordinate is ignored here and left to the plot's in-memory filter.
+    """
+    from chap_core.assessment.evaluation import FlatEvaluationData
+
+    dim_by_name = {d.clean_name: d for d in dimensions if isinstance(d, DBFacetDimension)}
+
+    forecast_clauses: list[Any] = [BacktestForecast.backtest_id == backtest.id]
+    for name, value in coords.items():
+        dim = dim_by_name.get(name)
+        if dim is None:
+            continue
+        forecast_clauses += dim.forecast_filters(value, session, backtest)
+
+    forecasts = session.exec(select(BacktestForecast).where(*forecast_clauses)).all()
+
+    # Observations narrow only by org unit (any location coordinate); other dimensions
+    # filter the forecasts and rely on the plot's in-memory filter for observations.
+    org_units = [value for name, value in coords.items() if isinstance(dim_by_name.get(name), LocationDimension)]
+    observations = DataSetManager(session).observations(
+        backtest.dataset_id,
+        org_units=org_units or None,
+        feature_names=["disease_cases"],
+    )
+
+    forecasts_df = convert_backtest_to_flat_forecasts(list(forecasts))
+    observations_df = convert_backtest_observations_to_flat_observations(list(observations))
+
+    return FlatEvaluationData(
+        forecasts=FlatForecasts.validate(forecasts_df),
+        observations=FlatObserved.validate(observations_df),
+    )

{chap_core-2.0.0 → chap_core-2.2.0}/chap_core/assessment/backtest_plots/evaluation_plot.py

@@ -10,6 +10,7 @@ import numpy as np
 import pandas as pd
 
 from chap_core.assessment.backtest_plots import ChartType, FacetDimension, FacetedBacktestPlot, backtest_plot
+from chap_core.assessment.backtest_plots.db_dimensions import LocationDimension, SplitPeriodDimension
 from chap_core.plotting.backtest_plot import clean_time
 from chap_core.time_period import TimePeriod
 
@@ -57,8 +58,8 @@ class EvaluationPlot(FacetedBacktestPlot):
     """Shows forecasts with uncertainty bands and observed values with historical context."""
 
     facet_dimensions: list[FacetDimension] = [
-        FacetDimension(field_name="split_period:O", display_name="Split Period"),
-        FacetDimension(field_name="location:N", display_name="Location"),
+        SplitPeriodDimension(field_name="split_period:O", display_name="Split Period"),
+        LocationDimension(field_name="location:N", display_name="Location"),
     ]
 
     def _preprocess(

{chap_core-2.0.0 → chap_core-2.2.0}/chap_core/assessment/backtest_plots/horizon_location_grid.py

@@ -9,7 +9,8 @@ line charts stacked below.
 import altair as alt
 import pandas as pd
 
-from chap_core.assessment.backtest_plots import BacktestPlotBase, ChartType, backtest_plot
+from chap_core.assessment.backtest_plots import ChartType, FacetDimension, FacetedBacktestPlot, backtest_plot
+from chap_core.assessment.backtest_plots.db_dimensions import HorizonDistanceDimension, LocationDimension
 from chap_core.assessment.backtest_plots.evaluation_plot import _compute_quantiles_from_forecasts
 from chap_core.assessment.flat_representations import FlatForecasts, FlatObserved
 from chap_core.assessment.metrics.crps import CRPSLog1pMetric, CRPSMetric
@@ -22,13 +23,13 @@ CELL_HEIGHT = 150
 METRIC_HEIGHT = 60
 
 
-def _empty_placeholder(width: int, height: int, title: str = "") -> ChartType:
-    """Return an empty chart placeholder that won't trip vegafusion's type checks."""
+def _empty_placeholder(width: int, height: int) -> ChartType:
+    """Return an empty chart placeholder that won't trip Altair/Vega type checks."""
     return (  # type: ignore[no-any-return]
         alt.Chart(pd.DataFrame({"x": [0]}))
         .mark_point(opacity=0)
         .encode(x=alt.value(0), y=alt.value(0))
-        .properties(width=width, height=height, title=title)
+        .properties(width=width, height=height)
     )
 
 
@@ -48,7 +49,7 @@ def _build_forecast_cell(
     obs = obs[obs["time_period"].isin(fq["time_period"])]
 
     if fq.empty:
-        return _empty_placeholder(CELL_WIDTH, CELL_HEIGHT, f"{location} | horizon {horizon}")
+        return _empty_placeholder(CELL_WIDTH, CELL_HEIGHT)
 
     base_forecast = alt.Chart(fq)
 
@@ -70,7 +71,7 @@ def _build_forecast_cell(
     layers = error_10_90 + error_25_75 + median_line
 
     # Only add observations layer if there is data; an empty DataFrame with
-    # object-typed columns causes vegafusion to fail on temporal encoding.
+    # object-typed columns causes Altair/Vega to fail on temporal encoding.
     if not obs.empty:
         obs_line = (
             alt.Chart(obs)
@@ -82,9 +83,7 @@ def _build_forecast_cell(
         )
         layers = layers + obs_line
 
-    return layers.properties(  # type: ignore[no-any-return]
-        width=CELL_WIDTH, height=CELL_HEIGHT, title=f"{location} | horizon {horizon}"
-    )
+    return layers.properties(width=CELL_WIDTH, height=CELL_HEIGHT)  # type: ignore[no-any-return]
 
 
 def _build_metric_chart(
@@ -152,68 +151,136 @@ def _build_summary_table(
     )
 
 
+def _metric_instances(historical_observations: pd.DataFrame | None) -> list:
+    """The metrics shown in each grid cell, in display order."""
+    return [
+        CRPSMetric(historical_observations=historical_observations),
+        CRPSLog1pMetric(historical_observations=historical_observations),
+        WinklerScore10_90Metric(historical_observations=historical_observations),
+        WinklerScore10_90Log1pMetric(historical_observations=historical_observations),
+        OutbreakAccuracyMetric(historical_observations=historical_observations),
+    ]
+
+
+def _metric_dfs_from_preprocessed(df: pd.DataFrame) -> list[tuple[str, pd.DataFrame]]:
+    """Recover the per-metric frames from the packed preprocessed frame, in order."""
+    metric_rows = df[df["role"] == "metric"]
+    return [(str(name), group) for name, group in metric_rows.groupby("metric_name", sort=False)]
+
+
 @backtest_plot(
     plot_id="horizon_location_grid",
     name="Forecast Grid (Locations x Horizons)",
     description="Grid of forecast intervals and metrics across locations and forecast horizons.",
     needs_historical=True,
 )
-class HorizonLocationGridPlot(BacktestPlotBase):
-    """Grid plot with locations as rows and forecast horizons as columns."""
+class HorizonLocationGridPlot(FacetedBacktestPlot):
+    """Grid plot with locations as rows and forecast horizons as columns.
+
+    Each cell is a composite (forecast band + observed + per-metric line charts),
+    so the all-cells view (`get_full_plot`) keeps the hand-built grid, while
+    `facet_coords` / `get_subplot` expose a single location x horizon cell for the
+    database-backed faceting workflow.
+    """
 
-    def plot(
+    facet_dimensions: list[FacetDimension] = [
+        HorizonDistanceDimension(field_name="horizon_distance:O", display_name="Horizon Distance"),
+        LocationDimension(field_name="location:N", display_name="Location"),
+    ]
+
+    def _preprocess(
         self,
         observations: pd.DataFrame,
         forecasts: pd.DataFrame,
         historical_observations: pd.DataFrame | None = None,
-    ) -> ChartType:
-        flat_obs = FlatObserved(observations)
-        flat_fc = FlatForecasts(forecasts)
+    ) -> pd.DataFrame:
+        """Pack forecast quantiles, observed values and metric series into one frame.
+
+        Each row carries `location` + `horizon_distance` (observations replicated
+        across horizons) so the generic coordinate filter can slice to one cell, plus
+        a `role` discriminator the cell renderer splits back out.
+        """
+        # No forecasts for this coordinate (e.g. a location x horizon cell with no
+        # data): skip metric computation and let the cell render as a placeholder.
+        if forecasts.empty:
+            return pd.DataFrame(columns=["location", "time_period", "horizon_distance", "role"])
+
+        flat_obs = FlatObserved.validate(observations)
+        flat_fc = FlatForecasts.validate(forecasts)
+        horizons = sorted(forecasts["horizon_distance"].unique())
 
-        # Compute quantiles for forecast cells
         forecast_quantiles = _compute_quantiles_from_forecasts(forecasts)
         forecast_quantiles["time_period"] = forecast_quantiles["time_period"].apply(clean_time)
+        forecast_quantiles["role"] = "forecast"
 
         obs_df = observations.copy()
         obs_df["time_period"] = obs_df["time_period"].apply(clean_time)
+        # Observations have no horizon; replicate across horizons so the cell filter keeps them.
+        obs_df = obs_df.merge(pd.DataFrame({"horizon_distance": horizons}), how="cross")
+        obs_df["role"] = "observed"
 
-        locations = sorted(forecasts["location"].unique())
-        horizons = sorted(forecasts["horizon_distance"].unique())
-
-        # Compute metrics
-        metric_instances = [
-            CRPSMetric(historical_observations=historical_observations),
-            CRPSLog1pMetric(historical_observations=historical_observations),
-            WinklerScore10_90Metric(historical_observations=historical_observations),
-            WinklerScore10_90Log1pMetric(historical_observations=historical_observations),
-            OutbreakAccuracyMetric(historical_observations=historical_observations),
-        ]
-
-        metric_dfs: list[tuple[str, pd.DataFrame]] = []
-        for m in metric_instances:
+        frames: list[pd.DataFrame] = [forecast_quantiles, obs_df]
+        for m in _metric_instances(historical_observations):
             if not m.is_applicable(flat_obs):
                 continue
             detailed = m.get_detailed_metric(flat_obs, flat_fc)
             detailed["time_period"] = detailed["time_period"].apply(clean_time)
-            metric_dfs.append((m.get_name(), detailed))
+            detailed["role"] = "metric"
+            detailed["metric_name"] = m.get_name()
+            frames.append(detailed)
+
+        return pd.concat(frames, ignore_index=True)
+
+    def _plot(self, df: pd.DataFrame) -> ChartType:
+        """Render one location x horizon cell from the packed frame."""
+        if df.empty:
+            return _empty_placeholder(CELL_WIDTH, CELL_HEIGHT)
+
+        forecast_rows = df[df["role"] == "forecast"]
+        observed_rows = df[df["role"] == "observed"]
+        key_src = forecast_rows if not forecast_rows.empty else df
+        location = key_src["location"].iloc[0]
+        horizon = int(key_src["horizon_distance"].iloc[0])
+
+        cell_parts: list[ChartType] = [_build_forecast_cell(forecast_rows, observed_rows, location, horizon)]
+        for metric_name, mdf in _metric_dfs_from_preprocessed(df):
+            cell_parts.append(_build_metric_chart(mdf, location, horizon, metric_name))
+
+        return alt.vconcat(*cell_parts).properties(spacing=2)  # type: ignore[no-any-return]
+
+    def get_full_plot(
+        self,
+        observations: pd.DataFrame,
+        forecasts: pd.DataFrame,
+        historical_observations: pd.DataFrame | None = None,
+    ) -> ChartType:
+        """The full grid: composite cells (locations as rows, horizons as columns) plus a summary table.
+
+        Overrides the base native-faceting implementation, which cannot tile the
+        composite (vconcat) cells this plot renders.
+        """
+        df = self._preprocess(observations, forecasts, historical_observations)
+        locations = sorted(forecasts["location"].unique())
+        horizons = sorted(forecasts["horizon_distance"].unique())
 
-        # Build grid: rows = locations, columns = horizons
         location_rows: list[ChartType] = []
         for loc in locations:
-            horizon_cells = []
-            for hz in horizons:
-                cell_parts: list[ChartType] = [_build_forecast_cell(forecast_quantiles, obs_df, loc, hz)]
-                for metric_name, mdf in metric_dfs:
-                    cell_parts.append(_build_metric_chart(mdf, loc, hz, metric_name))
-                horizon_cells.append(alt.vconcat(*cell_parts).properties(spacing=2))
+            # The grid layout is the only thing identifying a cell, so label each
+            # one here; the single-cell subplot view leaves identification to the
+            # frontend's facet selection.
+            horizon_cells = [
+                self._plot(df[(df["location"] == loc) & (df["horizon_distance"] == hz)]).properties(
+                    title=f"{loc} | horizon {hz}"
+                )
+                for hz in horizons
+            ]
             location_rows.append(alt.hconcat(*horizon_cells).properties(spacing=10))
 
-        # Aggregated summary tables
+        metric_dfs = _metric_dfs_from_preprocessed(df)
         if metric_dfs:
-            summary = _build_summary_table(metric_dfs, horizons)
-            location_rows.append(summary)
+            location_rows.append(_build_summary_table(metric_dfs, horizons))
 
-        return alt.vconcat(*location_rows).properties(  # type: ignore[return-value]
+        return alt.vconcat(*location_rows).properties(  # type: ignore[no-any-return]
             spacing=15,
             title="Forecast Grid: Locations x Horizons",
         )

{chap_core-2.0.0 → chap_core-2.2.0}/chap_core/assessment/backtest_plots/predicted_vs_actual_linear_plot.py

@@ -8,10 +8,10 @@ over- and under-prediction at high case counts immediately visible.
 
 import pandas as pd
 
-from chap_core.assessment.backtest_plots import BacktestPlotBase, ChartType, backtest_plot
+from chap_core.assessment.backtest_plots import ChartType, backtest_plot
 from chap_core.assessment.backtest_plots.predicted_vs_actual_plot import (
+    PredictedVsActualPlot,
     build_predicted_vs_actual_chart,
-    median_forecasts_joined_with_observations,
 )
 
 
@@ -20,16 +20,16 @@ from chap_core.assessment.backtest_plots.predicted_vs_actual_plot import (
     name="Predicted vs Actual (linear)",
     description="Scatter plots of predicted (median) vs actual values on linear axes, faceted by horizon and colored by location.",
 )
-class PredictedVsActualLinearPlot(BacktestPlotBase):
-    def plot(
-        self,
-        observations: pd.DataFrame,
-        forecasts: pd.DataFrame,
-        historical_observations: pd.DataFrame | None = None,
-    ) -> ChartType:
-        merged = median_forecasts_joined_with_observations(forecasts, observations)
+class PredictedVsActualLinearPlot(PredictedVsActualPlot):
+    """Linear-axes variant of :class:`PredictedVsActualPlot`.
+
+    Inherits the horizon faceting and the median-vs-observed preprocessing; only
+    the per-facet chart differs (raw values instead of log1p-transformed axes).
+    """
+
+    def _plot(self, data: pd.DataFrame) -> ChartType:
         return build_predicted_vs_actual_chart(
-            merged,
+            data,
             x_field="median_forecast",
             y_field="disease_cases",
             title="Predicted vs Actual (linear scale)",

{chap_core-2.0.0 → chap_core-2.2.0}/chap_core/assessment/backtest_plots/predicted_vs_actual_plot.py

@@ -10,6 +10,7 @@ import numpy as np
 import pandas as pd
 
 from chap_core.assessment.backtest_plots import ChartType, FacetDimension, FacetedBacktestPlot, backtest_plot
+from chap_core.assessment.backtest_plots.db_dimensions import HorizonDistanceDimension
 from chap_core.plotting.backtest_plot import clean_time
 
 
@@ -93,7 +94,7 @@ def build_predicted_vs_actual_chart(
 )
 class PredictedVsActualPlot(FacetedBacktestPlot):
     facet_dimensions: list[FacetDimension] = [
-        FacetDimension(field_name="horizon_distance:O", display_name="Horizon Distance"),
+        HorizonDistanceDimension(field_name="horizon_distance:O", display_name="Horizon Distance"),
     ]
 
     resolve_scale_x = "shared"

chap_core-2.2.0/chap_core/assessment/backtest_plots/sample_bias_plot.py

@@ -0,0 +1,91 @@
+"""
+Sample bias plots for backtests.
+
+This module provides backtest plots that show the ratio of forecast samples
+above truth, one by horizon distance and one by time period.
+"""
+
+import altair as alt
+import pandas as pd
+
+from chap_core.assessment.backtest_plots import ChartType, FacetDimension, FacetedBacktestPlot, backtest_plot
+from chap_core.assessment.flat_representations import FlatForecasts, FlatObserved
+from chap_core.assessment.metrics import RatioAboveTruthMetric
+
+_BIAS_DESCRIPTION = (
+    "Shows biases in the samples returned by the model, specifically whether the samples "
+    "generally are over or under the true observation. This can be used to assess model "
+    "calibration and tendency to over- or under-predict."
+)
+
+
+class SampleBiasPlotBase(FacetedBacktestPlot):
+    """
+    Shared preprocessing for the sample bias plots.
+
+    Computes the ratio of forecast samples that are above the true observation
+    value per forecast row. The plots are aggregates with no per-coordinate
+    decomposition, so they declare no facet dimensions; they conform to the
+    faceting interface only so every registered plot shares the same shape.
+    """
+
+    facet_dimensions: list[FacetDimension] = []
+
+    def _preprocess(
+        self,
+        observations: pd.DataFrame,
+        forecasts: pd.DataFrame,
+        historical_observations: pd.DataFrame | None = None,
+    ) -> pd.DataFrame:
+        """Compute the ratio-of-samples-above-truth metric per forecast row."""
+        flat_observations = FlatObserved.validate(observations)
+        flat_forecasts = FlatForecasts.validate(forecasts)
+        metric = RatioAboveTruthMetric()
+        return metric.get_detailed_metric(flat_observations, flat_forecasts)
+
+
+@backtest_plot(
+    plot_id="sample_bias_by_horizon",
+    name="Sample Bias by Horizon",
+    description=f"Ratio of forecast samples above truth per forecast horizon. {_BIAS_DESCRIPTION}",
+)
+class SampleBiasByHorizonPlot(SampleBiasPlotBase):
+    """Bar chart of the mean ratio of samples above truth per forecast horizon."""
+
+    def _plot(self, metric_df: pd.DataFrame) -> ChartType:
+        horizon_df = metric_df.groupby(["horizon_distance"]).agg({"metric": "mean"}).reset_index()
+        return (  # type: ignore[no-any-return]
+            alt.Chart(horizon_df)
+            .mark_bar()
+            .encode(
+                x=alt.X("horizon_distance:O", title="Horizon (periods ahead)"),
+                y=alt.Y("metric:Q", title="Ratio of samples above truth"),
+                tooltip=["horizon_distance", "metric"],
+            )
+            .properties(height=300)
+        )
+
+
+@backtest_plot(
+    plot_id="sample_bias_by_time_period",
+    name="Sample Bias by Time Period",
+    description=(
+        f"Ratio of forecast samples above truth over time periods, one line per location. {_BIAS_DESCRIPTION}"
+    ),
+)
+class SampleBiasByTimePeriodPlot(SampleBiasPlotBase):
+    """Line chart of the mean ratio of samples above truth per time period and location."""
+
+    def _plot(self, metric_df: pd.DataFrame) -> ChartType:
+        time_df = metric_df.groupby(["time_period", "location"]).agg({"metric": "mean"}).reset_index()
+        return (  # type: ignore[no-any-return]
+            alt.Chart(time_df)
+            .mark_line(point=True)
+            .encode(
+                x=alt.X("time_period:O", title="Time period"),
+                y=alt.Y("metric:Q", title="Ratio of samples above truth"),
+                color=alt.Color("location:N", title="Location"),
+                tooltip=["time_period", "location", "metric"],
+            )
+            .properties(height=300)
+        )