"""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.
""",
)