Path

class passengersim.core.Path

Bases: object

A 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)

accumulate_forecasts

Add this path's path class forecasts to the matching buckets on its legs.

add_booking_class

Add a path class for a booking class to this path.

add_carrier

Set the carrier that operates this path.

add_leg

Add legs to the end of this path.

add_order

Add an order to the current sample's order history.

add_path_class

Does nothing (deprecated).

allocate_q_demand

Split the path's Q demand forecast among its path classes.

capture_dcp

Record booking history for this path at a data collection point (DCP).

check_avail

Check whether a fare is available on this path, under the carrier's RM control.

combine_forecasts

Combine each path class's Y and Q forecasts into a total forecast.

compute_classless_q_equivalent_history

Store the path's Q-equivalent demand for a timeframe, from classless orders.

compute_conditional_q_forecast

Compute the path-level conditional Q (priceable) demand forecast.

compute_fare_adjustments

Compute the adjusted fares for this path's path classes.

compute_forecasts

Compute the yieldable (Y) demand forecast for each of this path's path classes.

compute_hybrid_forecasts

Compute the hybrid forecasts for this path: Y for each path class, and Q for the path.

compute_q_equivalent

Compute this path's Q-equivalent demand from the current sample's sales.

compute_simple_fare_adjustments

Compute the raw adjusted fares and sell-up probabilities for this path's path classes.

contains_leg_id

Check whether this path includes the leg with a given leg ID.

detruncate_demand

Untruncate (detruncate) the historical demand for this path's path classes.

get_class_decision_fare

Get the stored decision fare of one of this path's path classes.

get_class_fcst_mean

Get the forecast mean demand of one of this path's path classes.

get_class_fcst_std_dev

Get the forecast standard deviation of one of this path's path classes.

get_class_sold

Get the number sold in one of this path's path classes, in the current sample.

get_displacement_adjusted_fare

The part of a fare to credit to one leg, after displacement costs.

get_f_star

Get the classless continuous pricing F* value for a timeframe.

get_forecast_data

Get this path's path class forecasts and booking history as tables.

get_leg_arr_time

Get the arrival time of one of this path's legs.

get_leg_arr_time_local

Get the local arrival time of one of this path's legs.

get_leg_bid_price

Get the stored bid price of one of this path's legs.

get_leg_capacity

Get the capacity of one of this path's legs.

get_leg_carrier

Get the carrier code of one of this path's legs.

get_leg_dep_time

Get the departure time of one of this path's legs.

get_leg_dep_time_local

Get the local departure time of one of this path's legs.

get_leg_dest

Get the destination airport of one of this path's legs.

get_leg_equipment

Get the equipment code of one of this path's legs.

get_leg_fltno

Get the flight number of one of this path's legs.

get_leg_id

Get the leg ID of one of this path's legs.

get_leg_orig

Get the origin airport of one of this path's legs.

get_orders

Get the orders recorded for one sample, as a list of dictionaries.

get_total_bid_price

Total of the leg bid prices on this path, for one seat.

get_total_distance

Total distance of this path's legs.

mid_timeframe_forecast_interpolation

Adjust the path class forecasts for part of a timeframe having passed.

new_forecast

Create a new ForecastGroup that follows this path.

next_departure

Move this path's history buffers on to the next departure.

num_classes

Number of path classes on this path.

num_deps

Number of departures in the history (not implemented).

num_legs

Number of legs on this path.

report_total_bid_price

Total of the reportable leg bid prices on this path, for one seat.

reset_counters

Reset this path's sales counters for a new sample.

set_class_decision_fare

Set the stored decision fare of one of this path's path classes.

set_class_fcst_mean

Set the forecast mean demand of one of this path's path classes.

set_class_fcst_std_dev

Set the forecast standard deviation of one of this path's path classes.

set_class_sold

Set the number sold in one of this path's path classes.

update_forecasts

Set each path class's forecast mean and standard deviation from its total forecast.

Attributes

arr_time

Arrival time of the last leg, as a Unix timestamp.

carrier

The carrier that operates this path.

carrier_name

The code of the carrier that operates this path.

delta_t

Difference between local arrival and local departure time, in seconds.

dep_time

Departure time of the first leg, as a Unix timestamp.

dest

Destination airport code.

duration

Total travel time of the path, in minutes.

early_path

Whether this is the earliest path in its market (not implemented).

forecast

Access to this path's path class forecasts through the ForecastGroup API.

gt_revenue

Grand total revenue from this path, after the burn period.

gt_sold

Grand total number of passengers sold on this path, after the burn period.

gt_sold_priceable

Grand total of the priceable passengers in gt_sold, after the burn period.

hhi

Herfindahl-Hirschman index of this path's carrier at the market's origin.

late_path

Whether this is the latest path in its market (not implemented).

leg_ids

The leg IDs of this path's legs, in order.

legs

This path's legs, in order.

market

The market that this path serves, or None.

max_hhi

The largest Herfindahl-Hirschman index of any carrier at the market's origin.

minimum_connect_time

Total of the minimum connect times for all connections on the path.

num_objects

Number of Path Python objects currently alive.

orig

Origin airport code.

path_id

Unique ID for this path.

path_quality_index

Path quality index, used in the choice model's path quality term.

pathclasses

An iterator over the PathClass objects on this path.

price

Default price for this path (deprecated).

q_forecast

The path-level Q (priceable) demand forecast, or None if there isn't one.

revenue

Revenue from this path in the current sample.

sold

Number of passengers sold on this path in the current sample.

sold_priceable

Number of the passengers in sold whose offer was priceable.

total_bid_price

Total of the leg bid prices on this path, for one seat.

truncation_rule

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 sold and sold_priceable counts 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 (see Carrier.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 - 1 is 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 None or "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_rule gives.

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.