SimulationTables¶

class passengersim.summaries.SimulationTables(data: dict[str, pd.DataFrame] = None, *, config: Config | None = None, cnx: Database | None = None, sim: Simulation | None = None, n_total_samples: int = 0, items: Collection[str] = (), callback_data: CallbackData | None = None)[source]¶

Bases: SimTabPathLegs, SimTabDemandToCome, SimTabBidPriceHistory, SimTabCabins, SimTabCarriers, SimTabContinuousPricingSegmentation, SimTabDemands, SimTabDisplacementHistory, SimTabFareClassMix, SimTabForecasts, SimTabLegBuckets, SimTabPaths, SimTabSegByTimeframe, SimTabSegmentationDetail, SimTabServices, SimTabLegs, SimTabLocalAndFlowYields, SimTabPathClasses, 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.

Methods

`__init__`([data, config, cnx, sim, ...])
`aggregate`(summaries)	Aggregate multiple summary tables.
`aggregate_demand_history`([by_segment])	Total demand by sample, aggregated over all markets.
`connecting_paths_by_place`()	Get the number of paths that connect in each place.
`dashboard`()	Return a dashboard object for this SimulationTables instance.
`extract`(sim[, items])	Extract summary data from a Simulation.
`fig_bid_price_history`([by_carrier, ...])
`fig_bookings_by_timeframe`(args, *kwargs)
`fig_cabin_load_factors`([raw_df])
`fig_carrier_head_to_head_revenue`(x_carrier, ...)	Figure comparing carrier revenues head-to-head.
`fig_carrier_load_factors`([load_measure, ...])
`fig_carrier_local_share`([load_measure, ...])
`fig_carrier_mileage`(*[, raw_df, also_df])	Figure showing mileage by carrier.
`fig_carrier_rasm`(*[, raw_df, also_df, title])
`fig_carrier_revenue_distribution`(*[, ...])	Figure showing the distribution of carrier revenues.
`fig_carrier_revenues`(*[, raw_df, also_df, title])
`fig_carrier_total_bookings`(*[, raw_df, ...])
`fig_carrier_yields`(*[, raw_df, also_df, title])	Generate a figure showing carrier yields.
`fig_cp_segmentation`(*[, raw_df, also_df])
`fig_demand_segmentation_distribution`([x, y, ...])	Create a scatter plot showing the distribution of demands by segment.
`fig_displacement_history`([by_carrier, ...])
`fig_fare_class_mix`(*[, raw_df, also_df, ...])	Plot the fare class mix data.
`fig_leg_bid_price_detail_rake`(*, leg_id[, ...])
`fig_leg_bid_price_history`(carrier, *, measure)
`fig_leg_booking_detail_rake`(*, leg_id[, ...])
`fig_leg_forecasts`([by_leg_id, by_class, of, ...])
`fig_leg_load_factor_distribution`([...])	Figure showing the distribution of leg load factors.
`fig_leg_load_v_distance`(*[, orig, dest, ...])
`fig_leg_load_v_local`(*[, orig, dest, place, ...])	Figure showing the relationship between leg load factor and local share.
`fig_leg_local_share_distribution`([...])	Figure showing the distribution of leg local shares.
`fig_od_fare_class_mix`(orig, dest, *[, ...])	Plot the fare class mix data for a specific origin-destination pair.
`fig_path_forecasts`([by_path_id, by_class, ...])
`fig_segmentation_by_timeframe`(metric, *[, ...])
`fig_segmentation_detail`(*[, by_carrier, ...])	Plot the segmentation detail data.
`fig_select_leg_analysis`(leg_id[, metric, ...])	Origins, destinations, and booking classes for passengers on leg(s).
`file_info`()	Return information about the file store.
`from_file`(filename[, read_latest, lazy])	Load the object from a file.
`from_pickle`(filename[, read_latest])	Load the object from a pickle file.
`get_cabins_df`()	Get all the cabine data into a dataframe
`metadata`([key])	Return a metadata value.
`path_identifier`(path_id)	Get a human-readable identifying string for a path.
`remove_data`(keys)	Remove data from the summary tables.
`run_queries`([cnx, items, scenario, burn_samples])	Query summary data from a Database.
`save`(filename, *[, timestamp, make_dirs, ...])	Save the object to a set of files.
`select_leg_analysis`(leg_id)	Select path_legs for a specific leg.
`subclasses`()	Return a list of all concrete subclasses.
`to_file`(filename[, add_timestamp_ext, ...])	Write simulation tables to a file.
`to_html`(filename, *[, cfg, make_dirs, ...])	Write simulation tables report summary to html.
`to_pickle`(filename[, add_timestamp_ext, ...])	Save to a pickle file.
`to_xlsx`(filename)	Write simulation tables to excel.

