"""Daily callback collecting cumulative sales for selected legs.
Attach :func:`collect_leg_booking_detail` 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`).
"""
from __future__ import annotations
import re
import typing
from functools import partial
import altair as alt
import numpy as np
import pandas as pd
from pydantic import BaseModel
# 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 CallbackDefinition
if typing.TYPE_CHECKING:
from collections.abc import Callable
from passengersim.callbacks import CallbackMixin
from passengersim.summaries import SimulationTables
from passengersim.summaries.generic import GenericSimulationTables
def _collect_leg_booking_detail(sim: CallbackMixin, days_prior: int, *, leg_ids: set[int]) -> dict | None:
"""A daily callback function to collect sales for selected legs."""
if sim.eng.sample < sim.eng.burn_samples:
# don't collect data during burn period
return None
# create a dictionary to store the sales for each leg
out = {}
# iterate over all legs in the simulation engine, and collect the current leg sales
for leg in sim.eng.legs:
if leg.leg_id not in leg_ids:
continue
out[f"leg-{leg.leg_id}-sold"] = leg.sold
# return the value, which will be end up as "callback_data" in the results
return out
[docs]
def collect_leg_booking_detail(leg_ids: set[int]) -> Callable[[CallbackMixin, int], dict | None]:
"""Build a daily callback that records cumulative sales for selected legs.
Parameters
----------
leg_ids : collection of int
The legs to record.
Returns
-------
Callable
A daily callback returning ``{"leg-<id>-sold": sold}`` for each selected
leg, or None during burn-in samples.
"""
leg_ids = set(leg_ids)
return partial(_collect_leg_booking_detail, leg_ids=leg_ids)
[docs]
class LegBookingDetailOptions(BaseModel, extra="forbid"):
"""Options for the ``leg_booking_detail`` configured callback."""
leg_ids: list[int]
"""Leg IDs to record."""
def _make_leg_booking_detail(options: LegBookingDetailOptions) -> Callable[[CallbackMixin, int], dict | None]:
"""Configured-callback factory: build a fresh collector from validated options."""
return collect_leg_booking_detail(options.leg_ids)
LEG_BOOKING_DETAIL_CALLBACK = CallbackDefinition(
factory=_make_leg_booking_detail,
when="daily",
parameters_model=LegBookingDetailOptions,
version="1",
)
"""Configured-callback definition, registered as ``leg_booking_detail`` by the built-ins."""
[docs]
def process_leg_booking_detail(
data: CallbackData | SimulationTables,
) -> pd.DataFrame:
if not isinstance(data, CallbackData) and hasattr(data, "callback_data"):
data = data.callback_data
df = data.to_dataframe("daily").set_index(["trial", "sample", "days_prior"]).filter(regex="leg-[0-9]+-sold")
df.columns = [int(re.sub(r"leg-([0-9]+)-sold", r"\1", i)) for i in df.columns]
df.columns.name = "leg_id"
return df
[docs]
def summarize_leg_booking_detail(
data: CallbackData | GenericSimulationTables,
):
df = process_leg_booking_detail(data)
summary = (
df.groupby(["days_prior"])
.agg(
[
("mean", "mean"),
("q10", lambda x: np.quantile(x, 0.10)),
("q25", lambda x: np.quantile(x, 0.25)),
("q50", lambda x: np.quantile(x, 0.5)),
("q75", lambda x: np.quantile(x, 0.75)),
("q90", lambda x: np.quantile(x, 0.90)),
]
)
.stack(level=0, future_stack=True)
)
summary.columns.name = "metric"
return summary
[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
dfc = df.stack(level=0, future_stack=True).rename("value").reset_index()
median = (
alt.Chart(dfc.query("metric == 'q50'"))
.mark_line(color=color, strokeWidth=2.0)
.encode(
x=alt.X("days_prior", title="Days Prior to Departure", scale=alt.Scale(reverse=True)),
y="value",
)
)
q10_q90 = (
alt.Chart(dfc.query("metric in ['q10', 'q90']"))
.mark_line(color=color, strokeWidth=1.0, strokeDash=[3, 5])
.encode(
x=alt.X("days_prior", title="Days Prior to Departure", scale=alt.Scale(reverse=True)),
y="value",
detail="metric",
)
)
q25_q75 = (
alt.Chart(dfc.query("metric in ['q25', 'q75']"))
.mark_line(color=color, strokeWidth=1.0, strokeDash=[5, 1])
.encode(
x=alt.X("days_prior", title="Days Prior to Departure", scale=alt.Scale(reverse=True)),
y="value",
detail="metric",
)
)
return median + q10_q90 + q25_q75
# 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.