Source code for passengersim.summaries.leg_bid_price_history

"""Mergeable native leg bid-price moments, independent of database recording."""

from __future__ import annotations

from collections.abc import Iterable
from typing import TYPE_CHECKING, Self

import pandas as pd

from passengersim.reporting import report_figure

from .generic import GenericSimulationTables, MissingDataError, SimulationTableItem

if TYPE_CHECKING:
    import altair as alt

    from passengersim import Simulation


def _as_id_list(ids: int | Iterable[int]) -> list[int]:
    """Accept a single ID as well as a collection, as the metadata filters do."""
    if pd.api.types.is_integer(ids):
        return [ids]
    return list(ids)


def _filter_bid_price_history(
    df: pd.DataFrame,
    summary: GenericSimulationTables,
    *,
    kind: str,
    carrier: str | tuple[str, ...] | None,
    orig: str | tuple[str, ...] | None,
    dest: str | tuple[str, ...] | None,
) -> pd.DataFrame:
    """Filter by entity metadata without joining or duplicating history rows."""
    filters = {key: value for key, value in dict(carrier=carrier, orig=orig, dest=dest).items() if value is not None}
    if not filters:
        return df
    metadata = getattr(summary, f"{kind}s")
    if metadata is None:
        raise MissingDataError(f"{kind}s metadata is required for carrier/orig/dest filters")
    for key, value in filters.items():
        metadata = metadata[metadata[key].isin((value,) if isinstance(value, str) else value)]
    return df[df[f"{kind}_id"].isin(metadata.index)]


def _fig_leg_bid_prices(df: pd.DataFrame, *, std_dev: bool) -> alt.Chart | alt.HConcatChart:
    """Build native leg bid-price panels for a single run or comparison."""
    import altair as alt

    tooltip = [
        alt.Tooltip("leg_id:N", title="Leg ID"),
        alt.Tooltip("days_prior:Q", title="Days Prior to Departure", format=".0f"),
        alt.Tooltip("bid_price_mean:Q", title="Mean Bid Price", format=",.2f"),
        alt.Tooltip("bid_price_std_dev:Q", title="Std Dev Bid Price", format=",.2f"),
        alt.Tooltip("n_observations:Q", title="Observations", format=",.0f"),
    ]
    if "source" in df.columns:
        tooltip.insert(0, alt.Tooltip("source:N", title="Source"))
    chart = (
        alt.Chart(df)
        .mark_line()
        .encode(
            x=alt.X("days_prior:Q", title="Days Prior to Departure").scale(reverse=True),
            detail="leg_id:N",
            tooltip=tooltip,
        )
    )
    # Keep trajectories separate even when there are too many IDs for useful colors.
    if df.leg_id.nunique() < 13:
        chart = chart.encode(color="leg_id:N")
    if "source" in df.columns:
        chart = chart.encode(strokeDash="source:N", strokeWidth="source:N")
    mean = chart.encode(y=alt.Y("bid_price_mean:Q", title="Mean Bid Price"))
    if std_dev:
        return mean | chart.encode(y=alt.Y("bid_price_std_dev:Q", title="Std Dev Bid Price"))
    return mean


def _moments_from_rows(rows: list[tuple[int, int, int, float, float]]) -> pd.DataFrame:
    return (
        pd.DataFrame(rows, columns=["leg_id", "days_prior", "n_observations", "mean", "M2"])
        .astype(
            {"leg_id": "int64", "days_prior": "int64", "n_observations": "int64", "mean": "float64", "M2": "float64"}
        )
        .set_index(["leg_id", "days_prior"])
        .sort_index()
    )


def _merge_moments(left: pd.DataFrame | None, right: pd.DataFrame | None) -> pd.DataFrame | None:
    """Pool Welford moments by observation count without modifying either input."""
    if left is None:
        return None if right is None else right.copy()
    if right is None:
        return left.copy()
    index = left.index.union(right.index).sort_values()
    a, b = left.reindex(index), right.reindex(index)
    na = a.n_observations.fillna(0).astype("int64")
    nb = b.n_observations.fillna(0).astype("int64")
    n = na + nb
    # Unobserved/missing cells are identities, not NaN observations. Retain NaNs
    # in genuinely observed means rather than silently treating those as zeros.
    ma, mb = a["mean"].where(na > 0, 0.0), b["mean"].where(nb > 0, 0.0)
    delta = mb - ma
    weight = nb / n.where(n > 0)
    return pd.DataFrame(
        {
            "n_observations": n,
            "mean": (ma + delta * weight).where(n > 0),
            "M2": (a.M2.where(na > 0, 0.0) + b.M2.where(nb > 0, 0.0) + delta**2 * na * weight).where(n > 0, 0.0),
        },
        index=index,
    )


