PathClass¶
- class passengersim.core.PathClass¶
Bases:
objectA path class: one booking class on one path.
A path class (also called an ODIF, for origin-destination itinerary fare) is the finest level of detail for O&D revenue management. It counts its own sales, keeps the booking history for its booking class on its path, and holds the forecasts made from that history. The fares it sells are either given to it, or found in the path’s market the first time they are needed (see fare).
- Parameters:
- path : Path
The path. If it already has a path class for booking_class, the new object refers to that path class instead of creating another. Otherwise a new path class is added to the path, taking its carrier’s decision price rule.
- booking_class : str
The booking class.
- fare : Fare or None, optional
A fare for the path class; see fare.
- history : History or dict, optional
The booking history to use if the path class does not have one yet: a History, a dict of arguments for creating one, or None (the default) for a default History.
- Raises:
TypeError – If path is not a Path, booking_class is not a str, fare is neither a Fare nor None, or history is neither a History, a dict nor None.
Methods
__init__(*args, **kwargs)Add fares to this path class.
The adjusted fare for the carrier's current timeframe.
The raw adjusted fare for the carrier's current timeframe.
The forecast revenue (decision price) of one sale in this path class.
Get the bucket that this path class maps to on one leg, for virtual nesting.
Create the Q forecast for this path class, if it does not have one.
Finish the current departure for this path class, and move its history on.
Set the bucket that this path class maps to on one leg, for virtual nesting.
Attributes
The seconds before departure that fcst_mean and fcst_std_dev refer to.
The adjusted fare in each timeframe, from Path.compute_fare_adjustments.
The booking class of this path class.
The cabin of this path class's fare (
Fare.cabin).The stored decision fare of this path class.
How this path class's forecast revenue (decision price) is found.
The fare of this path class (its first fare, if it has more than one).
The price of this path class's fare.
The forecast mean demand from now to departure, times forecast_multiplier.
The forecast standard deviation of demand to departure, times forecast_multiplier.
The active forecast of demand for this path class.
Multiplier applied to fcst_mean and fcst_std_dev.
Grand total revenue in this path class, after the burn period.
Grand total revenue in this path class by customer segment, after the burn period.
Grand total number of passengers sold in this path class, after the burn period.
Grand total passengers sold in this path class by customer segment, after the burn period.
Grand total of the priceable passengers in gt_sold, after the burn period.
The booking history of this path class.
An identifier for this path class,
"<path_id>-<booking_class>", such as"7-Y".Number of PathClass Python objects currently alive.
The smoothed average selling price of this path class, over all timeframes.
The smoothed average selling price of this path class, in each timeframe.
The ID of the path this path class belongs to.
This path class's share of the path's Q-equivalent (priceable) demand forecast.
The raw adjusted fare in each timeframe, from Path.compute_simple_fare_adjustments.
The smoothing factor for the optimization prices.
Revenue in each timeframe (DCP index) of the current departure.
Number of passengers sold in this path class in the current sample.
Passengers sold in each timeframe (DCP index) of the current departure.
Number of the passengers in sold who bought a priceable offer.
The forecast of yieldable demand for this path class.
- add_fare()¶
Add fares to this path class.
A path class has more than one fare with matrix pricing or branded fares. The fares are added in the order given.
- Parameters:
- *fares : Fare
The fares to add.
- Returns:
int – Always 0.
- Raises:
TypeError – If an argument is not a Fare. Then no fares are added.
- adjusted_at¶
The seconds before departure that fcst_mean and fcst_std_dev refer to.
The mid-timeframe forecast adjustment for daily reoptimization sets it; it is 0 otherwise. Setting it requires an int.
- adjusted_marginal_revenue¶
The adjusted fare in each timeframe, from Path.compute_fare_adjustments.
Entries that were never set are shown as the fare’s price. This is an empty tuple if fare adjustment has not been computed. Read-only.
- booking_class¶
The booking class of this path class.
Read-only; it is set when the path class is created.
- cabin_code¶
The cabin of this path class’s fare (
Fare.cabin).Reading it raises RuntimeError if the path class has no fare (see fare). Read-only.
- current_tf_adjusted_fare_price()¶
The adjusted fare for the carrier’s current timeframe.
This is the entry of adjusted_marginal_revenue at the carrier’s
current_tf_index, or the first or last entry if that index is out of range. If fare adjustment has not been computed, it is the fare’s price.- Parameters:
- floor : float, default -999999.0
The result is never less than this.
- nan_to_zero : bool, default False
If True, a NaN adjusted fare (for a class closed by an advance purchase restriction) is returned as 0.0.
- Returns:
float – The adjusted fare.
- Raises:
RuntimeError – If the path class has no fare (see fare).
ValueError – If fare adjustment has been computed but the fare has no carrier.
- current_tf_raw_adjusted_fare_price()¶
The raw adjusted fare for the carrier’s current timeframe.
The same as current_tf_adjusted_fare_price, but using raw_adjusted_marginal_revenue.
- Parameters:
- floor : float, default -999999.0
The result is never less than this.
- nan_to_zero : bool, default False
If True, a NaN raw adjusted fare is returned as 0.0.
- Returns:
float – The raw adjusted fare.
- Raises:
RuntimeError – If the path class has no fare (see fare).
ValueError – If fare adjustment has been computed but the fare has no carrier.
- decision_fare¶
The stored decision fare of this path class.
When it is positive, it is used as the path class’s decision price, for example to sort the path classes and to compute Q-equivalent demand. When it is 0 (the default), the fare’s price is used instead. This is separate from the forecast revenue that decision_price_rule gives. Setting it requires a non-negative number.
- decision_price_rule¶
How this path class’s forecast revenue (decision price) is found.
See
Carrier.decision_price_rulefor what each value does. A new path class copies the rule from its path’s carrier; without a carrier it is"unknown", which acts like"lowest". Setting it requires one of those strings.
- fare¶
The fare of this path class (its first fare, if it has more than one).
If no fare has been given, the fares are looked up in the path’s market: those with the same booking class as this path class and the same carrier as the path. Reading it raises RuntimeError if none can be found.
Setting it to a Fare makes that the path class’s only fare. Setting it to None, or deleting it, removes all the fares. If the path class has more than one fare, as with matrix pricing, setting it raises Exception; use add_fare instead. Setting it requires a Fare or None.
- fare_price¶
The price of this path class’s fare.
Reading it raises RuntimeError if the path class has no fare (see fare), and Exception if it has more than one, as with matrix pricing or branded fares. Read-only.
- fcst_mean¶
The forecast mean demand from now to departure, times forecast_multiplier.
The forecasting steps (such as Path.compute_forecasts and Path.update_forecasts) set it. Setting it stores the value before the multiplier, and requires a non-negative number.
- fcst_std_dev¶
The forecast standard deviation of demand to departure, times forecast_multiplier.
It is set along with fcst_mean. Setting it stores the value before the multiplier, and requires a non-negative number.
- forecast¶
The active forecast of demand for this path class.
This is the total forecast if hybrid forecasting is in use, which includes both priceable and yieldable demand. Otherwise it is the Y forecast, or the Q forecast if there is no Y forecast. If there is no forecast at all, a new Y forecast is created from the history (ValueError if there is no history). Read-only.
- forecast_multiplier¶
Multiplier applied to fcst_mean and fcst_std_dev.
The default is 1.0. Setting it replaces the multiplier, rather than multiplying onto it, and requires a number. Deleting it resets it to 1.0.
- get_fcst_revenue()¶
The forecast revenue (decision price) of one sale in this path class.
How it is found depends on decision_price_rule; see
Carrier.decision_price_rule. For the"weighted"rule, dcp_index selects the timeframe in optimization_price_vector. The fallback is the lowest price among the path class’s fares.- Parameters:
- dcp_index : int, default -1
The timeframe index for the
"weighted"rule. The default, -1, uses the overall optimization_price.
- Returns:
float – The forecast revenue.
- Raises:
RuntimeError – If the path class has no fare, or, with the
"brand"rule, no fare with the"economy"brand.
- get_index()¶
Get the bucket that this path class maps to on one leg, for virtual nesting.
See set_index.
- Parameters:
- leg_number : int
Position of the leg on the path, starting at 0.
- Returns:
int – Index of the bucket on that leg.
- Raises:
IndexError – If leg_number is negative or past the end of the mapping.
- gt_revenue¶
Grand total revenue in this path class, after the burn period.
Resetting the counters does not change it. Setting it requires a non-negative number.
- gt_revenue_by_segment¶
Grand total revenue in this path class by customer segment, after the burn period.
Reading it returns a new dict keyed by segment. Read-only.
- gt_sold¶
Grand total number of passengers sold in this path class, after the burn period.
Resetting the counters does not change it. Setting it requires a non-negative int.
- gt_sold_by_segment¶
Grand total passengers sold in this path class by customer segment, after the burn period.
Reading it returns a new dict keyed by segment, such as
"business". Read-only.
- gt_sold_priceable¶
Grand total of the priceable passengers in gt_sold, after the burn period.
Resetting the counters does not change it. Setting it requires a non-negative int.
- history¶
The booking history of this path class.
Reading it raises ValueError if there is none. Setting it requires a History (not None), and it cannot be deleted. Setting it does not relink the path class’s existing forecasts to the new history.
- identifier¶
An identifier for this path class,
"<path_id>-<booking_class>", such as"7-Y".Read-only.
- initialize_q_forecast()¶
Create the Q forecast for this path class, if it does not have one.
The new forecast shares the path class’s history. See q_forecast.
- next_departure()¶
Finish the current departure for this path class, and move its history on.
This updates the optimization prices from the departure’s sales by timeframe (see optimization_price), sets sold_by_dcp and revenue_by_dcp back to zero, and moves the history buffer on to the next departure.
Path.next_departurecalls it for each path class, so it is mostly called directly for unit testing.- Returns:
int – Always 0.
- Raises:
ValueError – If the path class has no history.
- num_objects¶
Number of PathClass Python objects currently alive.
This is a count over all path classes, not a property of this one. It was used to find memory leaks. Read-only.
- optimization_price¶
The smoothed average selling price of this path class, over all timeframes.
next_departure updates it from the departure’s sales by exponential smoothing with revenue_alpha, or sets it to the first nonzero average. The
"weighted"and"weighted_scalar"decision price rules use it. Setting it requires a non-negative number.
- optimization_price_vector¶
The smoothed average selling price of this path class, in each timeframe.
This is optimization_price for each timeframe (DCP index); the
"weighted"decision price rule uses it. Reading it returns a new list. Setting it requires a list of numbers, which replaces the values.
- path_id¶
The ID of the path this path class belongs to.
It is copied from
Path.path_idwhen the path class is created, and is not updated if that changes later. Read-only.
- q_forecast¶
This path class’s share of the path’s Q-equivalent (priceable) demand forecast.
Q forecasting is done for the path as a whole; Path.allocate_q_demand stores each path class’s share here. Reading it raises ValueError if there is no Q forecast yet; see initialize_q_forecast. Read-only.
- raw_adjusted_marginal_revenue¶
The raw adjusted fare in each timeframe, from Path.compute_simple_fare_adjustments.
Entries that were never set are shown as the fare’s price. This is an empty tuple if fare adjustment has not been computed. Read-only.
- revenue_alpha¶
The smoothing factor for the optimization prices.
This value is shared by all path classes: setting it on one changes it for all of them. The default is 0.1. Setting it requires a non-negative number.
- revenue_by_dcp¶
Revenue in each timeframe (DCP index) of the current departure.
Like sold_by_dcp, but each sale adds its price times its number of passengers. Setting it requires a list of numbers, which replaces the values.
- set_index()¶
Set the bucket that this path class maps to on one leg, for virtual nesting.
Under virtual nesting (DAVN) control, availability and sales for the path class use the bucket at this index on each leg. Mappings for other legs are not changed. The mapping grows as needed, with new entries set to 0.
- Parameters:
- leg_number : int
Position of the leg on the path, starting at 0.
- index : int
Index of the bucket on that leg.
- Returns:
int – Always 0.
- Raises:
IndexError – If either argument is negative.
- sold¶
Number of passengers sold in this path class in the current sample.
Resetting the counters sets it back to zero. Setting it requires a non-negative int.
- sold_by_dcp¶
Passengers sold in each timeframe (DCP index) of the current departure.
Each sale adds to the entry for the timeframe it was made in. At the end of the departure, next_departure uses these to update the optimization prices, then sets them to zero. Reading it returns a new list. Setting it requires a list of ints, which replaces the values.
- sold_priceable¶
Number of the passengers in sold who bought a priceable offer.
A sale is priceable when the customer bought a lowest-priced available offer on the chosen path. Q forecasting uses these sales. Resetting the counters sets it back to zero. Setting it requires a non-negative int.
- y_forecast¶
The forecast of yieldable demand for this path class.
If hybrid forecasting is not in use, this is the same as forecast. Reading it raises ValueError if there is no Y forecast yet. Read-only.