Path¶
- class passengersim.core.Path¶
Bases:
objectA path: an itinerary of one or more legs that serves a market.
A path is what a customer can book: its legs in order, flown by one carrier, from the market’s origin to its destination. It holds one path class per booking class it sells, and those path classes carry the booking history and forecasts used by O&D revenue management. Paths are usually built by the simulation’s connection builder, but can also be created directly.
- Parameters:
- orig : str
Origin airport code.
- dest : str
Destination airport code.
- price : float, default 0.0
Default price; see price.
- carrier : Carrier or None, optional
The carrier that operates the path. If it is not given, carrier falls back to the carrier of the first leg.
- history : object, optional
Accepted but currently unused.
- Raises:
TypeError – If orig or dest is not a str, or carrier is neither a Carrier nor None.
Methods
__init__(*args, **kwargs)Add this path's path class forecasts to the matching buckets on its legs.
Add a path class for a booking class to this path.
Set the carrier that operates this path.
Add legs to the end of this path.
Add an order to the current sample's order history.
Does nothing (deprecated).
Split the path's Q demand forecast among its path classes.
Record booking history for this path at a data collection point (DCP).
Check whether a fare is available on this path, under the carrier's RM control.
Combine each path class's Y and Q forecasts into a total forecast.
Store the path's Q-equivalent demand for a timeframe, from classless orders.
Compute the path-level conditional Q (priceable) demand forecast.
Compute the adjusted fares for this path's path classes.
Compute the yieldable (Y) demand forecast for each of this path's path classes.
Compute the hybrid forecasts for this path: Y for each path class, and Q for the path.
Compute this path's Q-equivalent demand from the current sample's sales.
Compute the raw adjusted fares and sell-up probabilities for this path's path classes.
Check whether this path includes the leg with a given leg ID.
Untruncate (detruncate) the historical demand for this path's path classes.
Get the stored decision fare of one of this path's path classes.
Get the forecast mean demand of one of this path's path classes.
Get the forecast standard deviation of one of this path's path classes.
Get the number sold in one of this path's path classes, in the current sample.
The part of a fare to credit to one leg, after displacement costs.
Get the classless continuous pricing F* value for a timeframe.
Get this path's path class forecasts and booking history as tables.
Get the arrival time of one of this path's legs.
Get the local arrival time of one of this path's legs.
Get the stored bid price of one of this path's legs.
Get the capacity of one of this path's legs.
Get the carrier code of one of this path's legs.
Get the departure time of one of this path's legs.
Get the local departure time of one of this path's legs.
Get the destination airport of one of this path's legs.
Get the equipment code of one of this path's legs.
Get the flight number of one of this path's legs.
Get the leg ID of one of this path's legs.
Get the origin airport of one of this path's legs.
Get the orders recorded for one sample, as a list of dictionaries.
Total of the leg bid prices on this path, for one seat.
Total distance of this path's legs.
Adjust the path class forecasts for part of a timeframe having passed.
Create a new ForecastGroup that follows this path.
Move this path's history buffers on to the next departure.
Number of path classes on this path.
Number of departures in the history (not implemented).
Number of legs on this path.
Total of the reportable leg bid prices on this path, for one seat.
Reset this path's sales counters for a new sample.
Set the stored decision fare of one of this path's path classes.
Set the forecast mean demand of one of this path's path classes.
Set the forecast standard deviation of one of this path's path classes.
Set the number sold in one of this path's path classes.
Set each path class's forecast mean and standard deviation from its total forecast.
Attributes
Arrival time of the last leg, as a Unix timestamp.
The carrier that operates this path.
The code of the carrier that operates this path.
Difference between local arrival and local departure time, in seconds.
Departure time of the first leg, as a Unix timestamp.
Destination airport code.
Total travel time of the path, in minutes.
Whether this is the earliest path in its market (not implemented).
Access to this path's path class forecasts through the ForecastGroup API.
Grand total revenue from this path, after the burn period.
Grand total number of passengers sold on this path, after the burn period.
Grand total of the priceable passengers in gt_sold, after the burn period.
Herfindahl-Hirschman index of this path's carrier at the market's origin.
Whether this is the latest path in its market (not implemented).
The leg IDs of this path's legs, in order.
This path's legs, in order.
The market that this path serves, or None.
The largest Herfindahl-Hirschman index of any carrier at the market's origin.
Total of the minimum connect times for all connections on the path.
Number of Path Python objects currently alive.
Origin airport code.
Unique ID for this path.
Path quality index, used in the choice model's path quality term.
An iterator over the PathClass objects on this path.
Default price for this path (deprecated).
The path-level Q (priceable) demand forecast, or None if there isn't one.
Revenue from this path in the current sample.
Number of passengers sold on this path in the current sample.
Number of the passengers in sold whose offer was priceable.
Total of the leg bid prices on this path, for one seat.
The truncation rule of this path's carrier.
- accumulate_forecasts()¶
Add this path’s path class forecasts to the matching buckets on its legs.
This is how O&D forecasts reach leg-level RM. For each path class, and each bucket with the same booking class on each of the path’s legs, the core adds the path class’s forecast mean to the bucket’s forecast mean, its variance to the bucket’s variance, and its forecast mean times its adjusted fare at dcp_index to the bucket’s forecast revenue. If both have forecast vectors, the path class’s vectors are added to the bucket’s total forecast too: means are added and standard deviations are combined as the square root of the sum of squares. The buckets are not cleared first.
- Parameters:
- dcp_index : int
The DCP index for the adjusted fare. This is positional-only.
- Returns:
int – Always 0.
- Raises:
RuntimeError – If a bucket’s forecast vectors do not match the path class’s in length, or another error occurs in the core.
- add_booking_class()¶
Add a path class for a booking class to this path.
- Parameters:
- booking_class : str
The booking class.
- if_not_found : bool, default False
If True and the path already has a path class for this booking class, nothing is added and None is returned.
- Returns:
PathClass or None – The new path class, or None if if_not_found found an existing one.
- Raises:
TypeError – If booking_class is not a str.
- add_carrier()¶
Set the carrier that operates this path.
This is used for unit testing; the connection builder sets the carrier itself. It replaces any carrier already set.
- Parameters:
- carrier : Carrier
The carrier. This is positional-only.
- Raises:
TypeError – If carrier is not a Carrier.
- add_leg()¶
Add legs to the end of this path.
The legs are added in the order given. They are not checked: the path’s airports, the connections and the carrier are taken as they are.
- Parameters:
- *legs : Leg
The legs to add.
- Returns:
int – Always 0.
- Raises:
TypeError – If an argument is not a Leg. Then no legs are added.
- add_order()¶
Add an order to the current sample’s order history.
This is mostly used for unit testing; the simulation records the orders for classless continuous pricing itself.
- Parameters:
- timestamp : float
Time of the order.
- dcp_index : int
Index of the timeframe in which the order was made.
- num_pax : int
Number of passengers.
- price : float
Price per passenger.
- bid_price : float
Total bid price at the time of the order.
- Returns:
int – Always 0.
- Raises:
ValueError – If any argument is negative.
- add_path_class()¶
Does nothing (deprecated).
Path classes are linked to their path when they are created, for example with add_booking_class. This method accepts any arguments, ignores them, and returns 0.
- Returns:
int – Always 0.
- allocate_q_demand()¶
Split the path’s Q demand forecast among its path classes.
This takes the path-level Q forecast, for example from compute_conditional_q_forecast. For each timeframe from the last back to dcp_index, the path classes are sorted from the highest fare to the lowest, and each gets a share of the path’s Q demand equal to its increase in sell-up probability over the next higher path class. The sell-up probabilities are the ones cached by compute_simple_fare_adjustments (or compute_fare_adjustments). A path class gets no share in a timeframe if its adjusted fare is not positive, or it is closed by an advance purchase restriction. Timeframes before dcp_index are set to zero. The results are stored in each path class’s Q forecast.
- Parameters:
- frat5 : Frat5
The Frat5 curve. This is required.
- dcp_index : int, default 0
The first DCP index to allocate.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace of the calculation is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- allocation_algorithm : str, optional
How to build each path class’s standard deviation to departure. A string containing
"tf"allocates the variance within each timeframe and rolls it up. A string containing"dep"scales the path’s variance to departure directly. The default is"tf". This is keyword-only.
- Raises:
TypeError – If frat5 is not a Frat5.
IndexError – If dcp_index is negative or beyond the path’s Q forecast.
ValueError – If allocation_algorithm is not recognized.
RuntimeError – If the path has no Q forecast, a path class has no history or no cached sell-up probabilities, or the allocated total does not match the path’s Q demand.
- arr_time¶
Arrival time of the last leg, as a Unix timestamp.
This is 0 if the path has no legs. Read-only.
- capture_dcp()¶
Record booking history for this path at a data collection point (DCP).
The simulation driver calls this for every path at each DCP. It closes out the timeframe that just ended and starts the next one in each path class’s history for the current departure.
For each path class, the core records its cumulative
soldandsold_priceablecounts and whether it was closed, that is, not available for one passenger under the carrier’s RM control. With continuous pricing, if the carrier records CP sales in the highest closed class (seeCarrier.cp_record_highest_closed_as_open), that class is recorded as open. If the carrier stores Q history, the path’s priceable sales are then converted into Q-equivalent demand with the Frat5 curve and stored in the path’s Q history.With closures_only, the core only updates the closure flags, and the path’s Q history is marked closed when every path class is closed. This is used after the RM step has changed availability.
- Parameters:
- dcp : int
Index of the DCP being captured (0 is the first DCP of the booking horizon).
- frat5 : Frat5, optional
The Frat5 curve for the Q history. By default, the carrier’s curve for this market is used.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- closures_only : bool, default False
If True, only update the closure flags, as described above. This is keyword-only.
- Raises:
IndexError – If dcp is negative or past the end of a history.
TypeError – If frat5 is not a Frat5.
ValueError – If the path has no carrier (RuntimeError with closures_only).
RuntimeError – If a path class has no fare or no history, if the carrier stores Q history but there is no Frat5 curve, or another error occurs in the core.
- carrier¶
The carrier that operates this path.
If none was given to the constructor or add_carrier, this is the carrier of the first leg. Reading it raises ValueError if there is neither. Read-only.
- carrier_name¶
The code of the carrier that operates this path.
It falls back to the first leg’s carrier in the same way as carrier, and raises ValueError if there is neither. Read-only.
- check_avail()¶
Check whether a fare is available on this path, under the carrier’s RM control.
The path class for the fare is found, and its availability for num_pax passengers is checked using the carrier’s control (see
Carrier.control). This is mostly used for unit testing.- Parameters:
- fare : Fare
The fare to check.
- num_pax : int
The number of passengers.
- debug : bool, optional
If true, the working is written to standard output.
- Returns:
bool – True if the fare is available. False if it is not, or if no path class on this path has this fare.
- Raises:
TypeError – If fare is not a Fare.
ValueError – If num_pax is less than 1.
Exception – If the path has no carrier.
- combine_forecasts()¶
Combine each path class’s Y and Q forecasts into a total forecast.
For each path class and each timeframe, the total forecast mean is the sum of the Y and Q forecast means. The Q part is left out where the path class has a raw adjusted fare that is zero or less, and the total is zero once the path class is closed by an advance purchase restriction. How the standard deviations combine depends on rollup_algorithm. The total forecast becomes the path class’s active forecast. This does not change the path classes’ forecast mean and standard deviation; use update_forecasts for that.
- Parameters:
- dcp_index : int, default 0
Accepted but currently unused; all timeframes are combined.
- rollup_algorithm : str, optional
A string containing
"tf"adds the Y and Q variances within each timeframe, then rolls them up to departure. A string containing"dep"rolls up the Y and Q variances to departure separately, then adds them. The default is"tf". This is keyword-only.- snapshot_instruction : SnapshotInstruction or bool, optional
Accepted but currently unused. This is keyword-only.
- Raises:
ValueError – If a path class has no Y or Q forecast, or rollup_algorithm is not recognized.
- compute_classless_q_equivalent_history()¶
Store the path’s Q-equivalent demand for a timeframe, from classless orders.
This is the classless continuous pricing version of the Q history step in capture_dcp. For dcp_index greater than 0, each order in the current sample from timeframe
dcp_index - 1is converted to Q-equivalent demand: its passengers divided by the sell-up probability from the lowest decision price to the order’s price, capped at max_cap times the passengers. The total is stored in the path’s Q history for that timeframe, which is marked closed if the path has no seats left. For a dcp_index of 0, a zero timeframe is stored. The path’s Q forecast and its history are created first if they don’t exist yet.- Parameters:
- frat5 : Frat5
The Frat5 curve that gives the sell-up probabilities.
- dcp_index : int, default 0
The DCP index being captured.
- max_cap : float, default 10.0
The cap on the inflation of each order’s passengers.
- debug : bool or SnapshotInstruction, optional
If True, a trace is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- Returns:
float – The total Q-equivalent demand stored, or 0.0 for a dcp_index of 0.
- Raises:
TypeError – If frat5 is not a Frat5.
IndexError – If dcp_index is negative.
RuntimeError – If the Q objects cannot be created (for example, the path has no path classes), or another error occurs in the core.
- compute_conditional_q_forecast()¶
Compute the path-level conditional Q (priceable) demand forecast.
Working back from the last timeframe to dcp_index, the core takes the priceable sales in every path class for each historical departure and converts them to Q-equivalent demand using the sell-up probabilities from frat5 (inflating by the inverse sell-up probability, capped at max_cap if it is set). When a timeframe has no sales at all, the lowest open path class is assumed to be where sales would have happened. A regression over all the departures and path classes then gives the path’s Q demand mean for the timeframe, and its mean squared error gives the standard deviation, unless variance_is_ratio_of_mean is set.
The results are stored in the path’s own Q forecast, as means and standard deviations in each timeframe and to departure. They are not assigned to the path classes; use allocate_q_demand for that.
- Parameters:
- frat5 : Frat5
The Frat5 curve that gives the sell-up probabilities.
- dcp_index : int, default 0
The first DCP index to forecast. Earlier timeframes are set to zero.
- regression_weight : {'sellup', 'sellup^2', 'fare', 'none'} or None, optional
How to weight the regression: by the inverse sell-up probability, by its square, or by fare. None or
"none"means no weighting, which is the default.- max_cap : float, default 0.0
The cap on the inverse sell-up probability used to inflate sales. Zero means no cap. This is keyword-only.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace of the calculation is written to standard output; if a SnapshotInstruction, the trace is written as it directs. This is keyword-only.
- partial_tf_weight_adjustment : bool, default False
If True, adjust the regression weights for the fraction of each timeframe in which each path class was the lowest open one. This is keyword-only.
- variance_is_ratio_of_mean : float, default 0.0
If nonzero, the variance in each timeframe is set to this value times the mean, instead of coming from the regression error. This is keyword-only.
- Raises:
TypeError – If frat5 is not a Frat5.
ValueError – If regression_weight is not recognized, the path has no path classes, or the number of timeframes in the history does not match frat5.
IndexError – If dcp_index is out of range, or the path classes’ history has no stored departures.
- compute_fare_adjustments()¶
Compute the adjusted fares for this path’s path classes.
This first calls compute_simple_fare_adjustments to get the raw adjusted fares (reusing them if they were already computed). Then, for each DCP and each path class from the highest down, it sets the path class’s adjusted fare. A path class’s fare is its forecast revenue, which comes from the carrier’s
decision_price_rule.The highest path class keeps its fare.
Every other path class gets its raw adjusted fare. If weighted_by_ratio is True, this is instead blended with the unadjusted fare, weighted by the path class’s Q and Y demand forecasts to departure at that DCP:
(raw * Q + fare * Y) / (Q + Y). If both forecasts are zero, the raw adjusted fare is used.Adjusted fares are never negative, and are NaN once the path class is closed by an advance purchase restriction.
- Parameters:
- algorithm : {'MR', 'mr', 'KI', 'ki'} or None
The fare adjustment method: marginal revenue (
"MR") or"KI". If None, all adjusted fares are cleared and nothing else is done.- frat5 : Frat5
The Frat5 curve used for the adjustment. Required even when algorithm is None.
- scale_factor : float, default 1.0
Scaling factor passed on to the raw fare adjustment.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace of the calculation is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- sort_pathclasses : bool, default True
If True, first sort the path classes by forecast revenue, from highest to lowest. This is keyword-only.
- weighted_by_ratio : bool, default True
Whether to blend each raw adjusted fare with the unadjusted fare, as described above. If True, every path class must already have both a Q and a Y forecast. This is keyword-only.
- Raises:
TypeError – If frat5 is not a Frat5.
ValueError – If algorithm is not recognized.
RuntimeError – If weighted_by_ratio is True and a path class has no Q or Y forecast.
- compute_forecasts()¶
Compute the yieldable (Y) demand forecast for each of this path’s path classes.
For each path class, the core creates a Y forecast from the path class’s booking history if there isn’t one yet. If recompute is True, it then runs the chosen forecasting algorithm on that history for the timeframes from dcp_index to departure, taking any advance purchase restriction into account. Whether or not it recomputes, it then sets the path class’s forecast mean and standard deviation (see get_class_fcst_mean) to the Y forecast’s mean and standard deviation of demand to departure at dcp_index, or zero if there is no value there.
- Parameters:
- dcp_index : int
The DCP index to forecast from.
- algorithm : {'exp_smoothing', 'additive_pickup'} or None, optional
The forecasting algorithm. Required if recompute is True, and ignored otherwise.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace of the calculation is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- recompute : bool, default False
If True, recompute the forecasts from history. If False, only refresh each path class’s forecast mean and standard deviation from its existing forecast at dcp_index.
- alpha : float, default 0.15
Smoothing factor for exponential smoothing. This is keyword-only.
- event_time : int, optional
Accepted but currently unused. This is keyword-only.
- which_data : str, optional
Which sales to forecast from: a string containing
"tot"(or exactly"all") for total sales,"price"for priceable sales, or"yield"for yieldable sales. None or"none"also mean total sales, which is the default. This is keyword-only.- return_vectors : bool, default False
If True, return each path class’s forecast vectors. This is mostly used for debugging and testing. This is keyword-only.
- Returns:
None or dict[str, ForecastVectors] – None, unless return_vectors is True. Then a dictionary mapping each path class’s booking class to its forecast vectors: the mean and standard deviation in each timeframe and to departure, and the closure probabilities. These come from the path class’s active forecast, which is its total (hybrid) forecast if it has one, and otherwise its Y forecast.
- Raises:
ValueError – If recompute is True and algorithm is missing or unknown, or if which_data is not recognized.
TypeError – If which_data is not a string, or snapshot_instruction is neither a bool nor a SnapshotInstruction.
- compute_hybrid_forecasts()¶
Compute the hybrid forecasts for this path: Y for each path class, and Q for the path.
Hybrid forecasting splits demand in two. Yieldable demand, from customers who want a particular product, is forecast for each path class from its yieldable sales history. Priceable demand, from customers who buy the cheapest product available, is forecast for the path as a whole from the path’s Q-equivalent history (see capture_dcp).
For each path class, the core creates a Y forecast if there isn’t one yet, caches the sell-up probabilities from frat5 if they are not cached yet, and runs algorithm on the yieldable history for the timeframes from dcp_index to departure. It then runs algorithm on the path’s Q forecast using the priceable history. Use allocate_q_demand to split the Q forecast among the path classes, and combine_forecasts to combine the two.
- Parameters:
- dcp_index : int
The DCP index to forecast from.
- algorithm : {'exp_smoothing', 'additive_pickup'}
The forecasting algorithm.
- frat5 : Frat5
The Frat5 curve for the sell-up probabilities.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- recompute : bool, default True
Accepted but currently unused; the forecasts are always recomputed.
- pods_init : bool, default False
Accepted but currently unused.
- alpha : float, default 0.15
Smoothing factor for exponential smoothing. This is keyword-only.
- debug : object, optional
Accepted but currently unused. This is keyword-only.
- Raises:
TypeError – If algorithm is not a str or frat5 is not a Frat5.
ValueError – If algorithm is not recognized.
IndexError – If dcp_index is past the last timeframe of the Q history.
RuntimeError – If the path has no Q forecast, or another error occurs in the core.
- compute_q_equivalent()¶
Compute this path’s Q-equivalent demand from the current sample’s sales.
The path classes are first sorted by decision price, from highest to lowest. Each path class’s priceable sales are then divided by its sell-up probability from the lowest decision price (from frat5, for timeframe dcp_index), capped at max_cap times the sales, and the results are added up. Nothing is stored.
- Parameters:
- frat5 : Frat5
The Frat5 curve that gives the sell-up probabilities.
- dcp_index : int, default 0
The timeframe index for the Frat5 value.
- max_cap : float, default 10.0
The cap on the inflation of each path class’s sales.
- debug : bool or SnapshotInstruction, optional
If true, the working is written to the snapshot output.
- Returns:
float – The total Q-equivalent demand.
- Raises:
TypeError – If frat5 is not a Frat5.
IndexError – If dcp_index is negative or past the last Frat5 value.
RuntimeError – If a path class has no fare, or another error occurs in the core.
- compute_simple_fare_adjustments()¶
Compute the raw adjusted fares and sell-up probabilities for this path’s path classes.
For each DCP in frat5, the core works through the path classes from the highest down. A path class’s fare is its forecast revenue, which comes from the carrier’s
decision_price_rule. The highest path class’s raw adjusted fare is its fare. Each lower path class’s raw adjusted fare comes from the Frat5 curve’s fare adjustment, relative to the lowest fare on the path. Once a path class is closed by an advance purchase restriction, its raw adjusted fare is NaN. Along the way, the core also caches each path class’s sell-up probability (from frat5, relative to the lowest fare), which allocate_q_demand needs.The raw adjusted fares are computed only once: if every path class already has a value for each DCP, nothing is recomputed. To force a new calculation, first call this with algorithm set to None.
- Parameters:
- algorithm : {'MR', 'mr', 'KI', 'ki'} or None
The fare adjustment method: marginal revenue (
"MR") or"KI". If None, the raw adjusted fares are cleared, and only the sell-up probabilities are computed.- frat5 : Frat5
The Frat5 curve used for the adjustment and the sell-up probabilities.
- scale_factor : float, default 1.0
Scaling factor applied to the fare adjustment.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace of the calculation is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- Raises:
TypeError – If frat5 is not a Frat5.
ValueError – If algorithm is not recognized.
- contains_leg_id()¶
Check whether this path includes the leg with a given leg ID.
- Parameters:
- leg_id : int
The leg ID to look for.
- Returns:
bool – True if one of the path’s legs has this leg ID.
- delta_t¶
Difference between local arrival and local departure time, in seconds.
This is used by the decision window model. A negative difference, for an overnight trip, has one day (86400 seconds) added. Reading it raises RuntimeError if the path has no legs. Read-only.
- dep_time¶
Departure time of the first leg, as a Unix timestamp.
This is 0 if the path has no legs. Read-only.
- dest¶
Destination airport code.
Read-only; it is set when the Path is created.
- detruncate_demand()¶
Untruncate (detruncate) the historical demand for this path’s path classes.
Sales recorded while a path class was closed understate the true demand, because some customers were turned away. Untruncation estimates what demand would have been in those constrained observations, and stores the result in a “detruncated” history that forecasting can use in place of the raw sales.
What the core does depends on algorithm:
"em"(or"EM"): for each path class, and separately for each timeframe, runs the Expectation-Maximization algorithm across the stored departures. Departures where the path class was closed are treated as censored observations of a normal distribution. EM estimates that distribution’s mean and standard deviation, and replaces each censored value with its expected value given that demand was at least the sales observed (never less than the sales themselves). When only one or two departures were open in a timeframe, EM is skipped and each closed value is raised to the mean of the open ones instead. If the history holds fewer than 3 departures, nothing is done."external": no calculation is done. The detruncated history is taken directly from external (see below).Any other name (for example
"none"): nothing is done.
- Parameters:
- dcp_index : int
The DCP index at which untruncation is being run. This is required but is currently not used by the core, which processes every timeframe.
- algorithm : str
The untruncation algorithm, as described above.
- snapshot_instruction : SnapshotInstruction, optional
If given, and it is triggered, the EM working is written to the snapshot output.
- maxiter : int, default 20
Maximum number of EM iterations for each timeframe.
- tolerance : float, default 0.01
EM stops once the estimated mean changes by less than this fraction between iterations.
- pods_initialization : bool, default False
Use the PODS method to choose the EM starting values.
- minimum_mu : float, default 0.01
If the estimated mean falls below this value, closed observations in that timeframe are left at their observed sales.
- minimum_sigma : float, default 0.1
Lower limit for the estimated standard deviation.
- which_data : str, optional
Which sales history to untruncate. The value is matched as follows: containing
"tot"or equal to"all"means total sales; containing"price"means priceable sales; containing"yield"means yieldable sales. For priceable sales, only the path-level Q forecast history is untruncated, not the path classes.If omitted (or
Noneor"none"), no data type is selected and"em"does no untruncation: the detruncated history just equals the raw sales. In practice this argument should always be given.- external : dict or numpy.ndarray, optional
Detruncated history to store directly when algorithm is
"external"; it must not be given for any other algorithm. When which_data is priceable, it is a 2-D array of floats for the path-level Q history. Otherwise it is a dict mapping each path class’s booking class to a 2-D array of floats. Each value must be a NumPy float array with one row per stored departure and one column per timeframe, matching the shape of the corresponding history.
- Raises:
ValueError – If which_data is not recognized; if external is missing when algorithm is
"external"or given when it is not; if external is missing a booking class or an array has the wrong shape; or if priceable data is requested but the history does not store it.TypeError – If which_data is not a string, external is not a dict when one is required, or an external array is not a NumPy array of floats.
RuntimeError – If priceable data is requested but the path has no Q forecast, or another error occurs in the core.
- duration¶
Total travel time of the path, in minutes.
This runs from the first leg’s departure to the last leg’s arrival, both in local time (adjusted by each leg’s GMT offset). If that is not positive, for example when the leg times are not set, the leg durations plus 20 minutes for each connection are added to it instead. Reading it raises RuntimeError if the path has no legs. Read-only.
- early_path¶
Whether this is the earliest path in its market (not implemented).
This is always False. Read-only.
- forecast¶
Access to this path’s path class forecasts through the ForecastGroup API.
This works on the path classes’ own forecasts, unlike new_forecast, which creates a separate forecast group. Read-only.
- get_class_decision_fare()¶
Get the stored decision fare of one of this path’s path classes.
This is the stored value, not the decision price that the carrier’s
decision_price_rulegives.- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- Returns:
float – The decision fare.
- Raises:
IndexError – If pc_index does not match a path class.
- get_class_fcst_mean()¶
Get the forecast mean demand of one of this path’s path classes.
- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- Returns:
float – The forecast mean.
- Raises:
IndexError – If pc_index does not match a path class.
- get_class_fcst_std_dev()¶
Get the forecast standard deviation of one of this path’s path classes.
- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- Returns:
float – The forecast standard deviation.
- Raises:
IndexError – If pc_index does not match a path class.
- get_class_sold()¶
Get the number sold in one of this path’s path classes, in the current sample.
- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- Returns:
int – The number sold.
- Raises:
IndexError – If pc_index does not match a path class.
- get_displacement_adjusted_fare()¶
The part of a fare to credit to one leg, after displacement costs.
For a path with one leg, this is price. Otherwise the displacement costs (
Leg.displacement) of the path’s other legs are subtracted from price, and the result is normalized according to normalization_method:0: no normalization, just the result (never below zero).
1: if the results for all the path’s legs add up to more than price, scale them down so they add up to price.
2: if they add up to less than price, scale them up so they add up to price.
3: always scale them so they add up to price.
4: scale the result by this leg’s share of the path’s total displacement cost (if the total is positive).
When scaling, if the results add up to almost zero, price is shared equally among the legs. The result is always between 0 and price.
- Parameters:
- leg_id : int
The leg ID of the leg to credit.
- price : float
The fare.
- normalization_method : int
The normalization, from 0 to 4, as above.
- debug : bool, optional
If true, the working is written to standard error.
- Returns:
float – The displacement-adjusted fare for the leg.
- Raises:
ValueError – If normalization_method is not from 0 to 4.
- get_f_star()¶
Get the classless continuous pricing F* value for a timeframe.
F* is the optimal fare that the classless optimizer finds for this path in each timeframe. The values are only there after the classless optimizer has run.
- Parameters:
- tf_index : int
The timeframe index, starting at 0.
- Returns:
float – The F* value.
- Raises:
IndexError – If tf_index is negative or there is no value for it.
- get_forecast_data()¶
Get this path’s path class forecasts and booking history as tables.
This calls the function registered with _set_func_get_forecast_data, passing this path first and then any arguments given here. The default function returns a ForecastData object. It holds DataFrames, indexed by timeframe and with one column per booking class, of the forecast mean and standard deviation in each timeframe and to departure, each path class’s average priceable and yieldable sales and closures from its history, and its adjusted prices. It also holds the carrier’s DCP days prior.
- Parameters:
- *args
Passed on to the registered function. The default function takes none.
- **kwargs
Passed on to the registered function. The default function takes none.
- Returns:
ForecastData – The forecast data, when the default function is registered.
- Raises:
Exception – If no function is registered.
ValueError – With the default function, if the path’s carrier has no DCP days prior.
- get_leg_arr_time()¶
Get the arrival time of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
int – The arrival time, as a Unix timestamp.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_arr_time_local()¶
Get the local arrival time of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
int – The arrival time plus the leg’s arrival GMT offset.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_bid_price()¶
Get the stored bid price of one of this path’s legs.
This is the leg’s stored scalar bid price, not
Leg.bid_price, which also includes the bid price gradient and bid price arrays.- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
float – The bid price.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_capacity()¶
Get the capacity of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
int – The leg’s capacity.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_carrier()¶
Get the carrier code of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
str – The carrier code.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_dep_time()¶
Get the departure time of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
int – The departure time, as a Unix timestamp.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_dep_time_local()¶
Get the local departure time of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
int – The departure time plus the leg’s departure GMT offset.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_dest()¶
Get the destination airport of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
str – The destination airport code.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_equipment()¶
Get the equipment code of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
str – The equipment code, which may be empty.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_fltno()¶
Get the flight number of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
int – The flight number.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_id()¶
Get the leg ID of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
int – The leg ID.
- Raises:
IndexError – If n is negative or past the last leg.
- get_leg_orig()¶
Get the origin airport of one of this path’s legs.
- Parameters:
- n : int
Index of the leg on the path, starting at 0.
- Returns:
str – The origin airport code.
- Raises:
IndexError – If n is negative or past the last leg.
- get_orders()¶
Get the orders recorded for one sample, as a list of dictionaries.
The path keeps the orders for up to 27 samples: the current one and up to 26 earlier ones. reset_counters starts a new sample.
- Parameters:
- offset : int, default 0
How many samples to go back: 0 is the current sample.
- Returns:
list[dict[str, int or float]] – One dict per order, with the keys
"timestamp","dcp_index","num_pax","price"and"bid_price".- Raises:
IndexError – If offset is negative or not less than the number of samples kept.
- get_total_bid_price()¶
Total of the leg bid prices on this path, for one seat.
The same as the total_bid_price property.
- Returns:
float – The sum of each leg’s leg-level bid price.
- get_total_distance()¶
Total distance of this path’s legs.
- Returns:
float – The sum of the leg distances, or 0.0 if the path has no legs.
- gt_revenue¶
Grand total revenue from this path, after the burn period.
reset_counters does not change it. Setting it requires a non-negative number.
- gt_sold¶
Grand total number of passengers sold on this path, after the burn period.
reset_counters does not change it. Setting it requires a non-negative int.
- gt_sold_priceable¶
Grand total of the priceable passengers in gt_sold, after the burn period.
reset_counters does not change it. Setting it requires a non-negative int.
- hhi¶
Herfindahl-Hirschman index of this path’s carrier at the market’s origin.
The simulation computes it from the carriers’ seat shares at the origin airport, and the choice model’s HHI term uses it with max_hhi. It reads as a float, but setting it requires a non-negative int.
- late_path¶
Whether this is the latest path in its market (not implemented).
This is always False. Read-only.
- leg_ids¶
The leg IDs of this path’s legs, in order.
Each read returns a new tuple. Read-only.
- legs¶
This path’s legs, in order.
Each read returns a new tuple. Read-only; add legs with add_leg.
- market¶
The market that this path serves, or None.
The simulation sets it when it adds the path to its market. Setting it requires a Market.
- max_hhi¶
The largest Herfindahl-Hirschman index of any carrier at the market’s origin.
The simulation computes it along with hhi; the choice model’s HHI term uses the difference between the two. It reads as a float, but setting it requires a non-negative int.
- mid_timeframe_forecast_interpolation()¶
Adjust the path class forecasts for part of a timeframe having passed.
This is used for daily reoptimization within a timeframe. The fraction of the timeframe that has passed is
(current_time - current_tf_begin_time) / (current_tf_end_time - current_tf_begin_time). For each path class with a forecast, its forecast mean to departure at current_tf_index is reduced by that fraction of its mean in the timeframe (never below zero). Its standard deviation to departure is reduced by the same fraction of the timeframe’s part of it (the difference between the values at this timeframe and the next). The results become the path class’s forecast mean and standard deviation. Mostly used for unit testing.- Parameters:
- current_tf_index : int
The current timeframe index.
- current_tf_begin_time : int
When the current timeframe began. It must be nonzero and not after current_time.
- current_time : int
The current time.
- current_tf_end_time : int
When the current timeframe ends.
- departure_time : int, optional
Accepted but currently unused.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace is written to standard output; if a SnapshotInstruction, the trace is written as it directs.
- Raises:
ValueError – If current_tf_begin_time is zero or after current_time.
RuntimeError – If the fraction is negative or greater than 1, current_tf_index is out of range, or another error occurs in the core.
- minimum_connect_time¶
Total of the minimum connect times for all connections on the path.
The choice model compares the path’s actual connect time with this to find the buffer time. The connection builder sets it. Setting it requires a non-negative int.
- new_forecast()¶
Create a new ForecastGroup that follows this path.
The new forecast group has one class forecast per path class. Each one shares its path class’s booking history but keeps its own forecast values, so changing the group’s forecasts does not change the path classes’ forecasts.
- Returns:
ForecastGroup – The new forecast group.
- next_departure()¶
Move this path’s history buffers on to the next departure.
History is kept in ring buffers holding a fixed number of past departures. This finishes the current departure and makes room for the next one, for the path’s Q history (if there is one) and each path class’s history. Each path class also updates its weighted average selling prices by timeframe, which the
"weighted"decision price rules use.- Raises:
RuntimeError – If a path class has no history buffer, or another error occurs in the core.
- num_classes()¶
Number of path classes on this path.
- Returns:
int – The number of path classes.
- num_deps()¶
Number of departures in the history (not implemented).
- Raises:
NotImplementedError – Always.
- num_legs()¶
Number of legs on this path.
- Returns:
int – The number of legs.
- num_objects¶
Number of Path Python objects currently alive.
This is a count over all paths, not a property of this one. It was used to find memory leaks. Read-only.
- orig¶
Origin airport code.
Read-only; it is set when the Path is created.
- path_id¶
Unique ID for this path.
The connection builder numbers the paths it builds; a Path created directly starts at -1 until one is set. Setting it requires an int.
- path_quality_index¶
Path quality index, used in the choice model’s path quality term.
Until it is set, it is the number of legs on the path. Setting it accepts any number; setting it to -1 restores that default.
- pathclasses¶
An iterator over the PathClass objects on this path.
Each read returns a new iterator. Read-only; add path classes with add_booking_class.
- price¶
Default price for this path (deprecated).
Fares, not this value, set the prices that customers pay. Setting it requires a non-negative number.
- q_forecast¶
The path-level Q (priceable) demand forecast, or None if there isn’t one.
The path’s priceable history is stored in this forecast’s history, and hybrid forecasting and Q forecasting use it. The simulation creates it when the path’s histories are set up. The returned Forecast shares its data with the path. Setting it requires a Forecast; it cannot be set to None.
- report_total_bid_price()¶
Total of the reportable leg bid prices on this path, for one seat.
Each leg’s reportable bid price is the same as its bid price, except when the leg has a bid price array and is full: then it is the bid price that applied to the most recent sale, rather than the very large sentinel value (see
Leg.report_bid_price).- Returns:
float – The sum of each leg’s reportable leg-level bid price.
- reset_counters()¶
Reset this path’s sales counters for a new sample.
This sets the current-sample counters (passengers sold, priceable passengers sold and revenue) back to zero on the path and each of its path classes, and starts a new sample in the order history, keeping up to 26 earlier ones. The grand totals (the
gt_counters) are not changed.- Parameters:
- truncation_flags : int, default 0
A truncation rule. It only needs to be nonzero; when it is 0, the carrier’s truncation rule is used, which requires a carrier.
- Raises:
Exception – If truncation_flags is 0 and no carrier was set.
- revenue¶
Revenue from this path in the current sample.
Each booking adds its price times its number of passengers. reset_counters sets it back to zero. Read-only.
- set_class_decision_fare()¶
Set the stored decision fare of one of this path’s path classes.
This is mostly used for unit testing.
- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- fare : float
The decision fare.
- Returns:
int – Always 0.
- Raises:
IndexError – If pc_index does not match a path class.
- set_class_fcst_mean()¶
Set the forecast mean demand of one of this path’s path classes.
This is mostly used for unit testing.
- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- fcst_mean : float
The forecast mean.
- Returns:
int – Always 0.
- Raises:
IndexError – If pc_index does not match a path class.
- set_class_fcst_std_dev()¶
Set the forecast standard deviation of one of this path’s path classes.
This is mostly used for unit testing.
- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- fcst_std_dev : float
The forecast standard deviation.
- Returns:
int – Always 0.
- Raises:
IndexError – If pc_index does not match a path class.
- set_class_sold()¶
Set the number sold in one of this path’s path classes.
This is mostly used for unit testing.
- Parameters:
- pc_index : int or str
The path class, by its position on the path (starting at 0) or by its booking class. Only an int or a str is accepted.
- sold : int
The number sold.
- Returns:
int – Always 0.
- Raises:
IndexError – If pc_index does not match a path class.
- sold¶
Number of passengers sold on this path in the current sample.
reset_counters sets it back to zero. Read-only.
- sold_priceable¶
Number of the passengers in sold whose offer was priceable.
Priceable sales are used by Q forecasting. reset_counters sets it back to zero. Read-only.
- total_bid_price¶
Total of the leg bid prices on this path, for one seat.
This is the sum of each leg’s leg-level bid price; see
Leg.bid_price. Read-only.
- truncation_rule¶
The truncation rule of this path’s carrier.
See
Carrier.truncation_rule. Unlike carrier, this does not fall back to the first leg’s carrier: it raises ValueError if no carrier was set. Read-only.
- update_forecasts()¶
Set each path class’s forecast mean and standard deviation from its total forecast.
For each path class that has both a total (hybrid) forecast and a Q forecast, the core sets the path class’s forecast mean and standard deviation (see get_class_fcst_mean) to the total forecast’s mean and standard deviation of demand to departure at dcp_index, or zero if there is no value there. Path classes without those forecasts are skipped.
- Parameters:
- dcp_index : int, default 0
The DCP index whose to-departure values are used.
- snapshot_instruction : SnapshotInstruction or bool, optional
Controls debugging output. If True, a trace of the calculation is written to standard output; if a SnapshotInstruction, the trace is written as it directs. This is keyword-only.
- Raises:
RuntimeError – If a path class’s forecast mean would be negative.