Frat5

class passengersim.core.Frat5

Bases: object

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

Add values to the end of the curve.

adjust_fare_ki

Adjusted fare, using the KI method (due to Karl Isler).

adjust_fare_mr

Adjusted fare, using the MR (marginal revenue) method (due to Thomas Fiig).

cbc_modifier

Price modifier for class-based continuous pricing (CBC).

get_val

Get the Frat5 value for one timeframe.

print

A text listing of the curve's values.

sellup_probability

Probability that a customer who would buy the low fare buys up to the high fare.

set_val

Set the Frat5 value for one existing timeframe.

Attributes

fare_adjustment_scale

Default scale on the Frat5 values for fare adjustment.

max_cap

Cap on Q-equivalent demand, as a multiple of priceable sales.

name

Name of the curve.

num_values

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’s cp_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.