Attributes

`bid_price_history`	Bid price history for each carrier.
`cabins`	Cabin-level summary data from each sample
`callback_data`
`carrier_history`	Carrier-level summary data from each sample.
`carrier_history2`	Carrier-level summary data from each sample, new version with counters in CoreCarrier.
`carriers`	Carrier-level summary data.
`config`
`cp_segmentation`	Continuous pricing segmentation summary data.
`demand_history`	Demand-level summary data from each sample.
`demand_to_come`	Demand-to-come data.
`demand_to_come_summary`	Demand-to-come summary data.
`demands`	Demand-level summary data.
`displacement_history`	Displacement cost history for each carrier.
`edgar`	EDGAR forecast accuracy measurement.
`fare_class_mix`	Fare class mix data.
`forecast_accuracy`	Summary of forecast history, based on UA's EDGAR approach
`leg_bid_price_detail`
`leg_booking_detail`
`leg_defs`	A DataFrame containing the definitions of the legs in the simulation.
`leg_detail`	Sample / DCP level detail for legs - a lot of data
`leg_forecasts`	Leg forecasts.
`legbuckets`	Leg-Bucket summary data.
`legs`	Leg-level summary data.
`legs_`	A DataFrame containing the leg summary data, merged with the leg definitions.
`local_and_flow_yields`	Local and flow yields.
`local_fraction_by_place`	The local share of passengers by carrier and place.
`market_segmentation`	Computed DataFrame with market segmentation data.
`path_forecasts`	Path forecasts.
`path_legs`	Legs on each path.
`pathclasses`	Path-Class summary data.
`paths`	Path-level summary data.
`segmentation_by_timeframe`	Segmentation-by-timeframe summary data.
`segmentation_detail`	Segmentation detail.
`services`	Service-level summary data, aggregated by carrier and operating leg o-d.
`cnx`	Database connection for the Simulation run.
`sim`	Simulation object for the Simulation run.
`n_total_samples`	Total number of sample departures simulated to create these summaries.
`meta_summaries`	Summaries that were aggregated to create this summary.

dashboard()[source]¶: Return a dashboard object for this SimulationTables instance.

classmethod aggregate(summaries: Collection[GenericSimulationTables]) → Self¶: Aggregate multiple summary tables.

aggregate_demand_history(by_segment: bool = True) → Series¶

Total demand by sample, aggregated over all markets.

Parameters:

by_segment : bool, default True¶: Aggregate by segment. If false, segments are also aggregated.

Returns:

pandas.Series – Total demand, indexed by trial, sample, and segment (e.g. business/leisure).

bid_price_history : pd.DataFrame¶: Bid price history for each carrier.

cabins : pd.DataFrame | None¶: Cabin-level summary data from each sample

property callback_data¶

carrier_history : pd.DataFrame | None¶: Carrier-level summary data from each sample.

carrier_history2 : pd.DataFrame | None¶: Carrier-level summary data from each sample, new version with counters in CoreCarrier.

carriers : pd.DataFrame¶: Carrier-level summary data.

property config¶

connecting_paths_by_place() → Series¶

Get the number of paths that connect in each place.

The index of the result are the places that are layovers on one or more connecting paths. The values are the number of paths that connect in that place (i.e. the number of paths that have a leg with that place as the origin, but are not the first leg of the path). The series is sorted in descending order of the number of connecting paths.

Returns:: pandas.Series

cp_segmentation : pd.DataFrame¶: Continuous pricing segmentation summary data.

demand_history : pd.DataFrame | None¶: Demand-level summary data from each sample.

demand_to_come : pd.DataFrame¶: Demand-to-come data.

