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