Source code for passengersim.summaries.leg_callback_detail

"""Summary accessors and figures for the leg booking and bid-price detail callbacks.

The data come from the daily callbacks
:func:`passengersim.callbacks.booking_detail.collect_leg_booking_detail` and
:func:`passengersim.callbacks.bid_price_detail.collect_leg_bid_price_detail`,
which can be attached manually or enabled in a configuration as the
``leg_booking_detail`` and ``leg_bid_price_detail`` configured callbacks.

These members are defined here, on an ordinary summary-table class, so they are
always available on :class:`passengersim.SimulationTables` without importing the
callback modules for their side effects.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Literal

from passengersim.utils.colors import DarkOrange, DarkPurple

from .generic import GenericSimulationTables

if TYPE_CHECKING:
    import altair as alt
    import pandas as pd


[docs] class SimTabLegCallbackDetail(GenericSimulationTables): """Leg booking and bid-price detail collected by daily callbacks.""" @property def leg_booking_detail(self) -> pd.DataFrame: """Distribution of cumulative leg sales by days prior, across samples. Requires the ``leg_booking_detail`` callback (or :func:`~passengersim.callbacks.booking_detail.collect_leg_booking_detail`) to have been attached when the simulation ran. The table is computed from ``callback_data`` on first access and then cached. Returns ------- pandas.DataFrame Indexed by ``(days_prior, leg_id)`` with ``mean`` and quantile (``q10`` ... ``q90``) columns. """ from passengersim.callbacks.booking_detail import summarize_leg_booking_detail if "leg_booking_detail" not in self._data: self._data["leg_booking_detail"] = summarize_leg_booking_detail(self) return self._data["leg_booking_detail"]
[docs] def fig_leg_booking_detail_rake( self, *, leg_id: int, raw_df: bool = False, color: str = "red" ) -> alt.LayerChart | pd.DataFrame: """Plot the median and quantile bands of cumulative sales for one leg. Parameters ---------- leg_id : int The leg to plot; it must have been selected for collection. raw_df : bool, default False Return the plotted data instead of a chart. color : str, default "red" Line color. Returns ------- altair.LayerChart or pandas.DataFrame The rake chart, or its data when `raw_df` is True. """ from passengersim.callbacks.booking_detail import fig_leg_booking_detail_rake return fig_leg_booking_detail_rake(self, leg_id=leg_id, raw_df=raw_df, color=color)
@property def leg_bid_price_detail(self) -> pd.DataFrame: """Distribution of leg bid prices by days prior, across samples. Requires the ``leg_bid_price_detail`` callback (or :func:`~passengersim.callbacks.bid_price_detail.collect_leg_bid_price_detail`) to have been attached when the simulation ran. The table is computed from ``callback_data`` on first access and then cached. Returns ------- pandas.DataFrame Indexed by ``(days_prior, leg_id)`` with ``mean`` and quantile (``q10`` ... ``q90``) columns. """ from passengersim.callbacks.bid_price_detail import summarize_leg_bid_price_detail # Cached under its own key; it previously shared "leg_booking_detail", # so whichever detail table was read first was returned for both. if "leg_bid_price_detail" not in self._data: self._data["leg_bid_price_detail"] = summarize_leg_bid_price_detail(self) return self._data["leg_bid_price_detail"]
[docs] def fig_leg_bid_price_detail_rake( self, *, leg_id: int, raw_df: bool = False, color: str = DarkPurple, mean_color: str | None = DarkOrange, ) -> alt.LayerChart | pd.DataFrame: """Plot the median, quantile bands, and mean of bid prices for one leg. Parameters ---------- leg_id : int The leg to plot; it must have been selected for collection. raw_df : bool, default False Return the plotted data instead of a chart. color : str, optional Color of the median and quantile lines. mean_color : str or None, optional Color of the mean line, or None to omit it. Returns ------- altair.LayerChart or pandas.DataFrame The rake chart, or its data when `raw_df` is True. """ from passengersim.callbacks.bid_price_detail import fig_leg_bid_price_detail_rake return fig_leg_bid_price_detail_rake(self, leg_id=leg_id, raw_df=raw_df, color=color, mean_color=mean_color)
[docs] def fig_leg_bid_price_history( self, carrier: str, *, measure: Literal["mean", "q10", "q25", "q50", "q75", "q90", "median"], haul_category_labels: tuple[str, ...] | None = ("a. Short: ", "b. Medium: ", "c. Long: ", "d. Longest: "), opacity: float = 0.25, max_rows: int = 5000, ) -> alt.Chart: """Plot one bid-price statistic over days prior for every collected leg of a carrier. Parameters ---------- carrier : str Carrier whose legs are plotted. measure : {"mean", "q10", "q25", "q50", "q75", "q90", "median"} Statistic of :attr:`leg_bid_price_detail` to plot. haul_category_labels : tuple[str, ...] or None, optional Labels for distance quantile facets, or None for a single panel. opacity : float, default 0.25 Line opacity. max_rows : int, default 5000 Row limit; larger data are reduced to DCPs, then sampled. Returns ------- altair.Chart The faceted (or single) line chart. """ from passengersim.callbacks.bid_price_detail import fig_leg_bid_price_history return fig_leg_bid_price_history( self, carrier, measure=measure, haul_category_labels=haul_category_labels, opacity=opacity, max_rows=max_rows, )