"""Mergeable native path bid-price moments, independent of database recording."""
from __future__ import annotations
from typing import TYPE_CHECKING, Self
import pandas as pd
from passengersim.reporting import report_figure
from .generic import GenericSimulationTables, MissingDataError, SimulationTableItem
from .leg_bid_price_history import _as_id_list, _filter_bid_price_history
if TYPE_CHECKING:
import altair as alt
from passengersim import Simulation
def _fig_path_bid_prices(df: pd.DataFrame, *, std_dev: bool, augmented: bool) -> alt.Chart | alt.HConcatChart:
"""Keep path/cabin trajectories distinct, including in comparisons."""
import altair as alt
prefix = "augmented_" if augmented else ""
label = "Augmented Bid Price" if augmented else "Bid Price"
tooltip = [
alt.Tooltip("path_id:N", title="Path ID"),
alt.Tooltip("cabin_code:N", title="Cabin"),
alt.Tooltip("days_prior:Q", title="Days Prior to Departure", format=".0f"),
alt.Tooltip(f"{prefix}bid_price_mean:Q", title=f"Mean {label}", format=",.2f"),
alt.Tooltip(f"{prefix}bid_price_std_dev:Q", title=f"Std Dev {label}", 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="cabin_code:N",
tooltip=tooltip,
)
)
if df.path_id.nunique() < 13:
chart = chart.encode(color="path_id:N")
else:
# Both dimensions must group lines when color no longer identifies paths.
chart = chart.encode(detail=["path_id:N", "cabin_code:N"])
if "source" in df.columns:
chart = chart.encode(strokeDash="source:N", strokeWidth="source:N")
else:
chart = chart.encode(strokeDash="cabin_code:N")
mean = chart.encode(y=alt.Y(f"{prefix}bid_price_mean:Q", title=f"Mean {label}"))
if std_dev:
return mean | chart.encode(y=alt.Y(f"{prefix}bid_price_std_dev:Q", title=f"Std Dev {label}"))
return mean
def _moments_from_rows(rows: list[tuple[int, str, int, int, float, float, float, float]]) -> pd.DataFrame:
columns = ["path_id", "cabin_code", "days_prior", "n_observations", "mean", "M2", "augmented_mean", "augmented_M2"]
return (
pd.DataFrame(rows, columns=columns)
.astype(
{
"path_id": "int64",
"cabin_code": "object",
"days_prior": "int64",
"n_observations": "int64",
"mean": "float64",
"M2": "float64",
"augmented_mean": "float64",
"augmented_M2": "float64",
}
)
.set_index(["path_id", "cabin_code", "days_prior"])
.sort_index()
)
def _merge_moments(left: pd.DataFrame | None, right: pd.DataFrame | None) -> pd.DataFrame | None:
"""Merge paired moments using the same observation weights for both prices."""
from .leg_bid_price_history import _merge_moments as merge
if left is None:
return None if right is None else right.copy()
if right is None:
return left.copy()
result = merge(left, right)
rename = {"augmented_mean": "mean", "augmented_M2": "M2"}
augmented = merge(
left[["n_observations", *rename]].rename(columns=rename),
right[["n_observations", *rename]].rename(columns=rename),
)
result["augmented_mean"] = augmented["mean"]
result["augmented_M2"] = augmented["M2"]
return result
def _extract_moments(sim: Simulation) -> pd.DataFrame | None:
moments = sim._path_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 = SimTabPathBidPriceHistory.path_bid_price_history._get_raw(summary)
except MissingDataError:
continue
result = _merge_moments(result, frame)
return result
class _PathBidPriceHistoryItem(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),
"augmented_bid_price_mean": moments.augmented_mean.where(n > 0),
"augmented_bid_price_std_dev": (moments.augmented_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 SimTabPathBidPriceHistory(GenericSimulationTables):
"""Daily bid-price summaries pooled across all retained samples and trials."""
[docs]
@report_figure
def fig_path_bid_prices(
self,
*,
std_dev: bool = True,
augmented: bool = False,
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 path bid prices from native summary history.
Parameters
----------
std_dev : bool, optional
Show a second panel with pooled sample standard deviations (default True).
augmented : bool, optional
Plot augmented bid prices instead of ordinary path totals. Defaults to False.
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 path IDs. By default, show every path.
carrier, orig, dest : str or tuple[str, ...] or None, optional
Filter using path metadata. Values within a filter are alternatives;
different filters and ``ids`` are intersected. Requires ``paths`` 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 distinct paths 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.path_bid_price_history
if history is None:
raise MissingDataError(
"Native path_bid_price_history is unavailable; "
"run with simulation_controls.collect_path_bid_prices=True"
)
df = history.reset_index()
if ids is not None:
df = df[df.path_id.isin(_as_id_list(ids))]
df = _filter_bid_price_history(df, self, kind="path", carrier=carrier, orig=orig, dest=dest)
if raw_df:
return df
return _fig_path_bid_prices(df, std_dev=std_dev, augmented=augmented)
path_bid_price_history: pd.DataFrame | None = _PathBidPriceHistoryItem(
aggregation_func=_aggregate_moments,
extraction_func=_extract_moments,
doc="""Daily path/cabin bid-price moments, or None when not collected.
Indexed by ``(path_id, cabin_code, days_prior)``. Includes ``bid_price_mean``,
``bid_price_std_dev``, ``augmented_bid_price_mean``,
``augmented_bid_price_std_dev``, and one shared ``n_observations`` count.
Standard deviations use the sample convention and are undefined for n < 2.
Enable with ``simulation_controls.collect_path_bid_prices=True``.
Each retained sample contributes one paired observation per day. Totals
sum one-passenger reporting prices, retaining finite sold-out prices.
Augmentation adds ``fcst_revenue - adjusted_fare_price`` for the lowest-fare
class (by ``fcst_revenue``) with a finite adjusted fare at the active timeframe:
positive for ``bp``; ``bp_loose`` also allows zero only when the total
bid price is zero within 1e-9, so the zero-clipped class can currently open.
Positive adjusted fares remain eligible even when currently closed.
Booking code breaks equal-price ties. It includes MR or KI adjustment,
hybrid weighting, clipping, and class exemptions as used by offer checks.
If no class qualifies as a reference, the adjustment is zero and
no reference offer exists. The reference may change across time/samples;
this is its threshold, not a universal threshold for every class. Offer checks
treat differences smaller than 1e-9 as equality; ``bp`` closes at equality
and ``bp_loose`` opens.
Only bid-price-controlled carriers are collected. No adjustment gives
identical prices. Sold-out totals retain the finite reporting convention.
Raw moments survive trial/worker pooling and saved-result round trips.
""",
)