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()