Source code for passengersim.summaries.demand_to_come

from __future__ import annotations

from typing import TYPE_CHECKING, Literal

import altair as alt
import numpy as np
import pandas as pd

from passengersim.database import common_queries
from passengersim.reporting import report_figure
from passengersim.utils.nested_dict import from_nested_dict

from .generic import DatabaseTableItem, GenericSimulationTables, MissingDataError, SimulationTableItem
from .tools import aggregate_by_concat_dataframe, combine_sigmas

if TYPE_CHECKING:
    from passengersim import Simulation

    from . import SimulationTables


[docs] def extract_demand_to_come_summary(sim: Simulation) -> pd.DataFrame: """Extract demand-to-come summary data from a Simulation.""" eng = sim.eng raw = eng.summary_demand_to_come() df = ( from_nested_dict(raw, ["segment", "days_prior", "metric"]) .sort_index(ascending=[True, False]) .rename(columns={"mean": "mean_future_demand", "stdev": "stdev_future_demand"}) ) return df
[docs] def aggregate_demand_to_come_summary( summaries: list[SimulationTables], ) -> pd.DataFrame | None: frames = [] for s in summaries: frame = getattr(s, "_raw_demand_to_come_summary", None) if isinstance(frame, Exception): raise frame if frame is not None: frames.append((frame, s.n_total_samples)) while len(frames) > 1: df, df_n = frames[0] other, other_n = frames.pop(1) df["stdev_future_demand"] = np.sqrt( combine_sigmas( df["stdev_future_demand"], other["stdev_future_demand"], df["mean_future_demand"], other["mean_future_demand"], df_n, other_n, ddof=1, ) ) df["mean_future_demand"] = (df["mean_future_demand"] * df_n + other["mean_future_demand"] * other_n) / ( df_n + other_n ) frames[0] = (df, df_n + other_n) if frames: return frames[0][0] return None
[docs] class SimTabDemandToCome(GenericSimulationTables): """Container for summary tables and figures extracted from a Simulation. This class is a subclass of GenericSimulationTables, which is defined in the generic module. It lists the items that are available in the SimulationTables class, and provides type hints and (optionally, but ideally) documentation for the data that is stored in each item. """ demand_to_come_summary: pd.DataFrame = SimulationTableItem( aggregation_func=aggregate_demand_to_come_summary, extraction_func=extract_demand_to_come_summary, doc="Demand-to-come summary data.", ) demand_to_come: pd.DataFrame = DatabaseTableItem( aggregation_func=aggregate_by_concat_dataframe("demand_to_come"), query_func=common_queries.demand_to_come, doc="Demand-to-come data.", )
[docs] @report_figure def fig_demand_to_come( self, func: Literal["mean", "std"] | list[Literal["mean", "std"]] = "mean", *, raw_df: bool = False, title: str | None = "Demand to Come", also_df: bool = False, ) -> alt.Chart | alt.HConcatChart | pd.DataFrame | tuple[alt.Chart | alt.HConcatChart, pd.DataFrame]: """Plot remaining demand by passenger segment for a single result. Use the collected ``demand_to_come_summary`` when available. Otherwise, sum markets within each sample in ``demand_to_come`` before computing statistics across samples. Standard deviations use ``ddof=1``. Parameters ---------- func : {'mean', 'std'} or list thereof, default 'mean' Statistic to plot. A nonempty list produces side-by-side panels in the requested order. raw_df : bool, default False Return the plotted data instead of a chart. Takes precedence over ``also_df``. title : str, optional Figure title. Pass ``None`` to omit it. also_df : bool, default False Return both the chart and its plotted data. Returns ------- alt.Chart or alt.HConcatChart or pandas.DataFrame or tuple The chart, plotted data, or ``(chart, dataframe)``. Data columns are ``segment``, ``days_prior``, and ``dtc``. For a list of statistics, an additional ``statistic`` column identifies each panel's values. Raises ------ ValueError If ``func`` is not ``'mean'``, ``'std'``, or a nonempty list of them, or fallback data cannot be loaded without a database connection. MissingDataError If neither the collected summary nor sample-level data is available. """ statistics = func if isinstance(func, list) else [func] if not statistics or any(statistic not in ("mean", "std") for statistic in statistics): raise ValueError("func must be 'mean', 'std', or a nonempty list of those statistics") try: summary = self.demand_to_come_summary except MissingDataError: summary = None if summary is None: history = self.demand_to_come if history is None: raise MissingDataError("demand_to_come") # Sum markets before taking standard deviations to retain covariance. levels = [name for name in history.index.names if name not in ("orig", "dest")] totals = history.groupby(level=levels, observed=True).sum(min_count=1) grouped = totals.groupby(level="segment", observed=True) columns = {"mean": "mean_future_demand", "std": "stdev_future_demand"} labels = {"mean": "Mean Demand to Come", "std": "Std Dev Demand to Come"} frames = [] for statistic in statistics: if summary is not None: values = summary[columns[statistic]] else: aggregated = grouped.mean() if statistic == "mean" else grouped.std(ddof=1) values = aggregated.rename_axis(columns="days_prior").stack(future_stack=True) frame = values.rename("dtc").reset_index() if isinstance(func, list): frame["statistic"] = statistic frames.append(frame) df = pd.concat(frames, ignore_index=True) if raw_df: return df charts = [] for statistic, frame in zip(statistics, frames): charts.append( alt.Chart(frame) .mark_line() .encode( x=alt.X("days_prior:O").scale(reverse=True).title("Days Prior to Departure"), y=alt.Y("dtc:Q", title=labels[statistic]), color=alt.Color("segment:N", title="Segment"), tooltip=["segment:N", "days_prior:O", alt.Tooltip("dtc:Q", format=",.2f")], ) ) fig = alt.hconcat(*charts) if isinstance(func, list) else charts[0] if title: fig = fig.properties(title=title) if also_df: return fig, df return fig
[docs] def aggregate_demand_history(self, by_segment: bool = True) -> pd.Series: """ Total demand by sample, aggregated over all markets. Parameters ---------- by_segment : bool, default True Aggregate by segment. If false, segments are also aggregated. Returns ------- pandas.Series Total demand, indexed by trial, sample, and segment (e.g. business/leisure). """ groupbys = ["trial", "sample"] if by_segment: groupbys.append("segment") df = self.demand_to_come if isinstance(df, Exception): raise df if not isinstance(df, pd.DataFrame): raise ValueError("demand_to_come is not a DataFrame") return df.iloc[:, 0].groupby(groupbys, observed=False).sum()