Source code for passengersim.summaries.cabins
#
# Data for analyzing multi-cabin
#
# AlanW, October 2025
# (C) PassengerSIM LLC
#
from __future__ import annotations
from typing import TYPE_CHECKING
import pandas as pd
from .generic import (
GenericSimulationTables,
SimulationTableItem,
)
from .tools import aggregate_by_concat_dataframe
if TYPE_CHECKING:
import altair as alt
from passengersim import Simulation
[docs]
class SimTabCabins(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.
"""
cabins: pd.DataFrame | None = SimulationTableItem(
aggregation_func=aggregate_by_concat_dataframe("cabins"),
extraction_func=extract_cabins,
doc="Cabin-level summary data from each sample",
)
[docs]
def fig_cabin_load_factors(self, raw_df: bool = False) -> alt.VConcatChart | pd.DataFrame:
"""Plot distance-weighted load factors by carrier and cabin.
Parameters
----------
raw_df : bool, default False
Return aggregated cabin data instead of a chart.
Returns
-------
altair.VConcatChart or pandas.DataFrame
One panel per recorded cabin, or the data from `get_cabins_df`.
Raises
------
ValueError
If cabin data is missing or empty.
"""
import altair as alt
all_cabins_df = self.get_cabins_df()
if raw_df:
return all_cabins_df
fig = alt.vconcat()
for cabin in all_cabins_df["cabin"].unique():
cabin_df = all_cabins_df[all_cabins_df["cabin"] == cabin]
base = alt.Chart(cabin_df).encode(
y=alt.Y("carrier:N", title=""),
x=alt.X(
"load_factor:Q", axis=alt.Axis(format=".0%"), scale=alt.Scale(domain=[0, 1]), title="Load Factor"
),
color="carrier:N",
tooltip=alt.Tooltip("load_factor", format=".1%"),
text=alt.Text("load_factor:Q", format=".1%"),
)
z = alt.layer(
base.mark_bar(),
base.mark_text(color="black", baseline="top", dx=20, dy=-5),
).facet(row=alt.Row("carrier:N", title=""), title=alt.TitleParams(text=f"Cabin: {cabin}", anchor="middle"))
fig &= z
return fig
[docs]
def get_cabins_df(self) -> pd.DataFrame:
"""Aggregate recorded cabin observations by carrier and cabin.
Returns
-------
pandas.DataFrame
Carrier and cabin identifiers, total available seat miles (``asm``),
revenue passenger miles (``rpm``), seats sold, revenue, and load factor.
Totals include all recorded samples. Load factor is RPM divided by
ASM and is undefined (NaN) when ASM is zero.
Raises
------
ValueError
If cabin data is missing or empty.
"""
if self.cabins is None or self.cabins.empty:
raise ValueError("No cabin data available")
# Weight observations by distance before combining flights and samples.
observations = self.cabins.assign(
asm=self.cabins["distance"] * self.cabins["capacity"],
rpm=self.cabins["distance"] * self.cabins["sold"],
)
cabin_df = (
observations.groupby(["carrier", "cabin"])
.agg({"asm": "sum", "rpm": "sum", "sold": "sum", "revenue": "sum"})
.reset_index()
)
cabin_df["load_factor"] = cabin_df["rpm"] / cabin_df["asm"].where(cabin_df["asm"] != 0)
return cabin_df