Source code for passengersim.tracers.segmentation

"""Database-free tracer for sales and revenue by demand segment and timeframe.

The :class:`SegmentationTracer` collects the same information as the database-backed
``segmentation_detail`` summary table (cumulative sales by carrier, market, booking
class and DCP, split by passenger segment), plus realized revenue, without needing
the simulation database.  It can optionally be limited to a subset of O&D markets
and/or carriers, which keeps both run time and memory use small for large networks.

Results are averaged per sample across all (post-burn) samples in all trials, so the
final table has no ``trial`` dimension.  When run with
:class:`passengersim.MultiSimulation`, the per-process results are combined as a
sample-weighted mean, giving the same result as a single-process run.

Examples
--------
>>> import passengersim as pax
>>> from passengersim.tracers import SegmentationTracer
>>> sim = pax.Simulation(cfg)  # doctest: +SKIP
>>> SegmentationTracer(markets=[("BOS", "ORD"), ("ORD", "LAX")]).attach(
...     sim
... )  # doctest: +SKIP
>>> summary = sim.run()  # doctest: +SKIP
>>> summary.segmentation_detail_traced  # doctest: +SKIP
>>> summary.fig_segmentation_detail(metric="revenue")  # doctest: +SKIP
"""

from __future__ import annotations

import warnings
from collections.abc import Iterable
from typing import TYPE_CHECKING, ClassVar, Literal

import numpy as np
import pandas as pd
from pydantic import BaseModel

from .generic import GenericTracer

if TYPE_CHECKING:
    from passengersim import Simulation
    from passengersim.callbacks import CallbackData
    from passengersim.summaries.generic import GenericSimulationTables

SEGMENTATION_TRACER_NAME = "segmentation_detail"
"""Key under which the tracer's finalized table is stored in ``callback_data``."""

INDEX_NAMES = ["carrier", "orig", "dest", "booking_class", "segment", "days_prior"]
"""Index levels of the finalized segmentation detail table."""

VALUE_COLUMNS = ["sold", "revenue"]
"""Value columns of the finalized segmentation detail table."""


def _normalize_market(market: tuple[str, str] | str) -> tuple[str, str]:
    """Convert a market spec into an ``(orig, dest)`` tuple.

    Accepts a 2-tuple/list of airport codes, or a string such as ``"BOS-ORD"``
    or ``"BOS~ORD"``.
    """
    if isinstance(market, str):
        for sep in ("-", "~"):
            if sep in market:
                orig, dest = market.split(sep, 1)
                return orig.strip(), dest.strip()
        raise ValueError(f"cannot interpret market {market!r}; use (orig, dest) or 'ORIG-DEST'")
    orig, dest = market
    return str(orig), str(dest)


