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