Source code for passengersim.callbacks.booking_detail

"""Daily tracer collecting cumulative sales for selected legs.

Attach a :class:`LegBookingDetailTracer` manually, or enable it in a configuration as the ``leg_booking_detail``
configured callback. The results are available on summaries as
``leg_booking_detail`` and ``fig_leg_booking_detail_rake`` (see
:class:`passengersim.summaries.leg_callback_detail.SimTabLegCallbackDetail`).

Results saved before this collector became a tracer hold the same values as
rows of ``callback_data.daily``, with keys such as ``leg-101-sold``; the
readers in this module accept both.
"""

from __future__ import annotations

import re
import typing
import warnings
from collections.abc import Iterable
from typing import Any, ClassVar, Literal

import altair as alt
import pandas as pd

# Relative imports: this module is loaded while ``passengersim.callbacks`` is
# still initializing (by the built-in registrations), so it must not import
# from the package namespace or from the summaries package at runtime.
from .base import CallbackData
from .configured import register_tracer
from .tracer import GenericTracer

if typing.TYPE_CHECKING:
    from passengersim.summaries import SimulationTables
    from passengersim.summaries.generic import GenericSimulationTables

DETAIL_INDEX_NAMES = ["trial", "sample", "days_prior"]
"""Index levels of the per-sample detail tables."""


