Source code for passengersim.contrast.duo

"""Visualization tools for comparing exactly two simulations.

Each function here takes two positional arguments that each provide a `SimulationTables` object,
the "baseline" and "treatment" scenarios to compare. The functions then produce visualizations
that show the shift performance metrics (e.g. load factor, local share) from the baseline
to the treatment scenarios.
"""

from typing import Literal

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

from passengersim.summaries import SimulationTables


[docs] def fig_leg_shifts( baseline: SimulationTables, treatment: SimulationTables, *, coloring: Literal["avg_revenue", "change_revenue", "change_revenue_pct", None] = "avg_revenue", size_range: tuple[int, int] = (10, 100), facet_width: int = 400, facet_height: int = 400, facet_columns: int = 2, opacity: float = 1.0, fillOpacity: float = 1.0, strokeOpacity: float = 1.0, strokeWidth: float = 1.0, raw_df: bool = False, ): """Create a scatter/shift chart comparing leg-level metrics between two simulations. For each leg, a "lollipop" is drawn, with the stick showing the change from the baseline to the treatment position in load-factor vs. local-share space, and the point marking the treatment result. The size of the point reflects the leg total capacity (across all cabins). This makes it easy to see both the magnitude and direction of change for every leg. Parameters ---------- baseline : SimulationTables Simulation results to use as the reference (baseline) scenario. treatment : SimulationTables Simulation results to compare against the baseline (treatment) scenario. coloring : {"avg_revenue", "change_revenue", "change_revenue_pct"}, optional Determines how points and lines are colored: - ``"avg_revenue"`` – color by absolute average revenue in the treatment. - ``"change_revenue"`` – color by the absolute change in average revenue (treatment minus baseline), using a diverging red-blue scale centered at 0. - ``"change_revenue_pct"`` – color by the percentage change in average revenue, using a diverging red-blue scale centered at 0. - ``None`` – color by carrier (nominal color encoding). size_range : tuple[int, int], optional Minimum and maximum point sizes (in pixels²) used to encode leg capacity. facet_width : int, optional Width of each facet panel in pixels. facet_height : int, optional Height of each facet panel in pixels. facet_columns : int, optional Number of columns in the faceted layout (one facet per carrier). opacity : float, optional Overall opacity of the point marks. fillOpacity : float, optional Fill opacity of the point marks. strokeOpacity : float, optional Stroke opacity of both point and line marks. strokeWidth : float, optional Stroke width of the line (rule) marks. Returns ------- altair.FacetChart An interactive Altair faceted chart (faceted by carrier) showing the shift in load factor and local share for each leg between baseline and treatment. """ df_baseline = baseline.legs_ df_treatment = treatment.legs df_baseline["avg_revenue"] = df_baseline["gt_revenue"] / baseline.n_total_samples df_treatment["avg_revenue"] = df_treatment["gt_revenue"] / treatment.n_total_samples df = pd.merge( df_baseline, df_treatment, on=["leg_id", "carrier", "orig", "dest", "flt_no", "distance"], suffixes=("_baseline", "_treatment"), ) df["avg_revenue_change"] = df["avg_revenue_treatment"] - df["avg_revenue_baseline"] df["avg_revenue_change_pct"] = df["avg_revenue_change"] / df["avg_revenue_baseline"] if raw_df: return df chart = alt.Chart(df.reset_index()) if coloring == "avg_revenue": color = alt.Color( "avg_revenue_treatment:Q", title="Avg Revenue", ) elif coloring == "change_revenue": color = alt.Color( "avg_revenue_change:Q", title="Δ Avg Revenue", scale=alt.Scale( scheme="redblue", # Use a diverging scheme domainMid=0, # Forces the center of the scheme to 0 ), ) elif coloring == "change_revenue_pct": color = alt.Color( "avg_revenue_change_pct:Q", title="Δ Avg Revenue %", scale=alt.Scale( scheme="redblue", # Use a diverging scheme domainMid=0, # Forces the center of the scheme to 0 ), legend=alt.Legend(format=".1%"), ) elif coloring is None: color = alt.Color("carrier:N", title="Carrier") else: raise ValueError(f"Unknown coloring {coloring}") tooltips = [ alt.Tooltip("carrier", title="Carrier"), alt.Tooltip("orig", title="Origin"), alt.Tooltip("dest", title="Destination"), alt.Tooltip("avg_load_factor_baseline", title="Avg Load Factor (Baseline)", format=".2f"), alt.Tooltip("avg_load_factor_treatment", title="Avg Load Factor (Treatment)", format=".2f"), alt.Tooltip("avg_local_baseline", title="Avg Local Share (Baseline)", format=".2f"), alt.Tooltip("avg_local_treatment", title="Avg Local Share (Treatment)", format=".2f"), alt.Tooltip("avg_revenue_baseline", title="Avg Revenue (Baseline)", format="$.3s"), alt.Tooltip("avg_revenue_treatment", title="Avg Revenue (Treatment)", format="$.3s"), alt.Tooltip("avg_revenue_change", title="Δ Avg Revenue", format="$.3s"), alt.Tooltip("avg_revenue_change_pct", title="Δ Avg Revenue %", format=".2%"), alt.Tooltip("capacity"), ] lines = chart.mark_rule(strokeWidth=strokeWidth, strokeOpacity=strokeOpacity).encode( x=alt.X("avg_load_factor_baseline", scale=alt.Scale(zero=False), title="Avg Load Factor"), x2="avg_load_factor_treatment", y=alt.Y("avg_local_baseline", scale=alt.Scale(zero=False), title="Avg Local Share"), y2=alt.Y2("avg_local_treatment"), color=color, tooltip=tooltips, ) points = chart.mark_point( filled=True, opacity=opacity, fillOpacity=fillOpacity, strokeOpacity=strokeOpacity ).encode( x=alt.X("avg_load_factor_treatment", scale=alt.Scale(zero=False), title="Avg Load Factor"), y=alt.Y("avg_local_treatment", scale=alt.Scale(zero=False), title="Avg Local Share"), size=alt.Size("capacity:Q", title="Capacity", scale=alt.Scale(range=size_range)), color=color, tooltip=tooltips, ) return ( (points + lines) .properties(width=facet_width, height=facet_height) .facet("carrier", columns=facet_columns) .interactive() )
[docs] def fig_service_shifts( baseline: SimulationTables, treatment: SimulationTables, *, coloring: Literal["avg_revenue", "change_revenue", None] = "avg_revenue", size_range: tuple[int, int] = (10, 100), facet_width: int = 400, facet_height: int = 400, facet_columns: int = 2, opacity: float = 1.0, fillOpacity: float = 1.0, strokeOpacity: float = 1.0, strokeWidth: float = 1.0, ): """Create a scatter/shift chart comparing service-level metrics between two simulations. For each O&D service, a "lollipop" is drawn, with the stick showing the shift from the baseline to the treatment position in load-factor vs. local-share space, and the point marking the treatment result. Services are the aggregation of all legs sharing a common carrier, origin, and destination. Parameters ---------- baseline : SimulationTables Simulation results to use as the reference (baseline) scenario. treatment : SimulationTables Simulation results to compare against the baseline (treatment) scenario. coloring : {"avg_revenue", "change_revenue"}, optional Determines how points and lines are colored: - ``"avg_revenue"`` – color by absolute average revenue in the treatment. - ``"change_revenue"`` – color by the absolute change in average revenue (treatment minus baseline), using a diverging red-blue scale centered at 0. - ``None`` – color by carrier (nominal color encoding). size_range : tuple[int, int], optional Minimum and maximum point sizes (in pixels²) used to encode service capacity. facet_width : int, optional Width of each facet panel in pixels. facet_height : int, optional Height of each facet panel in pixels. facet_columns : int, optional Number of columns in the faceted layout (one facet per carrier). opacity : float, optional Overall opacity of the point marks. fillOpacity : float, optional Fill opacity of the point marks. strokeOpacity : float, optional Stroke opacity of both point and line marks. strokeWidth : float, optional Stroke width of the line (rule) marks. Returns ------- altair.FacetChart An interactive Altair faceted chart (faceted by carrier) showing the shift in load factor and local share for each service between baseline and treatment. """ df_baseline = baseline.services df_treatment = treatment.services df = pd.merge( df_baseline, df_treatment, on=["carrier", "orig", "dest", "distance", "capacity", "frequency"], suffixes=("_baseline", "_treatment"), ) df["avg_revenue_change"] = df["avg_revenue_treatment"] - df["avg_revenue_baseline"] chart = alt.Chart(df.reset_index()) if coloring == "avg_revenue": color = alt.Color( "avg_revenue_treatment:Q", title="Avg Revenue", ) elif coloring == "change_revenue": color = alt.Color( "avg_revenue_change:Q", title="Δ Avg Revenue", scale=alt.Scale( scheme="redblue", # Use a diverging scheme domainMid=0, # Forces the center of the scheme to 0 ), ) elif coloring is None: color = alt.Color("carrier:N", title="Carrier") else: raise ValueError(f"Unknown coloring {coloring}") tooltips = [ alt.Tooltip("carrier", title="Carrier"), alt.Tooltip("orig", title="Origin"), alt.Tooltip("dest", title="Destination"), alt.Tooltip("avg_load_factor_baseline", title="Avg Load Factor (Baseline)", format=".2f"), alt.Tooltip("avg_load_factor_treatment", title="Avg Load Factor (Treatment)", format=".2f"), alt.Tooltip("avg_local_baseline", title="Avg Local Share (Baseline)", format=".2f"), alt.Tooltip("avg_local_treatment", title="Avg Local Share (Treatment)", format=".2f"), alt.Tooltip("avg_revenue_baseline", title="Avg Revenue (Baseline)", format="$.3s"), alt.Tooltip("avg_revenue_treatment", title="Avg Revenue (Treatment)", format="$.3s"), alt.Tooltip("avg_revenue_change", title="Δ Avg Revenue", format="$.3s"), alt.Tooltip("capacity"), ] lines = chart.mark_rule(strokeWidth=strokeWidth, strokeOpacity=strokeOpacity).encode( x=alt.X("avg_load_factor_baseline", scale=alt.Scale(zero=False), title="Avg Load Factor"), x2="avg_load_factor_treatment", y=alt.Y("avg_local_baseline", scale=alt.Scale(zero=False), title="Avg Local Share"), y2=alt.Y2("avg_local_treatment"), color=color, tooltip=tooltips, ) points = chart.mark_point( filled=True, opacity=opacity, fillOpacity=fillOpacity, strokeOpacity=strokeOpacity ).encode( x=alt.X("avg_load_factor_treatment", scale=alt.Scale(zero=False), title="Avg Load Factor"), y=alt.Y("avg_local_treatment", scale=alt.Scale(zero=False), title="Avg Local Share"), size=alt.Size("capacity:Q", title="Capacity", scale=alt.Scale(range=size_range)), color=color, tooltip=tooltips, ) return ( (points + lines) .properties(width=facet_width, height=facet_height) .facet("carrier", columns=facet_columns) .interactive() )
[docs] def fig_market_shifts( baseline: SimulationTables, treatment: SimulationTables, *, coloring: Literal["avg_revenue", "change_revenue", "change_revenue_pct", None] = "change_revenue", size_range: tuple[int, int] = (10, 100), facet_width: int = 400, facet_height: int = 400, facet_columns: int = 2, opacity: float = 1.0, fillOpacity: float = 1.0, strokeOpacity: float = 1.0, strokeWidth: float = 1.0, ) -> alt.FacetChart: """Create a scatter/shift chart comparing carrier-market metrics between two simulations. For each carrier in each O&D market, a "lollipop" is drawn, with the stick showing the shift from the baseline to the treatment position in average-sold vs. average-price space, and the point marking the treatment result. The size of the point reflects the carrier's treatment market share (by passengers sold) in that O&D market. Market results are the aggregation of all path classes sharing a common carrier, origin, and destination, so they include both nonstop and connecting itineraries. This makes it easy to see whether a carrier gained or lost traffic in a market, and whether it did so by moving price, volume, or both. Values are averaged per sample, i.e. the grand totals for each simulation are divided by that simulation's ``n_total_samples``. Average price is computed as average revenue divided by average passengers sold. Only carrier-markets present in both simulations are shown. Parameters ---------- baseline : SimulationTables Simulation results to use as the reference (baseline) scenario. Must include the ``pathclasses`` table. treatment : SimulationTables Simulation results to compare against the baseline (treatment) scenario. Must include the ``pathclasses`` table. coloring : {"avg_revenue", "change_revenue", "change_revenue_pct", None}, optional Determines how points and lines are colored: - ``"avg_revenue"`` – color by absolute average revenue in the treatment. - ``"change_revenue"`` – color by the absolute change in average revenue (treatment minus baseline), using a diverging red-blue scale centered at 0. This is the default. - ``"change_revenue_pct"`` – color by the percentage change in average revenue, using a diverging red-blue scale centered at 0. Markets with zero baseline revenue have no defined percentage change and are left uncolored. - ``None`` – color by carrier (nominal color encoding). size_range : tuple[int, int], optional Minimum and maximum point sizes (in pixels²) used to encode the carrier's treatment market share. facet_width : int, optional Width of each facet panel in pixels. facet_height : int, optional Height of each facet panel in pixels. facet_columns : int, optional Number of columns in the faceted layout (one facet per carrier). opacity : float, optional Overall opacity of the point marks. fillOpacity : float, optional Fill opacity of the point marks. strokeOpacity : float, optional Stroke opacity of both point and line marks. strokeWidth : float, optional Stroke width of the line (rule) marks. Returns ------- altair.FacetChart An interactive Altair faceted chart (faceted by carrier) showing the shift in average sold and average price for each carrier-market between baseline and treatment. Raises ------ ValueError If `coloring` is not one of the recognized options. """ def _carrier_markets(summary: SimulationTables) -> pd.DataFrame: # Every pathclasses data column is a grand total (``gt_*``), so summing over # paths and booking classes and then dividing by the sample count yields # per-sample averages. path_id and booking_class are moved into the index # first so they are dropped by the groupby rather than summed as data. carrier_markets = ( summary.pathclasses.reset_index() .set_index(["path_id", "carrier", "orig", "dest", "booking_class"]) .groupby(["carrier", "orig", "dest"]) .sum() ) carrier_markets /= summary.n_total_samples carrier_markets.columns = carrier_markets.columns.str.removeprefix("gt_") # Markets with no sales give 0/0 = NaN here, which Altair omits from the plot. carrier_markets["avg_price"] = carrier_markets["revenue"] / carrier_markets["sold"] carrier_markets = carrier_markets.rename(columns={"revenue": "avg_revenue", "sold": "avg_sold"}) # market_shares() is wide (one column per carrier, indexed by orig/dest) and # in percent; reshape to long form and convert to a fraction for merging. shares = summary.market_shares(by="sold").rename_axis(columns="carrier").stack().div(100).rename("market_share") carrier_markets = carrier_markets.join(shares, how="left") return carrier_markets.reset_index() df = pd.merge( _carrier_markets(baseline), _carrier_markets(treatment), on=["carrier", "orig", "dest"], suffixes=("_baseline", "_treatment"), ) df["avg_revenue_change"] = df["avg_revenue_treatment"] - df["avg_revenue_baseline"] # A zero baseline revenue would give +/-inf; treat it as undefined instead. df["avg_revenue_change_pct"] = (df["avg_revenue_change"] / df["avg_revenue_baseline"]).replace( [np.inf, -np.inf], np.nan ) if coloring == "avg_revenue": color = alt.Color( "avg_revenue_treatment:Q", title="Avg Revenue", ) elif coloring == "change_revenue": color = alt.Color( "avg_revenue_change:Q", title="Δ Avg Revenue", scale=alt.Scale( scheme="redblue", # Use a diverging scheme domainMid=0, # Forces the center of the scheme to 0 ), ) elif coloring == "change_revenue_pct": color = alt.Color( "avg_revenue_change_pct:Q", title="Δ Avg Revenue %", scale=alt.Scale( scheme="redblue", # Use a diverging scheme domainMid=0, # Forces the center of the scheme to 0 ), legend=alt.Legend(format=".1%"), ) elif coloring is None: color = alt.Color("carrier:N", title="Carrier") else: raise ValueError(f"Unknown coloring {coloring}") chart = alt.Chart(df) tooltips = [ alt.Tooltip("carrier", title="Carrier"), alt.Tooltip("orig", title="Origin"), alt.Tooltip("dest", title="Destination"), alt.Tooltip("avg_sold_baseline", title="Avg Sold (Baseline)", format=".1f"), alt.Tooltip("avg_sold_treatment", title="Avg Sold (Treatment)", format=".1f"), alt.Tooltip("avg_price_baseline", title="Avg Price (Baseline)", format="$.2f"), alt.Tooltip("avg_price_treatment", title="Avg Price (Treatment)", format="$.2f"), alt.Tooltip("avg_revenue_baseline", title="Avg Revenue (Baseline)", format="$.3s"), alt.Tooltip("avg_revenue_treatment", title="Avg Revenue (Treatment)", format="$.3s"), alt.Tooltip("avg_revenue_change", title="Δ Avg Revenue", format="$.3s"), alt.Tooltip("avg_revenue_change_pct", title="Δ Avg Revenue %", format=".2%"), alt.Tooltip("market_share_baseline", title="Market Share (Baseline)", format=".1%"), alt.Tooltip("market_share_treatment", title="Market Share (Treatment)", format=".1%"), ] lines = chart.mark_rule(strokeWidth=strokeWidth, strokeOpacity=strokeOpacity).encode( x=alt.X("avg_sold_baseline", scale=alt.Scale(zero=False), title="Avg Sold"), x2="avg_sold_treatment", y=alt.Y("avg_price_baseline", scale=alt.Scale(zero=False), title="Avg Price"), y2=alt.Y2("avg_price_treatment"), color=color, tooltip=tooltips, ) points = chart.mark_point( filled=True, opacity=opacity, fillOpacity=fillOpacity, strokeOpacity=strokeOpacity ).encode( x=alt.X("avg_sold_treatment", scale=alt.Scale(zero=False), title="Avg Sold"), y=alt.Y("avg_price_treatment", scale=alt.Scale(zero=False), title="Avg Price"), size=alt.Size( "market_share_treatment:Q", title="Market Share", scale=alt.Scale(range=size_range), legend=alt.Legend(format=".0%"), ), color=color, tooltip=tooltips, ) return ( (points + lines) .properties(width=facet_width, height=facet_height) .facet("carrier", columns=facet_columns) .interactive() )