Source code for passengersim.summaries.carriers

from __future__ import annotations

from collections import defaultdict
from typing import TYPE_CHECKING, Literal

import pandas as pd

from passengersim.database import common_queries
from passengersim.reporting import report_figure

from .generic import (
    DatabaseTableItem,
    GenericSimulationTables,
    SimulationTableItem,
)
from .tools import aggregate_by_concat_dataframe

if TYPE_CHECKING:
    import altair as alt

    from passengersim import Simulation

    from . import SimulationTables


[docs] def extract_carriers(sim: Simulation) -> pd.DataFrame: """Extract carrier-level summary data from a Simulation.""" eng = sim.eng num_samples = eng.num_trials_completed * (eng.num_samples - eng.burn_samples) carrier_asm = defaultdict(float) carrier_rpm = defaultdict(float) carrier_leg_lf = defaultdict(float) carrier_leg_count = defaultdict(float) carrier_local_leg_pax = defaultdict(float) carrier_total_leg_pax = defaultdict(float) for leg in eng.legs: carrier_name = leg.carrier.name carrier_asm[carrier_name] += leg.distance * leg.capacity * num_samples carrier_rpm[carrier_name] += leg.distance * leg.gt_sold carrier_leg_lf[carrier_name] += leg.gt_sold / (leg.capacity * num_samples) carrier_leg_count[carrier_name] += 1 carrier_local_leg_pax[carrier_name] += leg.gt_sold_local carrier_total_leg_pax[carrier_name] += leg.gt_sold carrier_data = [] for carrier in sim.eng.carriers: avg_rev = carrier.gt_revenue / num_samples rpm = carrier_rpm[carrier.name] / num_samples avg_leg_lf = 100 * carrier_leg_lf[carrier.name] / max(carrier_leg_count[carrier.name], 1) # Add up total ancillaries tot_anc_rev = 0.0 for anc in carrier.ancillaries: tot_anc_rev += anc.price * anc.sold gt_cp_sold = carrier.gt_cp_sold gt_cp_revenue = carrier.gt_cp_revenue carrier_data.append( { "carrier": carrier.name, "control": carrier.control, "avg_rev": avg_rev, "avg_sold": carrier.gt_sold / num_samples, "truncation_rule": carrier.truncation_rule, "avg_leg_lf": avg_leg_lf, "asm": carrier_asm[carrier.name] / num_samples, "rpm": rpm, "ancillary_rev": tot_anc_rev, "avg_local_leg_pax": carrier_local_leg_pax[carrier.name] / num_samples, "avg_total_leg_pax": carrier_total_leg_pax[carrier.name] / num_samples, "cp_sold": gt_cp_sold / num_samples, "cp_revenue": gt_cp_revenue / num_samples, "rm_system": carrier.metadata.get("rm_system", {}).get("name"), } ) if len(carrier_data) == 0: return None return pd.DataFrame(carrier_data).set_index("carrier")
[docs] def aggregate_carriers(summaries: list[SimulationTables]) -> pd.DataFrame | None: """Aggregate leg-level summaries.""" table_avg = [] for s in summaries: frame = s._raw_carriers if frame is not None: # The keys in the set_index below represent qualitative string attributes that should be # consistent across all the tables we are collecting to aggregate. We will group by these # attributes and average the numeric values within each group, becase getting the # "average" of these string attributes doesn't make sense numerically. But conceptually # the average of strings that are all the same is just that string. table_avg.append(frame.set_index(["control", "truncation_rule", "rm_system"], append=True)) n = len(table_avg) while len(table_avg) > 1: table_avg[0] = table_avg[0].add(table_avg.pop(1), fill_value=0) if table_avg: table_avg[0] /= n return table_avg[0].reset_index(["control", "truncation_rule", "rm_system"]) return None
[docs] def extract_carrier_history2(sim: Simulation) -> pd.DataFrame | None: """Extract carrier_history from the Carrier class.""" combined_data = [] for cxr in sim.eng.carriers: hist = cxr.get_carrier_history() combined_data += hist if len(combined_data) == 0: return None df = pd.DataFrame.from_dict(combined_data) df = df.set_index(["trial", "sample", "carrier"]) return df
[docs] def extract_forecast_accuracy(sim: Simulation) -> pd.DataFrame | None: """Extract forecast accuracy from the Carrier class.""" combined_data = [] for cxr in sim.eng.carriers: hist = cxr.get_forecast_accuracy() combined_data += hist if len(combined_data) == 0: return None df = pd.DataFrame.from_dict(combined_data) df = df.set_index(["trial", "sample", "carrier", "booking_class", "timeframe"]).reset_index() return df
[docs] def extract_spill(sim: Simulation) -> pd.DataFrame | None: """Extract forecast accuracy from the Carrier class.""" combined_data = [] for cxr in sim.eng.carriers: data = cxr.get_spill_counters() combined_data += data if len(combined_data) == 0: return None df = pd.DataFrame.from_dict(combined_data) # df = df.set_index(["carrier", "booking_class"]).reset_index() return df
[docs] def aggregate_spill(summaries: list[SimTabCarriers]) -> pd.DataFrame | None | Exception: """Add spill counts across trials, matching rows by carrier and booking class. Row positions can't be used to line up the trials, because a first-choice class seen in only some trials shifts every row after it. Adding by position would also concatenate the text labels instead of keeping them as keys. Parameters ---------- summaries : list[SimTabCarriers] The trial summaries to combine. Returns ------- pandas.DataFrame or None or Exception One row for each carrier and booking class seen in any trial, in order of first appearance. Returns None if no trial has spill data, or the stored exception if a trial failed to produce the table. """ frames = [] for summary in summaries: frame = summary._raw_spill if isinstance(frame, Exception): return frame if frame is not None: frames.append(frame) if not frames: return None return pd.concat(frames, ignore_index=True).groupby(["carrier", "booking_class"], as_index=False, sort=False).sum()
[docs] class SimTabCarriers(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. """ carriers: pd.DataFrame = SimulationTableItem( aggregation_func=aggregate_carriers, extraction_func=extract_carriers, computed_fields={ "avg_price": "avg_rev / avg_sold", "yield": "avg_rev / rpm", "rasm": "avg_rev / asm", "sys_lf": "100.0 * rpm / asm", "local_pct_leg_pax": "100.0 * avg_local_leg_pax / avg_total_leg_pax", "local_pct_bookings": "100.0 * avg_local_leg_pax / avg_sold", }, doc="Carrier-level summary data.", ) carrier_history: pd.DataFrame | None = DatabaseTableItem( aggregation_func=aggregate_by_concat_dataframe("carrier_history"), query_func=common_queries.carrier_history, doc="Carrier-level summary data from each sample.", ) # TODO: the `carrier_history2` should be renamed `carrier_history`. Users should still # be able to call for `carrier_history2` and receive back this dataframe but also # get a deprecation warning. carrier_history2: pd.DataFrame | None = SimulationTableItem( aggregation_func=aggregate_by_concat_dataframe("carrier_history2"), extraction_func=extract_carrier_history2, doc="Carrier-level summary data from each sample, new version with counters in CoreCarrier.", ) forecast_accuracy: pd.DataFrame | None = SimulationTableItem( aggregation_func=aggregate_by_concat_dataframe("forecast_accuracy"), extraction_func=extract_forecast_accuracy, doc="Summary of forecast history, based on UA's EDGAR approach", ) spill: pd.DataFrame | None = SimulationTableItem( aggregation_func=aggregate_spill, extraction_func=extract_spill, doc="SWhat did the customer choose, given their first choice?", ) def _fig_carrier_attribute( self, raw_df: bool, load_measure: str, measure_name: str, measure_format: str = ".2f", orient: Literal["h", "v"] = "h", title: str | None = None, also_df: bool = False, ) -> alt.Chart | pd.DataFrame | tuple[alt.Chart, pd.DataFrame]: if "rm_system" not in self.carriers.columns: # TODO: remove this once no longer using older cached data df = self.carriers.reset_index()[["carrier", load_measure]].assign(rm_system="Unknown") else: df = self.carriers.reset_index()[["carrier", load_measure, "rm_system"]] if raw_df: return df import altair as alt chart = alt.Chart(df) if orient == "v": bars = chart.mark_bar().encode( x=alt.X("carrier:N", title="Carrier"), y=alt.Y(f"{load_measure}:Q", title=measure_name, axis=alt.Axis(format=measure_format)).stack("zero"), color=alt.Color("rm_system:N", title="RM System"), tooltip=[ alt.Tooltip("carrier", title="Carrier"), alt.Tooltip("rm_system", title="RM System"), alt.Tooltip(f"{load_measure}:Q", title=measure_name, format=measure_format), ], ) text = chart.mark_text(dx=0, dy=3, color="white", baseline="top").encode( x=alt.X("carrier:N", title="Carrier"), y=alt.Y(f"{load_measure}:Q", title=measure_name, axis=alt.Axis(format=measure_format)).stack("zero"), text=alt.Text(f"{load_measure}:Q", format=measure_format), ) else: bars = chart.mark_bar().encode( y=alt.Y("carrier:N", title="Carrier"), x=alt.X(f"{load_measure}:Q", title=measure_name, axis=alt.Axis(format=measure_format)).stack("zero"), color=alt.Color("rm_system:N", title="RM System"), tooltip=[ alt.Tooltip("carrier", title="Carrier"), alt.Tooltip("rm_system", title="RM System"), alt.Tooltip(f"{load_measure}:Q", title=measure_name, format=measure_format), ], ) text = chart.mark_text(dx=-5, dy=0, color="white", baseline="middle", align="right").encode( y=alt.Y("carrier:N", title="Carrier"), x=alt.X(f"{load_measure}:Q", title=measure_name, axis=alt.Axis(format=measure_format)).stack("zero"), text=alt.Text(f"{load_measure}:Q", format=measure_format), ) fig = ( (bars + text) .properties( width=500, height=10 + 20 * len(df), ) .configure_axis( labelFontSize=12, titleFontSize=12, ) .configure_legend( titleFontSize=12, labelFontSize=15, ) ) if title: fig.title = title if also_df: return fig, df return fig
[docs] @report_figure def fig_carrier_load_factors( self, load_measure: Literal["sys_lf", "avg_leg_lf"] = "sys_lf", *, raw_df: bool = False, also_df: bool = False, title: str | None = "_default_", ): measure_name = "System Load Factor" if load_measure == "sys_lf" else "Leg Load Factor" return self._fig_carrier_attribute( raw_df, load_measure, measure_name, title=f"Carrier {measure_name}s" if title == "_default_" else title, also_df=also_df, )
[docs] @report_figure def fig_carrier_revenues( self, *, raw_df: bool = False, also_df: bool = False, title: str | None = "Carrier Revenues" ): return self._fig_carrier_attribute(raw_df, "avg_rev", "Average Revenue", "$.4s", title=title, also_df=also_df)
[docs] @report_figure def fig_carrier_yields(self, *, raw_df: bool = False, also_df: bool = False, title: str | None = "Carrier Yields"): """Generate a figure showing carrier yields. Notes ----- Yield is defined as revenue per revenue passenger-mile. It differs from RASM (revenue per available seat mile) in that it only considers revenue and miles from paying passengers, If a seat is flown empty, it does not generate revenue or contribute to RPM, so it does not affect yield, but it does reduce RASM since it contributes to ASM. Yield is often considered a better measure of the price level that a carrier is achieving, while RASM is a better measure of overall revenue efficiency. Both measures are useful for understanding carrier performance, and they can sometimes move in different directions, so it's helpful to look at both. """ return self._fig_carrier_attribute(raw_df, "yield", "Average Yield", "$.4f", title=title, also_df=also_df)
[docs] @report_figure def fig_carrier_rasm( self, *, raw_df: bool = False, also_df: bool = False, title: str | None = "Carrier Revenue per Available Seat Mile (RASM)", ): return self._fig_carrier_attribute( raw_df, "rasm", "Revenue per Available Seat Mile", "$.4f", title=title, also_df=also_df, )
[docs] @report_figure def fig_carrier_total_bookings( self: SimulationTables, *, raw_df: bool = False, also_df: bool = False, title: str | None = "Carrier Total Bookings", ): return self._fig_carrier_attribute(raw_df, "avg_sold", "Total Bookings", ".4s", title=title, also_df=also_df)
[docs] @report_figure def fig_carrier_local_share( self, load_measure: Literal["bookings", "leg_pax"] = "bookings", *, raw_df: bool = False, also_df: bool = False, title: str | None = "_default_", ): measure_name = "Local Percent of Bookings" if load_measure == "bookings" else "Local Percent of Leg Passengers" m = "local_pct_bookings" if load_measure == "bookings" else "local_pct_leg_pax" if title == "_default_": title = f"Carrier {measure_name}" return self._fig_carrier_attribute(raw_df, m, measure_name, title=title, also_df=also_df)
[docs] @report_figure def fig_carrier_mileage( self, *, raw_df: bool = False, also_df: bool = False ) -> alt.Chart | pd.DataFrame | tuple[alt.Chart, pd.DataFrame]: """ Figure showing mileage by carrier. ASM is available seat miles, and RPM is revenue passenger miles. Both measures are reported as the average across all non-burned samples. Parameters ---------- raw_df : bool, default False Return the raw data for this figure as a pandas DataFrame, instead of generating the figure itself. report : xmle.Reporter, optional Also append this figure to the given report. trace : pd.ExcelWriter, optional Also write the data from this figure to the given Excel file. """ df = ( self.carriers.reset_index()[["carrier", "asm", "rpm"]] .set_index("carrier") .rename_axis(columns="measure") .unstack() .to_frame("value") .reset_index() ) if raw_df: return df import altair as alt chart = alt.Chart(df, title="Carrier Loads") bars = chart.mark_bar().encode( x=alt.X("carrier:N", title="Carrier"), y=alt.Y("value", stack=None, title="miles"), color="measure", tooltip=["carrier", "measure", alt.Tooltip("value", format=".4s")], ) text = chart.mark_text( dx=0, dy=5, color="white", baseline="top", ).encode( x=alt.X("carrier:N"), y=alt.Y("value").stack(None), text=alt.Text("value:Q", format=".4s"), ) fig = ( (bars + text) .properties( width=400, height=300, ) .configure_axis( labelFontSize=12, titleFontSize=12, ) .configure_legend( titleFontSize=12, labelFontSize=15, ) ) if also_df: return fig, df return fig
[docs] def fig_carrier_revenue_distribution(self, *, raw_df=False, also_df=False): """Figure showing the distribution of carrier revenues. Parameters ---------- raw_df : bool, default False Return the raw data for this figure as a pandas DataFrame, instead of generating the figure itself. This is not implemented yet and will raise an error if set. also_df: bool, default False Return the raw data for this figure as a pandas DataFrame, in addition to the figure itself. This is not implemented yet, and will be silently ignored if set. """ if raw_df: raise NotImplementedError("Raw data not available for this figure.") import altair as alt fig = ( alt.Chart(self.carrier_history2.reset_index()) .transform_density( "revenue", groupby=["carrier"], as_=["revenue", "density"], ) .mark_area() .encode( x=alt.X("revenue:Q", axis=alt.Axis(title="Revenue", format="$.3s")), y=alt.Y("density:Q", title="Density", axis=alt.Axis(labels=False)), color="carrier:N", ) .facet( "carrier:N", title="Revenue Distribution by Carrier", ) ) return fig
[docs] def fig_carrier_head_to_head_revenue( self, x_carrier: str | None = None, y_carrier: str | None = None, *, raw_df: bool = False, mean_adjusted: bool = True, ) -> alt.LayerChart | alt.RepeatChart | pd.DataFrame: """ Figure comparing carrier revenues head-to-head. Parameters ---------- x_carrier, y_carrier : str, optional The carrier to plot on the x- and y-axis, respectively. Omit both to generate a scatter plot matrix comparing all carriers. raw_df : bool, default False Return the raw data for this figure as a pandas DataFrame, instead of generating the figure itself. mean_adjusted : bool, default True If True, adjust revenues by dividing by the mean revenue for each carrier, so that the plot shows percentage of mean revenue. If False, use raw revenues, which is generally only useful for analyzing symmetric networks, such as 3MKT. Returns ------- alt.LayerChart | alt.RepeatChart | pd.DataFrame A single head-to-head chart or an all-carrier scatter plot matrix. With ``raw_df=True``, return one row per trial and sample, with a revenue column for each selected carrier. Raises ------ ValueError If only one carrier is specified, a named carrier is absent from the history, or the history contains no carriers. """ import altair as alt if (x_carrier is None) != (y_carrier is None): raise ValueError("Specify both x_carrier and y_carrier, or omit both for a scatter plot matrix.") revenue = self.carrier_history2["revenue"] carriers = revenue.index.get_level_values("carrier").unique().tolist() if not carriers: raise ValueError("Carrier history contains no carriers.") matrix = x_carrier is None if not matrix: for carrier in (x_carrier, y_carrier): if carrier not in carriers: raise ValueError(f"Carrier {carrier!r} is not in carrier history.") carriers = list(dict.fromkeys([x_carrier, y_carrier])) revenue = revenue[revenue.index.get_level_values("carrier").isin(carriers)] axis_label_text = "Percentage of Mean Revenue" axis_format = "%" if mean_adjusted: revenue = revenue / revenue.groupby(level="carrier").transform("mean") else: axis_label_text = "Revenue" axis_format = "$.2s" rng = revenue.min(), revenue.max() # Unstack aligns observations by trial and sample, even with missing rows. df = revenue.unstack("carrier").reset_index() if raw_df: return df # Vega field references interpret punctuation as access paths unless escaped. escape = str.maketrans({char: "\\" + char for char in "\\.[]'\""}) fields = {carrier: carrier.translate(escape) for carrier in carriers} x = alt.X(field=alt.repeat("column") if matrix else fields[x_carrier], type="quantitative") y = alt.Y(field=alt.repeat("row") if matrix else fields[y_carrier], type="quantitative") x = x.axis(format=axis_format).scale(zero=False) y = y.axis(format=axis_format).scale(zero=False) if not matrix: x = x.title(f"{x_carrier} {axis_label_text}") y = y.title(f"{y_carrier} {axis_label_text}") # Identical endpoints in every carrier column draw y=x in each panel. diag = ( alt.Chart(pd.DataFrame({carrier: rng for carrier in carriers})) .mark_line(color="red", opacity=0.3) .encode(x=x, y=y) ) fig = (alt.Chart(df).mark_circle(opacity=0.3).encode(x=x, y=y) + diag).interactive() if matrix: return ( fig.properties(width=150, height=150) .repeat(row=list(fields.values()), column=list(fields.values())) .properties(title=axis_label_text) ) return fig