Source code for passengersim.callbacks.booking_detail

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