demand_to_come_summary : pd.DataFrame¶: Demand-to-come summary data.

demands : pd.DataFrame¶: Demand-level summary data.

displacement_history : pd.DataFrame¶: Displacement cost history for each carrier.

edgar : pd.DataFrame¶: EDGAR forecast accuracy measurement.

classmethod extract(sim: Simulation, items: Collection[str] = ()) → Self¶: Extract summary data from a Simulation.

fare_class_mix : pd.DataFrame¶: Fare class mix data.

fig_bid_price_history(by_carrier: bool | str = True, show_stdev: float | bool | None = None, cap: 'some' | 'zero' | None = None, *, raw_df=False, trial: int | None = None, title: str | None = 'Bid Price History', also_df: bool = False) → alt.Chart | pd.DataFrame | tuple[alt.Chart, pd.DataFrame]¶

fig_bookings_by_timeframe(*args, **kwargs)¶

fig_cabin_load_factors(raw_df: bool = False) → alt.Chart | pd.DataFrame¶

fig_carrier_head_to_head_revenue(x_carrier: str, y_carrier: str, *, raw_df=False, mean_adjusted: bool = True)¶

Figure comparing carrier revenues head-to-head.

Parameters:

x_carrier : str¶: The carrier to plot on the x- and y-axis, respectively.
y_carrier : str¶: The carrier to plot on the x- and y-axis, respectively.
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.Chart | pd.DataFrame – The Altair chart object, or the raw data as a pandas DataFrame

fig_carrier_load_factors(load_measure: 'sys_lf' | 'avg_leg_lf' = 'sys_lf', *, raw_df: bool = False, also_df: bool = False, title: str | None = '_default_')¶

fig_carrier_local_share(load_measure: 'bookings' | 'leg_pax' = 'bookings', *, raw_df: bool = False, also_df: bool = False, title: str | None = '_default_')¶

