"""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,
)