def _extract_moments(sim: Simulation) -> pd.DataFrame | None:
    moments = sim._leg_bid_price_moments
    return None if moments is None else moments.copy()


def _aggregate_moments(summaries: list[GenericSimulationTables]) -> pd.DataFrame | None:
    result = None
    for summary in summaries:
        try:
            # Use the descriptor so lazy PXSIM results are loaded before merging,
            # including custom summary classes that only carry the stored payload.
            frame = SimTabLegBidPriceHistory.leg_bid_price_history._get_raw(summary)
        except MissingDataError:
            continue
        result = _merge_moments(result, frame)
    return result


class _LegBidPriceHistoryItem(SimulationTableItem):
    """Present derived statistics while retaining mergeable moments in storage."""

    @property
    def __doc__(self) -> str | None:
        # A subclass docstring otherwise shadows the base descriptor's API docs.
        return self._doc

    def __get__(
        self, instance: GenericSimulationTables | None, owner: type[GenericSimulationTables] | None = None
    ) -> pd.DataFrame | None | Self:
        if instance is None:
            return self
        moments = super().__get__(instance, owner)
        if moments is None:
            return None
        n = moments.n_observations
        # Build a separate public view: callers cannot accidentally corrupt the
        # raw moments required by worker aggregation or a later archive merge.
        return pd.DataFrame(
            {
                "bid_price_mean": moments["mean"].where(n > 0),
                "bid_price_std_dev": (moments.M2 / (n - 1).where(n > 1)).pow(0.5),
                "n_observations": n,
            },
            index=moments.index,
        )

    def _get_raw(self, instance: GenericSimulationTables) -> pd.DataFrame | None:
        # The base descriptor handles lazy PXSIM loading as well as live results.
        return super().__get__(instance, type(instance))

    def _get_export(self, instance: GenericSimulationTables) -> pd.DataFrame | None:
        return self.__get__(instance, type(instance))


[docs] class SimTabLegBidPriceHistory(GenericSimulationTables): """Daily bid-price summaries pooled across all retained samples and trials."""
[docs] @report_figure def fig_leg_bid_prices( self, *, std_dev: bool = True, raw_df: bool = False, ids: int | tuple[int, ...] | None = None, carrier: str | tuple[str, ...] | None = None, orig: str | tuple[str, ...] | None = None, dest: str | tuple[str, ...] | None = None, ) -> alt.Chart | alt.HConcatChart | pd.DataFrame: """Plot daily leg bid prices from native summary history. Parameters ---------- std_dev : bool, optional Show a second panel with pooled sample standard deviations (default True). raw_df : bool, optional Return tidy data instead of a chart. Native column names and observation counts are preserved. ids : int or tuple[int, ...] or None, optional Restrict the plot to these leg IDs. By default, show every leg. carrier, orig, dest : str or tuple[str, ...] or None, optional Filter using leg metadata. Values within a filter are alternatives; different filters and ``ids`` are intersected. Requires ``legs`` data. Returns ------- alt.Chart or alt.HConcatChart or pandas.DataFrame Mean bid prices, optionally beside standard deviations, or the plot data. Raises ------ MissingDataError Native history is absent, collection was disabled, or required metadata is absent. Notes ----- ID colors are used only for a dozen or fewer legs after filtering. Larger plots retain separate lines without ID colors. Statistics are already pooled across retained samples and trials. Undefined means and standard deviations remain missing rather than being filled with zero. The callback-based plot remains in ``passengersim.tracers.bid_price``. """ history = self.leg_bid_price_history if history is None: raise MissingDataError( "Native leg_bid_price_history is unavailable; run with simulation_controls.collect_leg_bid_prices=True" ) df = history.reset_index() if ids is not None: df = df[df.leg_id.isin(_as_id_list(ids))] df = _filter_bid_price_history(df, self, kind="leg", carrier=carrier, orig=orig, dest=dest) if raw_df: return df return _fig_leg_bid_prices(df, std_dev=std_dev)
leg_bid_price_history: pd.DataFrame | None = _LegBidPriceHistoryItem( aggregation_func=_aggregate_moments, extraction_func=_extract_moments, doc="""Daily native bid-price history for every leg, or None when not collected. Indexed by ``(leg_id, days_prior)`` with columns ``bid_price_mean``, ``bid_price_std_dev`` (pooled sample standard deviation), and ``n_observations``. Burn-in samples are excluded. Cells with zero observations have undefined mean and standard deviation; cells with one observation have undefined standard deviation. Collection is enabled by default. Set ``simulation_controls.collect_leg_bid_prices=False`` before running to disable it. Collection uses core daily-statistics timing and the leg reporting-price convention, including sold-out legs. It does not require a database or change ``LegBidPriceTracer``. Saved results retain moments so subsequent aggregation remains count-weighted and statistically correct. """, )