fig_carrier_mileage(*, 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.

fig_carrier_rasm(*, raw_df: bool = False, also_df: bool = False, title: str | None = 'Carrier Revenue per Available Seat Mile (RASM)')¶

fig_carrier_revenue_distribution(*, 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.

fig_carrier_revenues(*, raw_df: bool = False, also_df: bool = False, title: str | None = 'Carrier Revenues')¶

fig_carrier_total_bookings(*, raw_df: bool = False, also_df: bool = False, title: str | None = 'Carrier Total Bookings')¶

fig_carrier_yields(*, 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.

fig_cp_segmentation(*, raw_df: bool = False, also_df: bool = False) → alt.Chart | tuple[alt.Chart, pd.DataFrame] | pd.DataFrame¶

fig_demand_segmentation_distribution(x: str | None = None, y: str | None = None, *, raw_df: bool = False, also_df: bool = False) → Chart | DataFrame | tuple[Chart, DataFrame]¶

Create a scatter plot showing the distribution of demands by segment.

Parameters:

x : str, optional¶: The column to use for the x-axis. If not provided, the first segment column will be used.
y : str, optional¶: The column to use for the y-axis. If not provided, the second segment column will be used if there are two segments, otherwise ‘total’ will be used.
raw_df : bool, default False¶: If True, return the raw DataFrame used to create the plot instead of the plot itself
also_df : bool, default False¶: If True, return a tuple of (plot, DataFrame) instead of just the plot

Returns:

alt.Chart or pd.DataFrame or tuple[alt.Chart, pd.DataFrame] – The scatter plot, the raw DataFrame, or both, depending on the parameters.

fig_displacement_history(by_carrier: bool | str = True, show_stdev: float | bool | None = None, *, raw_df=False, also_df: bool = False, trial: int | None = None, title: str | None = 'Displacement Cost History')¶

fig_fare_class_mix(*, raw_df: bool = False, also_df: bool = False, label_threshold: float = 0.06, title: str | None = 'Fare Class Mix') → alt.Chart | pd.DataFrame | tuple[alt.Chart, pd.DataFrame]¶

Plot the fare class mix data.

Parameters:

raw_df : bool, optional¶: If True, return the raw dataframe instead of the figure.
also_df : bool, optional¶: If True, return the dataframe as well as the figure.
label_threshold : float, optional¶: The threshold for displaying labels on the bars. Default is 0.06.

Returns:

alt.Chart or pd.DataFrame or tuple[alt.Chart, pd.DataFrame] – The fare class mix figure or dataframe.

fig_leg_bid_price_detail_rake(*, leg_id: int, raw_df: bool = False, color: str = '#6a3d9a', mean_color: str | None = '#ff7f00')¶

fig_leg_bid_price_history(carrier: str, *, measure: 'mean' | 'q10' | 'q25' | 'q50' | 'q75' | 'q90' | 'median', haul_category_labels: tuple[str, ...] | None = ('a. Short: ', 'b. Medium: ', 'c. Long: ', 'd. Longest: '), opacity: float = 0.25, max_rows: int = 5000) → alt.Chart¶

fig_leg_booking_detail_rake(*, leg_id: int, raw_df: bool = False, color: str = 'red')¶

fig_leg_forecasts(by_leg_id: bool | int = True, *, by_class: bool | str = True, of: 'mu' | 'sigma' | 'closed' | list['mu' | 'sigma' | 'closed'] = 'mu', raw_df=False)¶

fig_leg_load_factor_distribution(by_carrier: bool | str = True, breakpoints: Collection[int] = None, normalize: bool = False, *, raw_df: bool = False, also_df: bool = False) → alt.Chart | pd.DataFrame | tuple[alt.Chart, pd.DataFrame]¶

Figure showing the distribution of leg load factors.

Parameters:

by_carrier : bool or str, default True¶: If True, show the distribution by carrier. If a string, show the distribution for that carrier. If False, show the distribution aggregated over all carriers.
breakpoints : Collection[int, ...], default (25, 30, 35, 40, ..., 90, 95, 100)¶: The breakpoints for the load factor ranges, which represent the lowest load factor value in each bin. The first and last breakpoints are always bounded to 0 and 101, respectively; these bounds can be included explicitly or omitted to be included implicitly. Setting the top value to 101 ensures that the highest load factor value (100) is included in the last bin.
normalize : bool, default False¶: If True, normalize the frequency by the total number of legs for each carrier, so that the sum of the frequencies for each carrier is 1.
raw_df : bool, default False¶: Return the raw data for this figure as a pandas DataFrame, instead of generating the figure itself.
also_df : bool, default False¶: If True, return the raw data for this figure as a pandas DataFrame, in addition to the figure itself.

Returns:

alt.Chart or pd.DataFrame or tuple[alt.Chart, pd.DataFrame]

fig_leg_load_v_distance(*, orig: str | None = None, dest: str | None = None, place: str | None = None, carrier: str | None = None, raw_df: bool = False, also_df: bool = False, facet_columns: int | None = 2, beeswarm: int | tuple[int, float] = 0)¶

Figure showing the relationship between leg load factor and local share.

Parameters:

orig : str or None, default None¶: Filter the data to only include legs with this origin.
dest : str or None, default None¶: Filter the data to only include legs with this destination.
place : str or None, default None¶: Filter the data to only include legs with this origin or destination.
carrier : str or None, default None¶: Filter the data to only include legs operated by this carrier.
raw_df : bool, default False¶: If True, return the raw data for this figure as a pandas DataFrame, instead of generating the figure itself.
also_df : bool, default False¶: If True, return the raw data for this figure as a pandas DataFrame, in addition to the figure itself.
facet_columns : int or None, default 2¶: The number of columns to use for faceting the plot by carrier. If None, all facets will appear on one row.
select_leg : bool, default False¶: If True, return an interactive widget that allows the user to select specific legs and view their path_legs. This feature is experimental and may change without notice.

Returns:

alt.Chart or pd.DataFrame

fig_leg_local_share_distribution(by_carrier: bool | str = True, breakpoints: Collection[int] = None, normalize: bool = False, *, raw_df=False, also_df: bool = False) → alt.Chart | pd.DataFrame | tuple[alt.Chart, pd.DataFrame]¶

Figure showing the distribution of leg local shares.

The local share is the percentage of passengers on a leg that are local to the leg’s origin and destination (i.e. not connecting).

Parameters:

by_carrier : bool or str, default True¶: If True, show the distribution by carrier. If a string, show the distribution for that carrier. If False, show the distribution aggregated over all carriers.
breakpoints : Collection[int, ...], default (0, 10, 20, ..., 90, 100)¶: The breakpoints for the load factor ranges, which represent the lowest load factor value in each bin. The first and last breakpoints are always bounded to 0 and 101, respectively; these bounds can be included explicitly or omitted to be included implicitly. Setting the top value to 101 ensures that the highest load factor value (100) is included in the last bin.
normalize : bool, default False¶: If True, normalize the frequency by the total number of legs for each carrier, so that the sum of the frequencies for each carrier is 1.
raw_df : bool, default False¶: Return the raw data for this figure as a pandas DataFrame, instead of generating the figure itself.
also_df : bool, default False¶: If True, return the raw data for this figure as a pandas DataFrame, in addition to the figure itself.

Returns:

alt.Chart or pd.DataFrame

fig_od_fare_class_mix(orig: str, dest: str, *, raw_df=False, also_df: bool = False, label_threshold=0.06) → alt.Chart | pd.DataFrame | tuple[alt.Chart, pd.DataFrame]¶

Plot the fare class mix data for a specific origin-destination pair.

Parameters:

orig : str¶: The origin and destination airport codes.
dest : str¶: The origin and destination airport codes.
raw_df : bool, optional¶: If True, return the raw dataframe instead of the figure.
also_df : bool, optional¶: If True, return the dataframe as well as the figure.
label_threshold : float, optional¶: The threshold for displaying labels on the bars. Default is 0.06.

Returns:

alt.Chart or pd.DataFrame or tuple[alt.Chart, pd.DataFrame] – The fare class mix figure or dataframe.

fig_path_forecasts(by_path_id: bool | int = True, *, by_class: bool | str = True, of: 'mu' | 'sigma' | 'closed' | 'adj_price' = 'mu', raw_df: bool = False)¶

fig_segmentation_by_timeframe(metric: 'bookings' | 'revenue', *, by_carrier: bool | str = True, by_class: bool | str = False, raw_df: bool = False, also_df: bool = False, exclude_nogo: bool = True)¶

Plot the segmentation detail data.

Parameters:

by_carrier : bool or str, default True¶: If True, group by carrier. If a string, filter by carrier.
by_class : bool or str, default False¶: If True, group by booking class. If a string, filter by booking class.
orig : str, optional¶: Filter by origin.
dest : str, optional¶: Filter by destination.
raw_df : bool, default False¶: If True, return the raw dataframe instead of the figure.
also_df : bool, default False¶: If True, return the dataframe as well as the figure.

Returns:

alt.Chart or pd.DataFrame or tuple[alt.Chart, pd.DataFrame] – The segmentation detail figure or dataframe.

fig_select_leg_analysis(leg_id: int | ArrayLike[int], metric: 'bookings' | 'revenue' = 'bookings', *, raw_input: dict[str, pd.DataFrame] = None, width: int = 300)¶

Origins, destinations, and booking classes for passengers on leg(s).

Parameters:

leg_id : int | ArrayLike[int]¶: The leg_id(s) to select.
metric : {"bookings", "revenue"}, default "bookings"¶: The metric to display.
raw_input : dict[str, pd.DataFrame], optional¶: Precomputed raw input data from the select leg analysis method. If not provided, that method will be called to get the data.
width : int, default 300¶: The width of each chart panel.

Returns:

alt.Chart – An Altair chart object.

file_info()¶: Return information about the file store.

forecast_accuracy : pd.DataFrame | None¶: Summary of forecast history, based on UA’s EDGAR approach

classmethod from_file(filename: str | Path, read_latest: bool = True, lazy: bool = True)¶

Load the object from a file.

Parameters:

filename : str or Path-like¶: The filename to load the object from.
read_latest : bool, default True¶: If True, read the latest file matching the pattern.
lazy : bool, default True¶: If True, load the data lazily (as needed). Otherwise, load the data immediately.

classmethod from_pickle(filename: str | Path, read_latest: bool = True)¶

Load the object from a pickle file.

Parameters:

filename : str or Path-like¶: The filename to load the object from.
read_latest : bool, default True¶: If True, read the latest file matching the pattern.

get_cabins_df()¶: Get all the cabine data into a dataframe

property leg_bid_price_detail¶

property leg_booking_detail¶

property leg_defs¶

A DataFrame containing the definitions of the legs in the simulation.

This DataFrame is constructed from the leg definitions defined in the simulation config, and does not depend on the simulation results.

Returns:: pd.DataFrame

leg_detail : pd.DataFrame¶: Sample / DCP level detail for legs - a lot of data

leg_forecasts : pd.DataFrame¶: Leg forecasts.

legbuckets : pd.DataFrame¶: Leg-Bucket summary data.

legs : pd.DataFrame¶: Leg-level summary data.

property legs_¶

A DataFrame containing the leg summary data, merged with the leg definitions.

This DataFrame is constructed by merging the legs DataFrame with the leg_defs DataFrame, so it includes all the summary data for each leg, as well as all the attributes of each leg defined in the config.

Returns:: pd.DataFrame

local_and_flow_yields : pd.DataFrame¶: Local and flow yields.

property local_fraction_by_place : DataFrame¶

The local share of passengers by carrier and place.

The index of this DataFrame contains all possible places, and the columns contain the carriers.

For each carrier and place, this is the percentage of leg passengers on legs arriving or departing from that place that are local passengers (i.e. not connecting passengers). Passengers are considered connecting whether the connection is at this place, or at another place.

If a carrier does not operate any legs to or from a place, or if legs are operated but no passengers are booked (which probably indicates a config error), the local share is NaN.

Returns:: pd.DataFrame

property market_segmentation : DataFrame¶: Computed DataFrame with market segmentation data.

metadata(key: str = '')¶: Return a metadata value.

path_forecasts : pd.DataFrame¶: Path forecasts.

path_identifier(path_id: int) → str¶

Get a human-readable identifying string for a path.

Parameters:

path_id : int¶: The path_id to look up.

Returns:

str

path_legs : pd.DataFrame¶: Legs on each path.

pathclasses : pd.DataFrame¶: Path-Class summary data.

paths : pd.DataFrame¶: Path-level summary data.

remove_data(keys: Collection[str] | str) → Self¶

Remove data from the summary tables.

This can be used to reduce the size of the summary tables when saving to a file, or to remove sensitive data before sharing the summary tables.

Parameters:

keys : Collection[str] or str¶: The key(s) of the data to remove.

Returns:

Self – The summary tables object, with the specified data removed.

run_queries(cnx: Database = None, items: Collection[str] | None = None, *, scenario: str = None, burn_samples: int | None = None) → Self¶

Query summary data from a Database.

The requested items will be queried from the database and stored in this summary object. If the item is not available, an exception will be raised.

Parameters:

cnx : Database, optional¶: Database connection to use for querying.
items : Collection[str], optional¶: The items to query. If None, or if only “*” is given, then all available items will be queried.
scenario : str, optional¶: The scenario to use for querying.
burn_samples : int, optional¶: The number of burn samples to use for querying. If explicitly None, the burn_samples value from the configuration will be used if available, otherwise the default value of 100 will be used.

Save the object to a set of files.

This method will write both an HTML report on this simulation tables object and a “.pxsim” file allowing the content to be restored.

Parameters:

filename : Path-like¶: The file stem to use for writing files.
timestamp : float or time.struct_time or datetime, optional¶: The timestamp to use for the filenames. If not provided, the current time will be used.
make_dirs : bool or "git", default True¶: If True, create the parent directory for the files if it does not already exist. If the directory is created, it will be created with a .gitignore file to prevent accidental inclusion of output in Git repositories, unless the value is “git”, in which case no .gitignore file is created and the results will be eligible for inclusion in Git.
cfg : Config, optional¶: The configuration to use for the HTML report. If None, the configuration from the simulation object will be used if available.
extra_html : tuple, optional¶: Additional data to include in the HTML report. This argument is passed to to_html, see that function for more details.

Returns:

dict – A dictionary of filenames written, including the timestamp added.

segmentation_by_timeframe : pd.DataFrame¶: Segmentation-by-timeframe summary data.

segmentation_detail : pd.DataFrame¶: Segmentation detail.

select_leg_analysis(leg_id: int | ArrayLike[int]) → dict[str, pd.DataFrame]¶

Select path_legs for a specific leg.

Parameters:

leg_id : int¶: The leg_id(s) to select.

Returns:

dict[str, pd.DataFrame] – Keys include “orig”, “dest”, and “booking_class”. Values are DataFrames with columns “gt_sold” and “gt_revenue”.

property services : DataFrame¶

Service-level summary data, aggregated by carrier and operating leg o-d.

A ‘service’ is an aggregation of all legs sharing a unique combination of carrier, origin, and destination. This table aggregates data from the legs table to the service level.

classmethod subclasses() → list[type[GenericSimulationTables]]¶

Return a list of all concrete subclasses.

User defined subclasses (those not in the passengersim package) are at the front of the list, so they come first in MRO and thus can override native subclasses.

to_file(filename: str | Path, add_timestamp_ext: bool = True, *, preserve_config: bool = True, make_dirs: True | False | 'git' = True) → Path¶

Write simulation tables to a file.

Parameters:

filename : Path-like¶: The file to write.
add_timestamp_ext : bool, default True¶: Add a timestamp extension to the filename.
preserve_config : bool, default True¶: Preserve the config attribute in the saved object. This includes the entire network, and can potentially be a lot of data.
make_dirs : bool or "git", default True¶: If True, create the parent directory for the file if it does not already exist. If the directory is created, it will be created with a .gitignore file to prevent accidental inclusion of output in Git repositories, unless the value is “git”, in which case no .gitignore file is created and the results will be eligible for inclusion in Git.

Returns:

Path-like – The resolved filename for the saved outputs.

to_html(filename: str | Path, *, cfg: Config | None = None, make_dirs: bool = True, extra: tuple = (), add_timestamp: bool = True) → Path¶

Write simulation tables report summary to html.

Parameters:

filename : Path-like, optional¶: The html file to write.
cfg : Config, optional¶: The configuration to use for the report. If None, the configuration from the simulation object will be used.
make_dirs : bool, default True¶: If True, create any necessary directories.
extra : tuple, optional¶: Additional data to include in the report. Each item in the tuple should either a section or subsection title, or a tuple of (title, func), or just a function. If a function is provided, it should take the summary as its only argument and return a figure (altair.Chart or xmle.Elem) or table (pandas.DataFrame). The function will be called with the summary as its only argument. To use a function that requires other arguments, use functools.partial provide the other arguments.
add_timestamp : bool, default True¶: If True, append a timestamp to the filename. This ensures that each report is unique and does not overwrite previous reports. If False, the filename will be used as-is. Set this to False if you want to overwrite previous reports with the same filename, or if you are already setting the timestamp yourself.

Returns:

Path-like – The resolved filename for the saved outputs.

to_pickle(filename: str | Path, add_timestamp_ext: bool = True, *, preserve_meta_summaries: bool = False, preserve_config: bool = True, make_dirs: True | False | 'git' = True) → Path¶

Save to a pickle file.

This method uses lz4 compression if the lz4.frame module is available.

Parameters:

filename : str or Path-like¶: The filename to save the object to. An extension map be added or modified, to optionally add a time stamp and/or compression flag.
add_timestamp_ext : bool, default True¶: Add a timestamp extension to the filename.
preserve_meta_summaries : bool, default False¶: Preserve the meta_summaries attribute in the saved object.
preserve_config : bool, default False¶: Preserve the config attribute in the saved object. This includes the entire network, and can potentially be a lot of data.
make_dirs : bool or "git", default True¶: If True, create the parent directory for the pickle file if it does not already exist. If the directory is created, it will be created with a .gitignore file to prevent accidental inclusion of pickled output in Git repositories, unless the value is “git”, in which case no .gitignore file is created and the results will be eligible for inclusion in Git.

Returns:

Path-like – The resolved filename for the saved outputs.

to_xlsx(filename: str | Path) → None¶

Write simulation tables to excel.

Parameters:

filename : Path-like¶: The excel file to write.

cnx¶: Database connection for the Simulation run.

sim¶: Simulation object for the Simulation run.

n_total_samples¶

Total number of sample departures simulated to create these summaries.

This excludes any burn samples.

meta_summaries¶: Summaries that were aggregated to create this summary.