SimTabPathLegs¶

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

Bases: 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, db, sim, ...])
aggregate(summaries)	Aggregate multiple summary tables.
close()	Close retained storage and invalidate all shared database aliases.
connecting_paths_by_place()	Get the number of paths that connect in each place.
extract(sim[, items])	Extract summary data from a Simulation.
fig_leg_bid_price_detail_rake(*, leg_id[, ...])
fig_leg_bid_price_history(carrier, *, measure)
fig_leg_booking_detail_rake(*, leg_id[, ...])
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 summary tables, configuration, and metadata from a saved result.
from_pickle(filename[, read_latest])	Load the object from a pickle file.
metadata([key])	Return a metadata value.
remove_data(keys)	Remove data from the summary tables.
run_queries([db, 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, ...])	Atomically write simulation tables to a chunked PXSIM archive.
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

callback_data	Saved callback outputs, loaded on first access.
cnx	Deprecated alias for the PassengerSim database wrapper.
config	Saved simulation configuration, loaded on first access, or None.
database_available	Whether this live result has retained detail data, without opening it.
database_path	Absolute main-database path, or None when no file backs the result.
database_status	Trial completion and failure status for retained multiprocess results.
db	The shared retained database, opened on first access by the caller.
leg_bid_price_detail
leg_booking_detail
path_legs	Legs on each path.
pathclasses	Path-Class summary data.
trial_databases	Completed trial files owned by this live result, if available.
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.

path_legs : pd.DataFrame¶

Legs on each path.

pathclasses : pd.DataFrame¶

Path-Class summary data.

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

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”.

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

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.

connecting_paths_by_place() → Series[source]¶

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

classmethod aggregate(summaries: Collection[GenericSimulationTables]) → Self¶

Aggregate multiple summary tables.

property callback_data : CallbackData¶

Saved callback outputs, loaded on first access.

close()¶

Close retained storage and invalidate all shared database aliases.

Persistent output files are preserved. Closing an active run or closing from a different thread/process raises without removing its files.

property cnx¶

Deprecated alias for the PassengerSim database wrapper.

property config : Config | None¶

Saved simulation configuration, loaded on first access, or None.

property database_available¶

Whether this live result has retained detail data, without opening it.

property database_path¶

Absolute main-database path, or None when no file backs the result.

property database_status¶

Trial completion and failure status for retained multiprocess results.

property db¶

The shared retained database, opened on first access by the caller.

classmethod extract(sim: Simulation, items: Collection[str] = ()) → Self¶

Extract summary data from a Simulation.

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')¶

file_info()¶

Return information about the file store.

classmethod from_file(filename: str | Path, read_latest: bool = True, lazy: bool = True, *, read_only: bool = False) → Self¶

Load summary tables, configuration, and metadata from a saved result.

Parameters:

filename : str or pathlib.Path¶

PXSIM or legacy pickle file to read.

read_latest : bool, default True¶

Select the latest timestamped file when present.

lazy : bool, default True¶

Load summary tables on demand.

read_only : bool, default False¶

Open the PXSIM archive read-only. Otherwise, attempt writable access and fall back to read-only access if needed. This option does not affect legacy pickles.

Returns:

Self – Loaded result. Close it, or use it as a context manager, to release archive connections. Detailed simulation databases are not restored.

Raises:

• FileNotFoundError – The selected file does not exist.

• ValueError – Archive format, integrity, or configuration validation fails.

Notes

Existing legacy PXSIM files are read without schema migration. Only load trusted files: summary values use Python pickle.

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.

property leg_bid_price_detail¶

property leg_booking_detail¶

metadata(key: str = '')¶

Return a metadata value.

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.

Raises:

PermissionError – The backing archive is read-only; no in-memory data is removed.

Warns:

UserWarning – Deletion succeeded but reclaiming unused disk space failed.

Notes

Missing keys are ignored. Backing-file deletions are atomic and complete before in-memory entries are removed.

run_queries(db: 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:

db : Database, optional¶

PassengerSim database wrapper 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(filename: str | Path, *, timestamp: float | struct_time | datetime | None = None, make_dirs: True | False | 'git' = True, cfg: Config | None = None, extra_html: tuple = ()) → dict[str, Path]¶

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.

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¶

Atomically write simulation tables to a chunked PXSIM archive.

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:

pathlib.Path – The output filename, with timestamp when requested.

Raises:

• ValueError – Serialization fails or the target is a hard-link alias of the source.

• OSError – File creation or atomic publication fails.

Notes

Unloaded entries are copied without unpickling when possible. Loaded values are serialized again to preserve in-place edits. Publication failure leaves the existing target intact. Older readers that support only the legacy layout cannot read newly written version 2 files. Detailed simulation data stays in a separate SQLite file and is never embedded or modified by this export. New files honor the process umask; replacing an existing file preserves its permission bits.

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.

property trial_databases¶

Completed trial files owned by this live result, if available.

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.