[docs] class SegmentationTracerOptions(BaseModel, extra="forbid"): """Configured-callback options for :class:`SegmentationTracer`.""" markets: list[tuple[str, str] | str] | None = None """Directional markets, as ``[orig, dest]`` pairs or ``"ORIG-DEST"`` strings, or None for all.""" carriers: list[str] | None = None """Carrier names, or None for all carriers.""" segments: list[str] | None = None """Demand segments, or None to detect all segments.""" priority: int = 1 """Seconds after the overnight trigger to collect data."""
[docs] class SegmentationTracer(GenericTracer): """A daily tracer recording sales and revenue by segment at each DCP. At every DCP of every post-burn sample, the cumulative (since the start of the sample) sales and realized revenue of each selected fare are read for each demand segment, using the bulk accessor :meth:`SimulationEngine.fare_segment_counters`, and added into in-memory accumulators. Nothing is written to the database. The finalized table is stored in ``summary.callback_data["segmentation_detail"]`` and is most conveniently accessed via :func:`segmentation_detail_traced` (also available as the ``segmentation_detail_traced`` property on summary objects). Notes ----- Fares sharing the same carrier, market and booking class (e.g. different brands or points of sale) are summed together in the output. Memory used during the run is proportional to (number of selected fares) x (number of DCPs) x (number of segments); use the `markets` and/or `carriers` filters to keep this small on large networks. """ name: str = SEGMENTATION_TRACER_NAME """Identifier used to store results in ``SimulationTables.callback_data``.""" hook: ClassVar[Literal["begin_sample", "daily", "end_sample"]] = "daily" """Lifecycle hook shared by manual and configured attachment.""" options_model: ClassVar[type[BaseModel]] = SegmentationTracerOptions """Configured-callback options; fields mirror the constructor."""
[docs] def __init__( self, markets: Iterable[tuple[str, str] | str] | None = None, *, carriers: Iterable[str] | None = None, segments: Iterable[str] | None = None, priority: int = 1, ) -> None: """Initialize the tracer. Parameters ---------- markets : Iterable[tuple[str, str] | str], optional The O&D markets to record, as directional ``(orig, dest)`` pairs or strings like ``"BOS-ORD"``. If not given, all markets are recorded. carriers : Iterable[str], optional Carrier names to record. If not given, all carriers are recorded. segments : Iterable[str], optional Demand segment names to record. If not given, every segment used by any demand in the simulation is recorded. priority : int, default 1 Daily callback priority, in seconds after the overnight trigger time. Positive values run after RM steps at the same time; no customers arrive within a few seconds of a DCP, so small positive values record the state exactly at the DCP. """ self.markets: frozenset[tuple[str, str]] | None = ( None if markets is None else frozenset(_normalize_market(m) for m in markets) ) """Directional markets to record, or None for all markets.""" self.carriers: frozenset[str] | None = None if carriers is None else frozenset(carriers) """Carrier names to record, or None for all carriers.""" self.segments: tuple[str, ...] | None = None if segments is None else tuple(segments) """Segment names requested by the user, or None to detect from demands.""" self.priority = priority """Daily callback priority, see :meth:`CallbackMixin.daily_callback`.""" self.reset()
[docs] def reset(self) -> None: """Reset all accumulated data, and forget the resolved fares.""" # The following are resolved lazily on the first call, because fares and # demands only exist once the simulation has been built. self._fares: list | None = None self._fare_keys: pd.DataFrame | None = None self._segments: list[str] | None = None self._dcps: list[int] | None = None self._dcp_pos: dict[int, int] = {} # Accumulators: sums has shape (n_fares, n_dcps, n_segments, 2), with the # last axis being (sold, revenue); counts is the number of samples # recorded at each DCP. self._sums: np.ndarray | None = None self._counts: np.ndarray | None = None self._coverage: dict | None = None
[docs] def fresh(self) -> SegmentationTracer: """Return a new, empty tracer with the same configuration. Returns ------- SegmentationTracer A freshly initialized tracer with the same filters and priority but no accumulated data. """ return type(self)( self.markets, carriers=self.carriers, segments=self.segments, priority=self.priority, )
[docs] def attach(self, sim: Simulation) -> None: """Attach a fresh instance of this tracer to `sim` as a daily callback. Parameters ---------- sim : Simulation or MultiSimulation The simulation to attach the callback to. """ getattr(sim, f"{self.hook}_callback")(self.fresh())
def __getstate__(self) -> dict: """Drop references to live engine objects when pickling.""" state = self.__dict__.copy() state["_fares"] = None return state def _resolve(self, sim: Simulation) -> None: """Select the fares, segments and DCPs to record, and allocate accumulators.""" fares = [] keys = [] for fare in sim.eng.fares: if self.markets is not None and (fare.orig, fare.dest) not in self.markets: continue carrier = fare.carrier_name if self.carriers is not None and carrier not in self.carriers: continue fares.append(fare) keys.append((carrier, fare.orig, fare.dest, fare.booking_class)) if self.markets is not None: found = {(k[1], k[2]) for k in keys} missing = self.markets - found if missing: warnings.warn( f"SegmentationTracer: no fares found for markets {sorted(missing)}", stacklevel=2, ) if not fares: warnings.warn("SegmentationTracer: no fares match the requested filters", stacklevel=2) if self.segments is not None: segments = list(self.segments) else: segments = sorted({dmd.segment for dmd in sim.eng.demands}) # Retain omitted scopes so figures can distinguish absent data from # zero sales, including after saving or combining worker summaries. all_markets = {(f.carrier_name, f.orig, f.dest) for f in sim.eng.fares} selected_markets = {k[:3] for k in keys} self._coverage = { "missing_markets": tuple(sorted(all_markets - selected_markets)), "missing_segments": tuple(sorted({d.segment for d in sim.eng.demands} - set(segments))), } self._fares = fares self._fare_keys = pd.DataFrame(keys, columns=INDEX_NAMES[:4]) self._segments = segments # DCPs in ascending days_prior order, matching the database query. self._dcps = sorted(set(int(d) for d in sim.dcp_list)) self._dcp_pos = {d: i for i, d in enumerate(self._dcps)} if self._sums is None: self._sums = np.zeros((len(fares), len(self._dcps), len(segments), 2), dtype=np.float64) self._counts = np.zeros(len(self._dcps), dtype=np.int64) def __call__(self, sim: Simulation, days_prior: int) -> None: """Record cumulative sales and revenue by segment, if today is a DCP. Skips burn-in samples and non-DCP days. Parameters ---------- sim : Simulation The running simulation. days_prior : int Days remaining before departure at the time of this callback. """ if sim.eng.sample < sim.eng.burn_samples: return if self._fares is None: self._resolve(sim) pos = self._dcp_pos.get(int(days_prior)) if pos is None: return # not a DCP if self._fares: self._sums[:, pos] += sim.eng.fare_segment_counters(self._fares, self._segments) self._counts[pos] += 1
[docs] def finalize(self) -> pd.DataFrame: """Convert the accumulators into a tidy DataFrame of per-sample means. Returns ------- pd.DataFrame Indexed by ``(carrier, orig, dest, booking_class, segment, days_prior)`` with columns ``sold`` and ``revenue``, giving the mean (per sample) cumulative sales and realized revenue from the start of the booking horizon through each DCP. The DataFrame attrs ``n_samples`` and ``aggregation_process`` are set so that results from multiple processes are combined as a sample-weighted mean. """ if self._sums is None or self._fare_keys is None: df = pd.DataFrame( columns=VALUE_COLUMNS, index=pd.MultiIndex.from_tuples([], names=INDEX_NAMES), dtype=np.float64, ) df.attrs["n_samples"] = 0 df.attrs["aggregation_process"] = "wgt_by_samples" df.attrs["segmentation_coverage"] = self._coverage return df n_fares, n_dcps, n_segs, _ = self._sums.shape # Mean per sample at each DCP; DCPs never observed stay at zero so that # they carry no weight when combined with other processes. counts = np.maximum(self._counts, 1).astype(np.float64) means = self._sums / counts[None, :, None, None] # Build the long-format frame: fare x segment x dcp, matching the # (fare, dcp, segment) array layout transposed to (fare, segment, dcp). means = means.transpose(0, 2, 1, 3).reshape(-1, 2) keys = self._fare_keys.loc[np.repeat(np.arange(n_fares), n_segs * n_dcps)].reset_index(drop=True) keys["segment"] = np.tile(np.repeat(np.asarray(self._segments, dtype=object), n_dcps), n_fares) keys["days_prior"] = np.tile(np.asarray(self._dcps, dtype=np.int64), n_fares * n_segs) keys["sold"] = means[:, 0] keys["revenue"] = means[:, 1] # Several fares may share a key (e.g. brands); sum them together. df = keys.groupby(INDEX_NAMES, sort=True)[VALUE_COLUMNS].sum() # Use the minimum count across DCPs; normally every DCP is observed in # every post-burn sample so these are all equal. df.attrs["n_samples"] = int(self._counts.min()) if len(self._counts) else 0 df.attrs["aggregation_process"] = "wgt_by_samples" df.attrs["segmentation_coverage"] = self._coverage return df
def _get_raw_table(source: GenericSimulationTables | CallbackData | pd.DataFrame) -> pd.DataFrame: """Extract the raw tracer table from a summary, callback data, or DataFrame.""" if isinstance(source, pd.DataFrame): return source callback_data = getattr(source, "callback_data", source) try: return callback_data[SEGMENTATION_TRACER_NAME] except (KeyError, TypeError): raise KeyError( f"no {SEGMENTATION_TRACER_NAME!r} found in callback data; " "attach a SegmentationTracer to the simulation before running it" ) from None
[docs] def cumulative_to_timeframe(df: pd.DataFrame) -> pd.DataFrame: """Convert cumulative-through-DCP values into values within each timeframe. Parameters ---------- df : pd.DataFrame A table indexed with ``days_prior`` as its last level, holding cumulative values (from the start of the booking horizon through each DCP), such as the output of :meth:`SegmentationTracer.finalize`. Returns ------- pd.DataFrame Same index levels, where each row's ``days_prior`` labels the *start* of a timeframe, and values are the amounts booked from that DCP up to the next DCP (closer to departure). The final DCP (normally 0, departure) starts no timeframe and is dropped. This matches the convention used by :meth:`SimTabSegmentationDetail.fig_segmentation_detail`. """ if df.index.names[-1] != "days_prior": raise ValueError("the last index level must be 'days_prior'") df = df.sort_index() groups = list(df.index.names[:-1]) # Within each group, rows are in ascending days_prior order, so the next DCP # toward departure is the previous row. nxt = df.groupby(groups, sort=False, observed=True).shift(1) out = nxt - df # The smallest days_prior in each group has no following timeframe. return out[nxt.notna().all(axis=1)]
[docs] def segmentation_detail_traced( source: GenericSimulationTables | CallbackData | pd.DataFrame, *, timeframe: bool = False, wide: bool = False, markets: Iterable[tuple[str, str] | str] | None = None, ) -> pd.DataFrame: """Get the tracer-based segmentation detail table, optionally reshaped. Parameters ---------- source : SimulationTables or CallbackData or pd.DataFrame A summary (or its ``callback_data``) from a simulation that was run with a :class:`SegmentationTracer` attached, or the raw tracer table. timeframe : bool, default False If True, convert cumulative values into values within each timeframe, see :func:`cumulative_to_timeframe`. wide : bool, default False If True, pivot segments into columns, named like ``sold_business`` and ``revenue_leisure``, and add ``sold`` and ``revenue`` total columns. markets : Iterable[tuple[str, str] | str], optional If given, filter the result to these directional markets. Returns ------- pd.DataFrame In long format (default), indexed by ``(carrier, orig, dest, booking_class, segment, days_prior)`` with ``sold`` and ``revenue`` columns. In wide format, the ``segment`` level is moved into columns. Values are means per sample, aggregated across all trials. Raises ------ KeyError If no segmentation tracer data is found in `source`. """ df = _get_raw_table(source).copy() df.attrs = {} if markets is not None: mkts = {_normalize_market(m) for m in markets} od = pd.MultiIndex.from_arrays([df.index.get_level_values("orig"), df.index.get_level_values("dest")]) df = df[od.isin(list(mkts))] if timeframe: df = cumulative_to_timeframe(df) if wide: df = df.unstack("segment") df.columns = [f"{metric}_{seg}" for metric, seg in df.columns] segs = sorted({c.split("_", 1)[1] for c in df.columns}) df.insert(0, "sold", df[[f"sold_{s}" for s in segs]].sum(axis=1)) df.insert(1, "revenue", df[[f"revenue_{s}" for s in segs]].sum(axis=1)) df = df.reorder_levels(INDEX_NAMES[:4] + ["days_prior"]).sort_index() return df
[docs] def segment_metric_table( source: GenericSimulationTables | CallbackData | pd.DataFrame, metric: Literal["bookings", "revenue"] = "bookings", ) -> pd.DataFrame: """Get cumulative values of one metric with segments as columns. This is the shape consumed by the segmentation detail figures. Parameters ---------- source : SimulationTables or CallbackData or pd.DataFrame See :func:`segmentation_detail_traced`. metric : {"bookings", "revenue"}, default "bookings" Which metric to return. Returns ------- pd.DataFrame Indexed by ``(carrier, orig, dest, booking_class, days_prior)`` with one column per segment, holding mean cumulative values per sample. """ col = {"bookings": "sold", "sold": "sold", "revenue": "revenue"}[metric] df = _get_raw_table(source)[col].unstack("segment") df.columns.name = None return df.reorder_levels(INDEX_NAMES[:4] + ["days_prior"]).sort_index()