Frat5¶
- class passengersim.core.Frat5¶
Bases:
objectA Frat5 curve: how willing customers are to buy up to higher fares, by timeframe.
A Frat5 value is the ratio of a higher fare to the lowest fare at which half of the customers who would buy the lowest fare buy up to the higher one; a larger value means customers are less price sensitive. The curve holds one value per timeframe (DCP index), usually rising as departure approaches. Q forecasting uses it to turn priceable sales into Q-equivalent demand, fare adjustment (the MR and KI methods) uses it to adjust fares, and the CBC and classless continuous pricing algorithms use it to mark up prices.
- Parameters:
- name : str
Name of the curve. The name
"test"loads the 16 values of PODS test curve C (with their days prior) before any values.- values : sequence of float, or mapping of int to float, optional
Frat5 values to add, by timeframe. A sequence is added in order. A mapping is keyed by days prior to departure, and its values are added from the largest key to the smallest, so the first value is for the earliest timeframe; the keys only set the order and are not stored. Each value must be convertible to float.
- max_cap : float, optional
See max_cap. The default is 10.0.
- fare_adjustment_scale : float, optional
See fare_adjustment_scale. The default is 1.0.
- __init__ : The arguments are used when the object is created; calling
- properties : again has no effect. Unlike the
- and : max_cap
- here. : fare_adjustment_scale accept an int
- Raises:
TypeError – If name is not a str, values is neither a sequence nor a mapping, a mapping key is not an int, or a value cannot be converted to float.
Methods
__init__(*args, **kwargs)Add values to the end of the curve.
Adjusted fare, using the KI method (due to Karl Isler).
Adjusted fare, using the MR (marginal revenue) method (due to Thomas Fiig).
Price modifier for class-based continuous pricing (CBC).
Get the Frat5 value for one timeframe.
A text listing of the curve's values.
Probability that a customer who would buy the low fare buys up to the high fare.
Set the Frat5 value for one existing timeframe.
Attributes
Default scale on the Frat5 values for fare adjustment.
Cap on Q-equivalent demand, as a multiple of priceable sales.
Name of the curve.
Number of values in the curve, one per timeframe.
- add_vals()¶
Add values to the end of the curve.
Each value is for the next timeframe. The values must be floats (numpy floats are accepted); an int raises TypeError, and the values before it are still added.
- Parameters:
- *vals : float
The Frat5 values to add.
- Returns:
int – The number of values given.
- Raises:
TypeError – If a value is not a float.
- adjust_fare_ki()¶
Adjusted fare, using the KI method (due to Karl Isler).
The adjusted fare is
(p1 * hi_fare - p2 * next_higher_fare) / (p1 - p2), where p1 and p2 are the sellup probabilities from low_fare to hi_fare and to next_higher_fare (see sellup_probability, with scale_factor). If p1 equals p2, hi_fare is returned unadjusted. This is mostly used for unit testing and debugging.- Parameters:
- dcp_index : int
The timeframe (DCP) index, starting at 0.
- hi_fare : float
The fare to adjust.
- next_higher_fare : float
The next higher fare above hi_fare.
- low_fare : float
The lowest fare.
- scale_factor : float, default 1.0
How far to move the Frat5 value toward 1.0, as in sellup_probability. Unlike adjust_fare_mr, the default is 1.0, not fare_adjustment_scale.
- debug : bool or SnapshotInstruction, optional
If True, write the intermediate values to stdout.
- Returns:
float – The adjusted fare.
- Raises:
IndexError – If dcp_index is negative or past the last value.
TypeError – If debug is neither a bool nor a SnapshotInstruction.
- adjust_fare_mr()¶
Adjusted fare, using the MR (marginal revenue) method (due to Thomas Fiig).
The adjusted fare is
hi_fare - low_fare * (f5 - 1) / ln(2), where f5 is the timeframe’s Frat5 value moved toward 1.0 by scale_factor:f5 = 1 + scale_factor * (value - 1). This is mostly used for unit testing and debugging.- Parameters:
- tf_index : int
The timeframe (DCP) index, starting at 0.
- hi_fare : float
The fare to adjust.
- low_fare : float
The lowest fare.
- scale_factor : float, optional
How far to move the Frat5 value toward 1.0. If it is omitted or negative, fare_adjustment_scale is used.
- debug : bool, optional
If true, write the intermediate values to stderr.
- Returns:
float – The adjusted fare.
- Raises:
IndexError – If tf_index is negative or past the last value.
- cbc_modifier()¶
Price modifier for class-based continuous pricing (CBC).
From Long and Belobaba (2023). The modifier is
low_fare * (f5 - 1) / ln(2), where f5 is the timeframe’s Frat5 value. The CBC algorithm adds it, scaled by the carrier’scp_scale, to the total bid price.- Parameters:
- dcp_index : int
The timeframe (DCP) index, starting at 0.
- low_fare : float
The lowest fare.
- debug : bool, optional
If true, write the intermediate values to stderr.
- Returns:
float – The modifier.
- Raises:
IndexError – If dcp_index is negative or past the last value.
- fare_adjustment_scale¶
Default scale on the Frat5 values for fare adjustment.
Fare adjustment moves each Frat5 value toward 1.0 by a scale: the value used is
1 + scale * (value - 1), so 1.0 uses the curve as it is and 0.0 turns the adjustment off. This is the scale adjust_fare_mr uses when it is not given one; RM steps usually pass their own. The default is 1.0. Setting it requires a float (an int is rejected), and it cannot be deleted.
- get_val()¶
Get the Frat5 value for one timeframe.
- Parameters:
- dcp : int
The timeframe (DCP) index, starting at 0.
- Returns:
float – The Frat5 value.
- Raises:
IndexError – If dcp is negative or past the last value.
- max_cap¶
Cap on Q-equivalent demand, as a multiple of priceable sales.
When Q forecasting turns a path class’s priceable sales into Q-equivalent demand (sales divided by the sellup probability), the result is capped at the sales times this value. The default is 10.0. Setting it requires a float (an int is rejected), and it cannot be deleted.
- name¶
Name of the curve.
Read-only; it is set when the Frat5 is created.
- num_values¶
Number of values in the curve, one per timeframe.
Read-only; add values with add_vals.
- print()¶
A text listing of the curve’s values.
Despite its name, it returns the text rather than printing it. Each line shows a timeframe index, its days prior (0 unless the curve was created with the name
"test") and its value.- Returns:
str – The listing.
- sellup_probability()¶
Probability that a customer who would buy the low fare buys up to the high fare.
The probability is
exp(-ln(2) * (hi_fare / low_fare - 1) / (f5 - 1)), where f5 is the timeframe’s Frat5 value moved toward 1.0 by scale:f5 = 1 + scale * (value - 1). It is 0.5 when the fare ratio equals f5, and 1.0 when the fares are equal. This is mostly used for unit testing and debugging; the simulation calls the same calculation in the core.- Parameters:
- dcp_index : int
The timeframe (DCP) index, starting at 0.
- hi_fare : float
The higher fare.
- low_fare : float
The lowest fare.
- scale : float, default 1.0
How far to move the Frat5 value toward 1.0, as above. A scale of 0 or less returns 0.0.
- Returns:
float – The sellup probability. If f5 is 1.0, it is 0.0, or NaN when the fares are equal.
- Raises:
IndexError – If dcp_index is negative or past the last value.
- set_val()¶
Set the Frat5 value for one existing timeframe.
- Parameters:
- dcp : int
The timeframe (DCP) index, starting at 0. It must be an existing index; use add_vals to add values.
- val : float
The new Frat5 value.
- Returns:
int – Always 0.
- Raises:
IndexError – If dcp is negative or past the last value.