[docs] class LegDetailTracer(GenericTracer): """Base for daily tracers keeping one value per leg, sample, and day. Each call records one row, keyed by ``(trial, sample, days_prior)``, with one column per selected leg. Unlike the summary-statistic tracers, every observation is kept, so quantiles can be computed afterwards. Subclasses set :attr:`name` and implement :meth:`_value`. """ hook: ClassVar[Literal["begin_sample", "daily", "end_sample"]] = "daily" """Lifecycle hook shared by manual and configured attachment.""" skip_burn: ClassVar[bool] = True """Burn-in samples are not recorded."""
[docs] def __init__(self, leg_ids: list[int], *, priority: int = 1, name: str | None = None) -> None: """Initialize the tracer. Parameters ---------- leg_ids : list[int] The legs to record. IDs not found in the simulation are ignored. priority : int, default 1 Daily offset in seconds from the overnight trigger; positive values run after the RM systems and the simulation's daily bookkeeping. Zero is not allowed. name : str, optional Key for the results in ``callback_data``; defaults to the class name. The summary accessors read only the default name. """ self.leg_ids = set(leg_ids) """IDs of the legs to record.""" self.priority = priority """Daily callback priority, see :meth:`CallbackMixin.daily_callback`.""" self._set_name(name) self.reset()
[docs] def reset(self) -> None: """Discard all recorded rows, and forget the selected legs.""" self._legs: list | None = None self._columns: list[int] = [] self._keys: list[tuple[int, int, int]] = [] self._rows: list[list[Any]] = []
def __getstate__(self) -> dict: """Drop references to live engine objects when pickling.""" state = self.__dict__.copy() state["_legs"] = None return state
[docs] def setup(self, sim: Any) -> None: """Select the legs to record, in the simulation's leg order. Parameters ---------- sim : Simulation The simulation about to run. """ self._legs = [leg for leg in sim.eng.legs if leg.leg_id in self.leg_ids] self._columns = [leg.leg_id for leg in self._legs]
def _value(self, leg: Any) -> Any: """The value recorded for one leg; implemented by subclasses.""" raise NotImplementedError def __call__(self, sim: Any, days_prior: int) -> None: """Record one row of values for the selected legs. Parameters ---------- sim : Simulation The running simulation. days_prior : int Days remaining before departure. """ if self._legs is None: # Normally done by setup(); kept for a tracer called directly. self.setup(sim) self._keys.append((sim.eng.trial, sim.eng.sample, days_prior)) self._rows.append([self._value(leg) for leg in self._legs])
[docs] def finalize(self) -> pd.DataFrame: """Convert the recorded rows into a table. Returns ------- pd.DataFrame Indexed by ``(trial, sample, days_prior)``, with one column per leg (named ``leg_id``). The ``aggregation_process`` attribute is ``"concat_rows"``, so results from several workers are stacked. """ levels = list(zip(*self._keys, strict=True)) if self._keys else [[], [], []] index = pd.MultiIndex.from_arrays(levels, names=DETAIL_INDEX_NAMES) df = pd.DataFrame(self._rows, index=index, columns=pd.Index(self._columns, name="leg_id")) df.attrs["aggregation_process"] = "concat_rows" return df
[docs] @register_tracer class LegBookingDetailTracer(LegDetailTracer): """Daily tracer recording the cumulative sales of selected legs in every sample.""" name: str = "leg_booking_detail" """Identifier used to store results in ``callback_data``.""" options_version: ClassVar[str] = "2" """Version 2 stores results under ``leg_booking_detail``, not in ``daily`` rows.""" def _value(self, leg: Any) -> int: return leg.sold
[docs] def detail_table(data: CallbackData | SimulationTables, name: str, legacy_suffix: str = "") -> pd.DataFrame: """Get a per-sample leg detail table, from a tracer or from legacy daily rows. Parameters ---------- data : CallbackData or SimulationTables Callback data, or a summary holding it. name : str The tracer's result name, such as ``"leg_booking_detail"``. legacy_suffix : str The suffix of legacy ``daily`` keys, such as ``"sold"`` for ``leg-101-sold``, used for results saved before the tracer existed. Returns ------- pd.DataFrame Indexed by ``(trial, sample, days_prior)``, one column per leg. Raises ------ KeyError If neither the tracer's table nor legacy daily rows are present. """ if not isinstance(data, CallbackData) and hasattr(data, "callback_data"): data = data.callback_data if name in data and isinstance(data[name], pd.DataFrame): return data[name].copy() if not legacy_suffix: raise KeyError(f"{name} not found in data and no legacy_suffix provided") pattern = f"leg-([0-9]+)-{legacy_suffix}" df = data.to_dataframe("daily").set_index(DETAIL_INDEX_NAMES).filter(regex=pattern) df.columns = [int(re.sub(pattern, r"\1", i)) for i in df.columns] df.columns.name = "leg_id" return df
[docs] def collect_leg_booking_detail(leg_ids: Iterable[int]) -> LegBookingDetailTracer: """Build a tracer recording cumulative sales for selected legs. .. deprecated:: Use :class:`LegBookingDetailTracer` directly. The tracer stores its results in ``callback_data.leg_booking_detail`` rather than in ``callback_data.daily`` rows; the summary accessors read either. Parameters ---------- leg_ids : Iterable[int] The legs to record. Returns ------- LegBookingDetailTracer A tracer to attach with ``sim.daily_callback``. """ warnings.warn( "collect_leg_booking_detail() is deprecated; use LegBookingDetailTracer(leg_ids) instead", DeprecationWarning, stacklevel=2, ) return LegBookingDetailTracer(list(leg_ids))
[docs] def process_leg_booking_detail(data: CallbackData | SimulationTables) -> pd.DataFrame: """Get the recorded cumulative sales, one row per trial, sample, and day. .. deprecated:: Use :func:`detail_table` with ``LegBookingDetailTracer.name``, or the summary accessor ``leg_booking_detail`` for the daily statistics. Parameters ---------- data : CallbackData or SimulationTables Callback data, or a summary holding it. Returns ------- pd.DataFrame Indexed by ``(trial, sample, days_prior)``, one column per leg. """ warnings.warn( "process_leg_booking_detail() is deprecated; use detail_table(data, LegBookingDetailTracer.name, 'sold')", DeprecationWarning, stacklevel=2, ) return detail_table(data, LegBookingDetailTracer.name, "sold")
def _summarize_leg_detail(table: pd.DataFrame) -> pd.DataFrame: """Compute daily means and quantiles across observed samples for each leg.""" grouped = table.astype(float, copy=False).groupby("days_prior") mean = grouped.mean().rename_axis(columns="leg_id").stack(future_stack=True) probabilities = [0.10, 0.25, 0.50, 0.75, 0.90] # Both reductions skip missing samples. Keeping the leg rows when stacking # preserves a row of NaNs for a leg with no observations on a given day. quantiles = grouped.quantile(probabilities).rename_axis(index=["days_prior", "metric"], columns="leg_id") quantiles = quantiles.stack(future_stack=True).unstack("metric").reindex(columns=probabilities) quantiles.columns = pd.Index(["q10", "q25", "q50", "q75", "q90"], name="metric") quantiles.insert(0, "mean", mean) return quantiles.reindex(mean.index)
[docs] def summarize_leg_booking_detail(data: CallbackData | GenericSimulationTables) -> pd.DataFrame: """Summarize the observed cumulative sales for each leg and day.""" return _summarize_leg_detail(detail_table(data, LegBookingDetailTracer.name, "sold"))
[docs] def fig_leg_booking_detail_rake( data: CallbackData | SimulationTables, *, leg_id: int, raw_df: bool = False, color: str = "red", ): df = summarize_leg_booking_detail(data) df = df.query(f"leg_id == {leg_id}").droplevel("leg_id") if raw_df: return df percentile_groups = { "q50": "Median", "q25": "25th and 75th", "q75": "25th and 75th", "q10": "10th and 90th", "q90": "10th and 90th", } dfc = df[list(percentile_groups)].stack(future_stack=True).rename("value").reset_index() dfc["percentiles"] = dfc["metric"].map(percentile_groups) domain = ["Median", "25th and 75th", "10th and 90th"] return alt.layer( alt.Chart(dfc) .mark_line(color=color) .encode( x=alt.X("days_prior:Q", title="Days Prior to Departure", scale=alt.Scale(reverse=True)), y="value:Q", detail="metric:N", strokeDash=alt.StrokeDash( "percentiles:N", title="Percentiles", scale=alt.Scale(domain=domain, range=[[], [5, 1], [3, 5]]) ), strokeWidth=alt.StrokeWidth( "percentiles:N", title="Percentiles", scale=alt.Scale(type="ordinal", domain=domain, range=[2, 1, 1]) ), ) )
# The summary accessor ``leg_booking_detail`` and the figure method # ``fig_leg_booking_detail_rake`` are defined on # ``passengersim.summaries.leg_callback_detail.SimTabLegCallbackDetail``; this # module no longer attaches them to the summary class as an import side effect.