Source code for passengersim_core.forecast_tools

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