from __future__ import annotations
from typing import TYPE_CHECKING, Literal
from passengersim_core import Path, Leg, ForecastGroup
if TYPE_CHECKING:
from passengersim_core import Frat5, PathClass
from passengersim.snapshot import SnapshotInstruction
import altair as alt
import pandas as pd
[docs]
class ForecastData:
# The class-level default covers instances unpickled from before this
# attribute existed, which would otherwise fail in __getattr__.
adjusted_price: pd.DataFrame | None = None
"""Adjusted fare by timeframe and booking class, or None if not collected.
Only path forecasts carry this. Cells are NaN once a class has closed
under its advance purchase restriction.
"""
def __init__(
self,
label: str,
mean_to_departure: pd.DataFrame,
stdev_to_departure: pd.DataFrame,
mean_in_timeframe: pd.DataFrame,
stdev_in_timeframe: pd.DataFrame,
history_sold_priceable: pd.DataFrame = None,
history_sold_yieldable: pd.DataFrame = None,
history_closure: pd.DataFrame = None,
dcp_days_prior: tuple[int] = (),
adjusted_price: pd.DataFrame = None,
):
self.label = label
self.mean_to_departure = mean_to_departure
self.stdev_to_departure = stdev_to_departure
self.mean_in_timeframe = mean_in_timeframe
self.stdev_in_timeframe = stdev_in_timeframe
self.history_sold_priceable = history_sold_priceable
self.history_sold_yieldable = history_sold_yieldable
self.history_closure = history_closure
self.dcp_days_prior = dcp_days_prior
self.adjusted_price = adjusted_price
def _figure(self, kind: str, stack=False, days=False):
import altair as alt
df = getattr(self, kind)
if df is None or len(df) == 0:
bad = kind.replace("_", " ") + "\ndata not available"
return alt.Chart().mark_text(text=bad, lineBreak="\n").properties(title=self.label)
comparing = "source" in df.columns
stack |= "sold" in kind
if stack and not comparing:
# compute cumulative sum
df = pd.concat([df, df.cumsum(axis=1)], keys=["value", "cumulative"], axis=1)
cumulative_tip = [alt.Tooltip("cumulative:Q", title="cumulative")]
elif stack and comparing:
# when comparing, the cumulative sum is already computed
cumulative_tip = [alt.Tooltip("cumulative:Q", title="cumulative")]
else:
cumulative_tip = []
x = alt.X("tf_index:O").title("timeframe index")
xt = [alt.Tooltip("tf_index:O", title="timeframe index")]
if days and not comparing:
# change to days prior as a quantitative scale
if len(self.dcp_days_prior) == len(df):
df.index = self.dcp_days_prior
elif len(self.dcp_days_prior) == len(df) + 1:
df.index = self.dcp_days_prior[:-1]
elif len(df) != 0:
raise ValueError("length mismatch, cannot set days")
df.index.name = "days_prior"
x = alt.X("days_prior:Q").scale(domain=(self.dcp_days_prior[0], 0)).title("days prior to departure")
xt = [alt.Tooltip("days_prior:Q", title="days prior to departure")]
elif days and comparing:
# the conversion to days prior is already done
# but we need to use ordinal scale to make the figure readable
x = alt.X("days_prior:O").scale(reverse=True).title("days prior to departure")
xt = [
alt.Tooltip("days_prior:O", title="days prior to departure"),
alt.Tooltip("source:N"),
]
elif comparing:
x = alt.X("timeframe_start_day:O").scale(reverse=True).title("timeframe beginning day")
xt = [alt.Tooltip("timeframe_start_day:O", title="timeframe beginning day"), alt.Tooltip("source:N")]
else:
if (len(self.dcp_days_prior) == len(df)) or (
len(self.dcp_days_prior) == len(df) + 1 and self.dcp_days_prior[-1] == 0
):
df.index = self.dcp_days_prior[: len(df)]
df.index.name = "timeframe_start_day"
x = alt.X("timeframe_start_day:O").scale(reverse=True).title("timeframe beginning day")
xt = [alt.Tooltip("timeframe_start_day:O", title="timeframe beginning day")]
common_encoding = dict(
x=x,
y=alt.Y("value:Q", title=kind.replace("_", " ")),
color="booking_class",
tooltip=["booking_class", alt.Tooltip("value:Q", title=kind.replace("_", " ")), *cumulative_tip, *xt],
)
if stack and not comparing:
df = df.stack(future_stack=True).reset_index()
elif not comparing:
if "value" not in df.columns:
df = df.melt(ignore_index=False).reset_index()
# when `value` is present, the dataframe is already in the right format
if days and stack and not comparing:
return (
alt.Chart(df)
.mark_area()
.encode(
**common_encoding,
order=alt.Order("booking_class", sort="ascending"),
)
.properties(title=self.label)
)
elif days and stack and comparing:
return (
alt.Chart(df)
.mark_bar()
.encode(
**common_encoding,
xOffset=alt.XOffset("source:N"),
order=alt.Order("booking_class", sort="ascending"),
)
.properties(title=self.label)
)
elif stack and not comparing:
return (
alt.Chart(df)
.mark_bar()
.encode(
**common_encoding,
order=alt.Order("booking_class", sort="ascending"),
)
.properties(title=self.label)
)
elif stack and comparing:
return (
alt.Chart(df)
.mark_bar()
.encode(
**common_encoding,
xOffset=alt.XOffset("source:N"),
order=alt.Order("booking_class", sort="ascending"),
)
.properties(title=self.label)
)
elif comparing:
return (
alt.Chart(df)
.mark_line()
.encode(**common_encoding, strokeDash="source:N", strokeWidth="source:N")
.properties(title=self.label)
)
else:
return alt.Chart(df).mark_line().encode(**common_encoding).properties(title=self.label)
def __getattr__(self, item):
if item.startswith("fig_"):
return lambda *a, **kw: self._figure(item[4:], *a, **kw)
else:
raise AttributeError(f"Attribute {item} not found")
[docs]
def dashboard(self, tile_height=240, tile_width=300):
props = dict(height=tile_height, width=tile_width, title="")
result = (
self.fig_mean_to_departure(stack=True, days=True).properties(**props)
| self.fig_stdev_to_departure().properties(**props)
| self.fig_mean_in_timeframe(stack=True).properties(**props)
)
if self.history_sold_priceable is not None:
row2 = (
self.fig_history_sold_priceable().properties(**props)
| self.fig_history_sold_yieldable().properties(**props)
| self.fig_history_closure().properties(**props)
)
result = result & row2
elif self.history_sold_yieldable is not None:
row2 = self.fig_history_sold_yieldable().properties(**props) | self.fig_history_closure().properties(
**props
)
result = result & row2
else:
result = result & self.fig_history_closure().properties(**props)
if self.adjusted_price is not None:
result = result & self.fig_adjusted_price().properties(**props)
return result.properties(title=self.label)
[docs]
def to_dataframe(self):
df = pd.concat(
[
self.mean_to_departure,
self.stdev_to_departure,
self.mean_in_timeframe,
self.stdev_in_timeframe,
self.history_sold_priceable,
self.history_sold_yieldable,
self.history_closure,
self.adjusted_price,
],
keys=[
"mean_to_departure",
"stdev_to_departure",
"mean_in_timeframe",
"stdev_in_timeframe",
"history_sold_priceable",
"history_sold_yieldable",
"history_closure",
"adjusted_price",
],
axis=1,
)
df.index = df.index.map(dict(enumerate(self.dcp_days_prior))).rename("days_prior")
return df
[docs]
@classmethod
def from_dataframe(cls, df: pd.DataFrame, dcp_days_prior: tuple[int] | None = None):
if dcp_days_prior is None and df.index.name == "days_prior":
dcp_days_prior = tuple(df.index)
return cls(
label="",
mean_to_departure=df["mean_to_departure"],
stdev_to_departure=df["stdev_to_departure"],
mean_in_timeframe=df["mean_in_timeframe"],
stdev_in_timeframe=df["stdev_in_timeframe"],
history_sold_priceable=df["history_sold_priceable"] if "history_sold_priceable" in df else None,
history_sold_yieldable=df["history_sold_yieldable"] if "history_sold_yieldable" in df else None,
history_closure=df["history_closure"] if "history_closure" in df else None,
dcp_days_prior=dcp_days_prior,
# Absent from leg forecasts and from results saved by older versions.
adjusted_price=df["adjusted_price"] if "adjusted_price" in df else None,
)
def _adjusted_prices_by_timeframe(path_class: PathClass, n_timeframes: int) -> list[float]:
"""Return a path class's adjusted fare for each timeframe.
This mirrors what the database records in ``path_class_detail``: the
adjusted fare where one has been computed, and otherwise the forecast
revenue, which is the whole result when fare adjustment is not in use.
Parameters
----------
path_class : PathClass
The path class to read.
n_timeframes : int
The number of timeframes to return.
Returns
-------
list[float]
One price per timeframe. NaN marks timeframes after the class has
closed under its advance purchase restriction.
"""
prices = list(path_class.adjusted_marginal_revenue[:n_timeframes])
if len(prices) < n_timeframes:
prices.extend([path_class.get_fcst_revenue()] * (n_timeframes - len(prices)))
return prices
@Path._set_func_get_forecast_data
def get_forecasts(self: Path):
dcp_days_prior = self.carrier.dcp_days_prior
mean_to_departure = {}
stdev_to_departure = {}
mean_in_timeframe = {}
stdev_in_timeframe = {}
tot_sold_priceable = {}
tot_sold_yieldable = {}
closure_status = {}
adjusted_price = {}
for pc in self.pathclasses:
v = pc.forecast.get_vectors()
mean_to_departure[pc.booking_class] = v.mean_to_departure
stdev_to_departure[pc.booking_class] = v.stdev_to_departure
mean_in_timeframe[pc.booking_class] = v.mean_in_timeframe
stdev_in_timeframe[pc.booking_class] = v.stdev_in_timeframe
h = pc.forecast.history.as_mean_arrays()
if "sold_priceable" in h:
tot_sold_priceable[pc.booking_class] = h["sold_priceable"]
tot_sold_yieldable[pc.booking_class] = h["sold"] - h["sold_priceable"]
else:
tot_sold_yieldable[pc.booking_class] = h["sold"]
closure_status[pc.booking_class] = h["closure"]
adjusted_price[pc.booking_class] = _adjusted_prices_by_timeframe(pc, len(h["closure"]))
f = ForecastData(
label=str(self),
mean_to_departure=pd.DataFrame(mean_to_departure).rename_axis(index="tf_index", columns="booking_class"),
stdev_to_departure=pd.DataFrame(stdev_to_departure).rename_axis(index="tf_index", columns="booking_class"),
mean_in_timeframe=pd.DataFrame(mean_in_timeframe).rename_axis(index="tf_index", columns="booking_class"),
stdev_in_timeframe=pd.DataFrame(stdev_in_timeframe).rename_axis(index="tf_index", columns="booking_class"),
history_sold_priceable=pd.DataFrame(tot_sold_priceable).rename_axis(index="tf_index", columns="booking_class")
if tot_sold_priceable
else None,
history_sold_yieldable=pd.DataFrame(tot_sold_yieldable).rename_axis(index="tf_index", columns="booking_class"),
history_closure=pd.DataFrame(closure_status).rename_axis(index="tf_index", columns="booking_class"),
dcp_days_prior=dcp_days_prior,
adjusted_price=pd.DataFrame(adjusted_price).rename_axis(index="tf_index", columns="booking_class"),
)
return f
@Leg._set_func_get_forecast_data
def get_forecasts_leg(self: Leg):
dcp_days_prior = self.carrier.dcp_days_prior
mean_to_departure = {}
stdev_to_departure = {}
mean_in_timeframe = {}
stdev_in_timeframe = {}
tot_sold_priceable = {}
tot_sold_yieldable = {}
closure_status = {}
for bkt in self.buckets:
v = bkt.forecast.get_vectors()
mean_to_departure[bkt.booking_class] = v.mean_to_departure
stdev_to_departure[bkt.booking_class] = v.stdev_to_departure
mean_in_timeframe[bkt.booking_class] = v.mean_in_timeframe
stdev_in_timeframe[bkt.booking_class] = v.stdev_in_timeframe
h = bkt.forecast.history.as_mean_arrays()
if "sold_priceable" in h:
tot_sold_priceable[bkt.booking_class] = h["sold_priceable"]
tot_sold_yieldable[bkt.booking_class] = h["sold"] - h["sold_priceable"]
else:
tot_sold_yieldable[bkt.booking_class] = h["sold"]
closure_status[bkt.booking_class] = h["closure"]
f = ForecastData(
label=str(self),
mean_to_departure=pd.DataFrame(mean_to_departure).rename_axis(index="tf_index", columns="booking_class"),
stdev_to_departure=pd.DataFrame(stdev_to_departure).rename_axis(index="tf_index", columns="booking_class"),
mean_in_timeframe=pd.DataFrame(mean_in_timeframe).rename_axis(index="tf_index", columns="booking_class"),
stdev_in_timeframe=pd.DataFrame(stdev_in_timeframe).rename_axis(index="tf_index", columns="booking_class"),
history_sold_priceable=pd.DataFrame(tot_sold_priceable).rename_axis(index="tf_index", columns="booking_class")
if tot_sold_priceable
else None,
history_sold_yieldable=pd.DataFrame(tot_sold_yieldable).rename_axis(index="tf_index", columns="booking_class"),
history_closure=pd.DataFrame(closure_status).rename_axis(index="tf_index", columns="booking_class"),
dcp_days_prior=dcp_days_prior,
)
return f
@ForecastGroup._bind_method
def get_forecast_data(self: ForecastGroup, summarize_history: bool = False):
raw = dict(
label=self.label,
mean_to_departure=pd.DataFrame(self.get_mean_to_departure()).rename_axis(
index="tf_index", columns="booking_class"
),
stdev_to_departure=pd.DataFrame(self.get_stdev_to_departure()).rename_axis(
index="tf_index", columns="booking_class"
),
mean_in_timeframe=pd.DataFrame(self.get_mean_in_timeframe()).rename_axis(
index="tf_index", columns="booking_class"
),
stdev_in_timeframe=pd.DataFrame(self.get_stdev_in_timeframe()).rename_axis(
index="tf_index", columns="booking_class"
),
dcp_days_prior=self.dcp_days_prior,
)
if summarize_history:
tot_sold_priceable = {}
tot_sold_yieldable = {}
closure_status = {}
histories = self.get_history()
for booking_class, hist in histories.items():
h = hist.as_mean_arrays()
if "sold_priceable" in h:
tot_sold_priceable[booking_class] = h["sold_priceable"]
tot_sold_yieldable[booking_class] = h["sold"] - h["sold_priceable"]
else:
tot_sold_yieldable[booking_class] = h["sold"]
closure_status[booking_class] = h["closure"]
if tot_sold_priceable:
raw["history_sold_priceable"] = pd.DataFrame(tot_sold_priceable).rename_axis(
index="tf_index", columns="booking_class"
)
raw["history_sold_yieldable"] = pd.DataFrame(tot_sold_yieldable).rename_axis(
index="tf_index", columns="booking_class"
)
raw["history_closure"] = pd.DataFrame(closure_status).rename_axis(index="tf_index", columns="booking_class")
f = ForecastData(**raw)
return f
@ForecastGroup._bind_method
def update_q_forecast(
self: ForecastGroup,
f5: Frat5,
fa_algorithm: str = "mr",
fa_scale_factor: float = 0.25,
snapshot_instruction: SnapshotInstruction | None = None,
exp_smoothing_alpha: float | None = None,
):
"""Update the forecast using Q-Forecasting."""
if exp_smoothing_alpha is None:
forecast_algo = "additive_pickup"
alpha = 0.0
else:
forecast_algo = "exp_smoothing"
alpha = exp_smoothing_alpha
self.compute_simple_fare_adjustments(
algorithm=fa_algorithm,
frat5=f5,
scale_factor=fa_scale_factor,
snapshot_instruction=snapshot_instruction,
)
self.compute_sellup_probability(frat5=f5, snapshot_instruction=snapshot_instruction)
self.compute_hybrid_forecasts(
dcp_index=0,
algorithm=forecast_algo,
frat5=f5,
snapshot_instruction=snapshot_instruction,
recompute=True,
pods_init=False,
alpha=alpha,
)
self.allocate_q_demand(f5, 0, snapshot_instruction=snapshot_instruction, allocation_algorithm="tf")
self.combine_forecasts(
0,
rollup_algorithm="tf",
snapshot_instruction=snapshot_instruction,
)
@ForecastGroup._bind_method
def update_conditional_forecast(
self: ForecastGroup,
f5: Frat5,
fa_algorithm: str = "mr",
fa_scale_factor: float = 0.25,
snapshot_instruction: SnapshotInstruction | None = None,
exp_smoothing_alpha: float | None = None,
max_cap: float = 0.0,
regression_weight: Literal["sellup", "sellup^2", "fare", "none", None] = "sellup",
weighted_by_ratio: bool = True,
variance_is_ratio_of_mean: float = 0.0,
):
"""Update the forecast using Q-Forecasting."""
if exp_smoothing_alpha is None:
forecast_algo = "additive_pickup"
alpha = 0.0
else:
forecast_algo = "exp_smoothing"
alpha = exp_smoothing_alpha
self.compute_simple_fare_adjustments(
algorithm=fa_algorithm,
frat5=f5,
scale_factor=fa_scale_factor,
snapshot_instruction=snapshot_instruction,
)
self.compute_sellup_probability(frat5=f5, snapshot_instruction=snapshot_instruction)
self.compute_conditional_q_forecast(
f5,
0,
regression_weight=regression_weight,
max_cap=max_cap,
snapshot_instruction=snapshot_instruction,
variance_is_ratio_of_mean=variance_is_ratio_of_mean,
)
# The forecast has now been created in the q_forecast of the thing.
# Now we allocate the Q demand to the pathclasses/buckets.
self.allocate_q_demand(f5, 0, snapshot_instruction, allocation_algorithm="tf")
# compute the yieldable forecasts (if needed). This must be done before computing the
# fare adjustments if "weighted_by_ratio" is True, as in that case the fare adjustment is weighted by
# the ratio of priceable and yieldable forecasted demand. If "weighted_by_ratio" is False, then it is
# not critical to compute the yieldable forecasts before the fare adjustments, but it does not
# adversely affect the results to do so.
# TODO: check if actually needed? This may do a lot of compute to get to zero if not needed
self.compute_forecasts(
dcp_index=0,
algorithm=forecast_algo,
snapshot_instruction=snapshot_instruction,
recompute=True,
which_data="yieldable",
alpha=alpha,
)
# compute the "actual" fare adjustment after the Q demand has been allocated
# This does two things: zero out forecasted Q demand in classes that have a negative
# adjusted price, and weight the fare adjustment by the ratio of priceable and yieldable demand
if fa_algorithm is not None:
self.compute_fare_adjustments(
fa_algorithm,
f5,
snapshot_instruction=snapshot_instruction,
weighted_by_ratio=weighted_by_ratio,
scale_factor=fa_scale_factor,
)
self.combine_forecasts(
dcp_index=0,
rollup_algorithm="tf",
snapshot_instruction=snapshot_instruction,
)
###### Multi-Forecast Dashboarding
def _iterate_subfigures(fig: alt.Chart):
if "vconcat" in fig._kwds:
for i in fig._kwds["vconcat"]:
yield from _iterate_subfigures(i)
elif "hconcat" in fig._kwds:
for i in fig._kwds["hconcat"]:
yield from _iterate_subfigures(i)
else:
yield fig
def _collect_data_by_panel(fig: alt.Chart) -> dict[str, pd.DataFrame]:
collected = {}
for subfig in _iterate_subfigures(fig):
try:
y_title = subfig._kwds["encoding"].y["title"]
except (KeyError, AttributeError):
# raise ValueError(f"Could not find y title in subfigure type {type(subfig)}") from e
y_title = None
if y_title is not None:
collected[y_title] = subfig._kwds["data"]
return collected
def _collect_multiple_data_by_panel(figs) -> dict[str, dict[str, pd.DataFrame]]:
"""
Collect data from multiple dashboard figures.
Result is nested dict first by source, then by panel title.
"""
data = {}
for k, fig in figs.items():
try:
data[k] = _collect_data_by_panel(fig)
except ValueError as e:
print(f"Error processing figure for source {k}: {e}")
return data
def _combine_data_by_panel(d: dict[str, dict[str, pd.DataFrame]]):
# by_panel = list(zip(*(_iterate_nested_list(d[z]) for z in top_keys)))
from collections import defaultdict
combined = {}
pending = defaultdict(dict)
for source_name, content in d.items():
for panel_name, df in content.items():
pending[panel_name][source_name] = df
for panel_name, sources in pending.items():
try:
c = pd.concat(sources, names=["source"]).reset_index("source")
except:
import sys
print(f"panel_name: {panel_name}", file=sys.stderr)
print(f"sources: {sources.keys()}", file=sys.stderr)
print("----", file=sys.stderr)
for s in sources.values():
print(s, file=sys.stderr)
print("----", file=sys.stderr)
raise
combined[panel_name] = c
return combined
def multi_forecast_dashboard(
**kwds: dict[str, ForecastData],
):
"""
Create a dashboard of leg forecasts.
Parameters
----------
**kwds
Returns
-------
alt.Chart
The dashboard figure.
"""
figs = {k: v.dashboard() for k, v in kwds.items()}
figd_panel = _collect_multiple_data_by_panel(figs)
dfs_p = _combine_data_by_panel(figd_panel)
singleton = next(iter(kwds.values()))
fd = ForecastData(
**{k.replace(" ", "_"): v for (k, v) in dfs_p.items()},
label=str(singleton.label),
stdev_in_timeframe=pd.DataFrame(),
)
return fd.dashboard()
@ForecastGroup._bind_method
def _dump_histories(self: ForecastGroup, as_code: bool = False) -> dict:
"""Dump the histories of the forecast group."""
from passengersim.utils.compression import pretty_pack
history = {}
for k, h in self.get_history().items():
history[k] = h._dump_state()
if as_code:
print("{")
for k, h in history.items():
packed = pretty_pack(h).replace("\n", "\n ")
print(f" '{k}': {packed},\n")
print("}")
return history