ForecastGroup¶

class passengersim.core.ForecastGroup¶

Bases: object

ForecastGroup object.

Methods

`__init__`(args, *kwargs)
`adjust_forecast_means`	Adjust forecast means by a ratio factor.
`allocate_q_demand`	Allocate aggregate Q demand back to individual booking class level.
`clear_forecast_means_adjustment`	Clear the forecast mean multiplier.
`combine_forecasts`	Combine Y and Q forecasts into a total forecast.
`compute_conditional_q_forecast`	Compute the conditional Q forecast.
`compute_fare_adjustments`	Compute fare adjustments for all booking classes.
`compute_forecasts`	Run the forecasting method on all booking classes.
`compute_hybrid_forecasts`	Run the hybrid forecast models for all booking classes.
`compute_sellup_probability`	Compute sell-up probability for each booking class.
`compute_simple_fare_adjustments`	Compute simple (unweighted) fare adjustments for all booking classes.
`detruncate_demand`	Demand untruncation for all booking classes.
`detruncate_q_demand`	Demand untruncation for priceable (price-sensitive, Q) demand.
`detruncate_yieldable_demand`	Demand untruncation for yieldable (non-price-sensitive) demand.
`follow`	Follow the history and DCP data of a leg.
`get_adjusted_marginal_revenue`	Get adjusted marginal revenue (adjusted fare prices) for each booking class.
`get_advpurch_max_tf_indexes`	Timeframe indexes where each booking class closes due to an AP restriction.
`get_current_mean`	Current current forecast mean to departure
`get_current_stdev`	Current forecast standard deviation to departure
`get_customer_prices`	Customer prices on each booking class.
`get_forecast_data`
`get_forecast_means_adjustment`	Get all forecast mean multipliers.
`get_history`	Get the history for a booking class, or all histories.
`get_mean_in_timeframe`	Get the mean demand within each timeframe for each booking class.
`get_mean_to_departure`	Get the mean demand from now to departure for each booking class.
`get_q_mean_in_timeframe`	Get the aggregate Q forecast mean within each timeframe.
`get_q_mean_to_departure`	Get the aggregate Q forecast mean from now to departure.
`get_q_stdev_in_timeframe`	Get the aggregate Q forecast standard deviation within each timeframe.
`get_q_stdev_to_departure`	Get the aggregate Q forecast standard deviation from now to departure.
`get_stdev_in_timeframe`	Get the standard deviation of demand within each timeframe.
`get_stdev_to_departure`	Get the standard deviation of demand from now to departure.
`is_freestanding`	Check if this ForecastGroup is a free-standing forecast.
`move_forecast_pointers`	Adjust the point forecasts (mean and std_dev) to a different position on the vectors.
`sellup_probability`	Get cached sell-up probability for each booking class.
`set_adjusted_marginal_revenue`	Set adjusted marginal revenue (adjusted fare prices) for booking classes.
`set_mean_in_timeframe`	Set the mean demand within each timeframe for each booking class.
`set_mean_to_departure`	Set the mean demand from now to departure for each booking class.
`set_stdev_in_timeframe`	Set the standard deviation of demand within each timeframe for each booking class.
`set_stdev_to_departure`	Set the standard deviation of demand from now to departure for each booking class.
`update_conditional_forecast`
`update_q_forecast`

Attributes

`dcp_days_prior`	Days prior for DCPs (i.e. the start time of each timeframe).
`label`

adjust_forecast_means()¶

Adjust forecast means by a ratio factor.

Parameters:

ratio : float: The ratio by which to scale the forecast means.
current_simulation_time : float: The current simulation time (used to throttle adjustments).
minimum_days_between_adjustments : int: Minimum number of simulation days that must pass between consecutive adjustments.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.

Returns:

int – 1 if the forecast means were adjusted, 0 otherwise.

allocate_q_demand()¶

Allocate aggregate Q demand back to individual booking class level.

Parameters:

frat5 : Frat5: The Frat5 object to use for sell-up probability calculations.
dcp_index : int, optional: The DCP index for which to allocate demand. Default is 0.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.
allocation_algorithm : {'tf', 'dep'} or None, optional: The allocation algorithm to use. ‘tf’ allocates within timeframe; ‘dep’ allocates to departure. Default is ‘tf’.

clear_forecast_means_adjustment()¶

Clear the forecast mean multiplier.

Parameters:

snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.

combine_forecasts()¶

Combine Y and Q forecasts into a total forecast.

Parameters:

dcp_index : int, optional: The DCP index for which to combine forecasts. Default is 0.
rollup_algorithm : {'tf', 'dep'} or None, optional: The rollup algorithm to use when combining forecasts. ‘tf’ rolls up within timeframe; ‘dep’ rolls up to departure. Default is ‘tf’.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.

compute_conditional_q_forecast()¶

Compute the conditional Q forecast.

Parameters:

frat5 : Frat5: The Frat5 object to use for Q-forecasting.
dcp_index : int, optional: The DCP index from which to start the forecast. Default is 0.
regression_weight : {'sellup', 'sellup^2', 'fare', 'none'} or None, optional: Weighting method for regression. Default is None (no weighting).
max_cap : float, optional: Maximum capacity inflation factor for Q-forecasting. Default is 0.0.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot of the forecast will be written based on these instructions.
partial_tf_weight_adjustment : bool, default False: Whether to apply partial timeframe weight adjustments.
variance_is_ratio_of_mean : float, default 0.0: If nonzero, sets variance as a ratio of the mean demand.

compute_fare_adjustments()¶

Compute fare adjustments for all booking classes.

Parameters:

algorithm : {'MR', 'mr', 'KI', 'ki'} or None: The fare adjustment algorithm to use. ‘MR’ applies the market response model; ‘KI’ applies the Kambour-Imber model. If None, all fare adjustments are cleared.
frat5 : Frat5: The Frat5 object to use for sell-up probability calculations.
scale_factor : float, optional: A scaling factor applied to the fare adjustments. Default is 1.0.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.
sort_pathclasses : bool, default True: Whether to sort path classes before computing adjustments.
weighted_by_ratio : bool, default True: Whether to weight adjustments by the Q-to-Y forecast ratio.

compute_forecasts()¶

Run the forecasting method on all booking classes.

Parameters:

dcp_index : int: The DCP index from which to compute the forecasts.
algorithm : str, optional: The name of the forecast algorithm to use (‘exp_smoothing’ or ‘additive_pickup’). Required when recompute is True.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.
recompute : bool, optional: If True, recompute the forecast. If False, only update cached values. Default behavior depends on whether an algorithm is provided.
event_time : int, optional: The time of the event that triggered the forecast computation.
which_data : str, optional: Which demand data to use (‘t’ for total, ‘q’/’p’ for priceable, ‘y’ for yieldable). Default is ‘t’.
alpha : float, default 0.15: Smoothing factor for exponential smoothing (keyword-only).
return_vectors : bool, default False: If True, return a dictionary of forecast vectors for each booking class. Primarily used for debugging and testing.

Returns:

None or dict[str, ForecastVectors] – Returns None unless return_vectors is True, in which case returns a dictionary mapping booking class names to ForecastVectors.

compute_hybrid_forecasts()¶

Run the hybrid forecast models for all booking classes.

Parameters:

dcp_index : int: Compute forecasts only from this DCP to departure.
algorithm : {'exp_smoothing', 'additive_pickup'}: Forecasting algorithm to use.
frat5 : Frat5: Frat5 object to use for Q-forecasting.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot of the forecast will be written based on these instructions.
recompute : bool, default True: If True, recompute the entire forecast. Otherwise, the forecast cached values will be moved to a new dcp_index.
pods_init : bool, default False: Whether to use PODS-style initialization.
alpha : float, default 0.15: Smoothing factor for exponential smoothing. This is a keyword-only argument.

compute_sellup_probability()¶

Compute sell-up probability for each booking class.

Parameters:

frat5 : Frat5: The Frat5 object to use for sell-up probability calculations.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.

compute_simple_fare_adjustments()¶

Compute simple (unweighted) fare adjustments for all booking classes.

Parameters:

algorithm : {'MR', 'mr', 'KI', 'ki'} or None: The fare adjustment algorithm to use. If None, fare adjustments are set to a “no-op” state.
frat5 : Frat5: The Frat5 object to use for sell-up probability calculations.
scale_factor : float, optional: A scaling factor applied to the fare adjustments. Default is 1.0.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.

dcp_days_prior¶

Days prior for DCPs (i.e. the start time of each timeframe).

A tuple of integers giving the number of days prior to departure at the beginning of each timeframe (i.e. at the data collection points, or DCPs). Returns None if not set.

detruncate_demand()¶

Demand untruncation for all booking classes.

Parameters:

dcp_index : int: The DCP index from which to run untruncation.
algorithm : str: The untruncation algorithm to use (e.g., ‘em’ for EM algorithm).
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.
maxiter : int, default 20: Maximum number of iterations for the EM algorithm.
tolerance : float, default 0.01: Convergence tolerance for the EM algorithm.
pods_initialization : bool, default False: Whether to use PODS-style initialization for the EM algorithm.
minimum_mu : float, default 0.01: Minimum value for the mean (mu) in the EM algorithm. When mu is less than this value, the function returns 0.
minimum_sigma : float, default 0.1: Minimum value for the standard deviation (sigma) in the EM algorithm. When sigma falls below this value it is set to this value instead.
which_data : str, optional: Which demand type to detruncate: ‘t’ for total, ‘q’/’p’ for priceable, ‘y’ for yieldable. Default is total.

detruncate_q_demand()¶

Demand untruncation for priceable (price-sensitive, Q) demand.

Parameters:

snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.
maxiter : int, default 20: Maximum number of iterations for the EM algorithm.
tolerance : float, default 0.01: Convergence tolerance for the EM algorithm.
pods_initialization : bool, default False: Whether to use PODS-style initialization for the EM algorithm.
minimum_mu : float, default 0.01: Minimum value for the mean (mu) in the EM algorithm. When mu is less than this value, the function returns 0.
minimum_sigma : float, default 0.1: Minimum value for the standard deviation (sigma) in the EM algorithm. When sigma falls below this value it is set to this value instead.

Returns:

ForecastGroup – Returns self to allow method chaining.

detruncate_yieldable_demand()¶

Demand untruncation for yieldable (non-price-sensitive) demand.

Parameters:

snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.
maxiter : int, default 20: Maximum number of iterations for the EM algorithm.
tolerance : float, default 0.01: Convergence tolerance for the EM algorithm.
pods_initialization : bool, default False: Whether to use PODS-style initialization for the EM algorithm.
minimum_mu : float, default 0.01: Minimum value for the mean (mu) in the EM algorithm. When mu is less than this value, the function returns 0.
minimum_sigma : float, default 0.1: Minimum value for the standard deviation (sigma) in the EM algorithm. When sigma falls below this value it is set to this value instead.

Returns:

ForecastGroup – Returns self to allow method chaining.

follow()¶

Follow the history and DCP data of a leg.

Parameters:

other : Leg: The Leg object whose history and DCP data this ForecastGroup should follow.

get_adjusted_marginal_revenue()¶

Get adjusted marginal revenue (adjusted fare prices) for each booking class.

Returns:: dict[str, numpy.ndarray] – Dictionary mapping booking class names to arrays of adjusted marginal revenue (interpreted as adjusted fare prices) across timeframes.
Raises:: ValueError – If the underlying forecast or Q-forecast data required to compute the adjusted marginal revenue is not initialized or available.

get_advpurch_max_tf_indexes()¶: Timeframe indexes where each booking class closes due to an AP restriction.

get_current_mean()¶: Current current forecast mean to departure

get_current_stdev()¶: Current forecast standard deviation to departure

get_customer_prices()¶: Customer prices on each booking class.

get_forecast_data()¶

get_forecast_means_adjustment()¶

Get all forecast mean multipliers.

Returns:: dict[str, float]

get_history()¶

Get the history for a booking class, or all histories.

Parameters:

booking_class : str, optional: The booking class name to retrieve history for. If not provided, returns a dictionary mapping all booking class names to their History objects.
detruncated : {None, 'total', 'yieldable', 'priceable'}, default None: If set to a string, return the detruncated histories according to the value. If omitted or None, return the actual raw history. If detruncated histories are requested but not available, raises a ValueError.

Returns:

History or dict[str, History] – If booking_class is given, returns the History object for that class. If not given, returns a dict of all booking class histories.

Raises:

KeyError – If booking_class is provided but not found in this forecast.
ValueError – If detruncated is requested but not available.

get_mean_in_timeframe()¶

Get the mean demand within each timeframe for each booking class.

Parameters:

use_multiplier : bool or float or None, optional: Controls the forecast multiplier. If False, no multiplier is applied (equivalent to 1.0). If a number, use that value as the multiplier. If True, None, or omitted, the default multiplier stored on this ForecastGroup is used.
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to use: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.

Returns:

dict[str, numpy.ndarray] – Dictionary mapping booking class names to arrays of mean demand within each timeframe.

get_mean_to_departure()¶

Get the mean demand from now to departure for each booking class.

Parameters:

use_multiplier : bool or float or None, optional: Controls the forecast multiplier. If False, no multiplier is applied (equivalent to 1.0). If a number, use that value as the multiplier. If True, None, or omitted, the default multiplier stored on this ForecastGroup is used.
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to use: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.

Returns:

dict[str, numpy.ndarray] – Dictionary mapping booking class names to arrays of mean demand from the current DCP to departure.

get_q_mean_in_timeframe()¶

Get the aggregate Q forecast mean within each timeframe.

Returns:: numpy.ndarray – Array of mean Q demand within each timeframe, for the aggregate Q forecast.
Raises:: ValueError – If the Q forecast has not been initialized.

get_q_mean_to_departure()¶

Get the aggregate Q forecast mean from now to departure.

Returns:: numpy.ndarray – Array of mean Q demand from the current DCP to departure, for the aggregate Q forecast.
Raises:: ValueError – If the Q forecast has not been initialized.

get_q_stdev_in_timeframe()¶

Get the aggregate Q forecast standard deviation within each timeframe.

Returns:: numpy.ndarray – Array of standard deviation of Q demand within each timeframe, for the aggregate Q forecast.
Raises:: ValueError – If the Q forecast has not been initialized.

get_q_stdev_to_departure()¶

Get the aggregate Q forecast standard deviation from now to departure.

Returns:: numpy.ndarray – Array of standard deviation of Q demand from the current DCP to departure, for the aggregate Q forecast.
Raises:: ValueError – If the Q forecast has not been initialized.

get_stdev_in_timeframe()¶

Get the standard deviation of demand within each timeframe.

Parameters:

use_multiplier : bool or float or None, optional: Controls the forecast multiplier. If False, no multiplier is applied (equivalent to 1.0). If a number, use that value as the multiplier. If True, None, or omitted, the default multiplier stored on this ForecastGroup is used.
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to use: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.

Returns:

dict[str, numpy.ndarray] – Dictionary mapping booking class names to arrays of standard deviation of demand within each timeframe.

get_stdev_to_departure()¶

Get the standard deviation of demand from now to departure.

Parameters:

use_multiplier : bool or float or None, optional: Controls the forecast multiplier. If False, no multiplier is applied (equivalent to 1.0). If a number, use that value as the multiplier. If True, None, or omitted, the default multiplier stored on this ForecastGroup is used.
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to use: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.

Returns:

dict[str, numpy.ndarray] – Dictionary mapping booking class names to arrays of standard deviation of demand from the current DCP to departure.

is_freestanding()¶

Check if this ForecastGroup is a free-standing forecast.

Returns:: bool – True if this is a free-standing forecast not attached to a leg, False if it is following a leg’s history.

label¶

move_forecast_pointers()¶

Adjust the point forecasts (mean and std_dev) to a different position on the vectors.

Parameters:

dcp_index : int, optional: The index of the desired timeframe for the pointer.
days_prior : float, optional: The number of days prior to departure for the pointer. This can be used instead of dcp_index, you cannot provide both.
snapshot_instruction : SnapshotInstruction, optional: If not None, a snapshot will be written based on these instructions.

sellup_probability()¶

Get cached sell-up probability for each booking class.

Returns:: dict[str, numpy.ndarray] – Dictionary mapping booking class names to arrays of sell-up probabilities across timeframes.

set_adjusted_marginal_revenue()¶

Set adjusted marginal revenue (adjusted fare prices) for booking classes.

Parameters:

values : dict[str, array-like]: Dictionary mapping booking class identifiers (or booking class names) to vectors (array-like) of adjusted marginal revenue (adjusted fare prices) across timeframes. Each vector must have the same length as the target forecast’s timeframe vector.
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to set values for: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.
partial_ok : bool, default False: If True, missing keys in values will be ignored; if False (the default), a KeyError is raised for any missing booking class.

Returns:

None

Raises:

KeyError – If a booking class key is missing from values and partial_ok is False.
ValueError – If the target forecast is missing, vector lengths do not match, or values contain invalid numbers.
TypeError – If values is not a mapping or the provided vectors are not array-like.

set_mean_in_timeframe()¶

Set the mean demand within each timeframe for each booking class.

Parameters:

values : dict[str, array-like]: Dictionary mapping booking class identifiers (or booking class names) to vectors (array-like) of mean demand within each timeframe. Each vector must have the same length as the forecast’s mean_in_timeframe vector.
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to set: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.
partial_ok : bool, default False: If True, missing keys in values will be ignored; if False (the default), a KeyError is raised for any missing booking class.

Returns:

None

Raises:

KeyError – If a booking class key is missing from values and partial_ok is False.
ValueError – If the target forecast is missing, vector lengths do not match, or vectors contain negative values.
TypeError – If values is not a mapping or the provided vectors are not array-like.

set_mean_to_departure()¶

Set the mean demand from now to departure for each booking class.

Parameters:

values : dict[str, array-like]: Dictionary mapping booking class identifiers (or booking class names) to vectors (array-like) of mean demand from the current DCP to departure. Each vector must have the same length as the forecast’s mean_to_departure vector.
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to set: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.
partial_ok : bool, default False: If True, missing keys in values will be ignored; if False (the default), a KeyError is raised for any missing booking class.

Returns:

None

Raises:

KeyError – If a booking class key is missing from values and partial_ok is False.
ValueError – If the target forecast is missing, vector lengths do not match, or vectors contain negative values.
TypeError – If values is not a mapping or the provided vectors are not array-like.

set_stdev_in_timeframe()¶

Set the standard deviation of demand within each timeframe for each booking class.

Parameters:

values : dict[str, array-like]: Dictionary mapping booking class identifiers (or booking class names) to vectors (array-like) of standard deviation within each timeframe. Each vector must have the same length as the forecast’s stdev_in_timeframe vector and contain non-negative values (or NaN where appropriate).
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to set: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.
partial_ok : bool, default False: If True, missing keys in values will be ignored; if False (the default), a KeyError is raised for any missing booking class.

Returns:

None

Raises:

KeyError – If a booking class key is missing from values and partial_ok is False.
ValueError – If the target forecast is missing, vector lengths do not match, or vectors contain negative values.
TypeError – If values is not a mapping or the provided vectors are not array-like.

set_stdev_to_departure()¶

Set the standard deviation of demand from now to departure for each booking class.

Parameters:

values : dict[str, array-like]: Dictionary mapping booking class identifiers (or booking class names) to vectors (array-like) of standard deviation of demand from the current DCP to departure. Each vector must have the same length as the forecast’s stdev_to_departure vector and contain non-negative values (or NaN where appropriate).
which_forecast : {'t', 'p', 'q', 'y'} or None, optional: Which forecast to set: ‘t’ for total (default), ‘p’/’q’ for priceable (Q), ‘y’ for yieldable.
partial_ok : bool, default False: If True, missing keys in values will be ignored; if False (the default), a KeyError is raised for any missing booking class.

Returns:

None

Raises:

KeyError – If a booking class key is missing from values and partial_ok is False.
ValueError – If the target forecast is missing, vector lengths do not match, or vectors contain negative values.
TypeError – If values is not a mapping or the provided vectors are not array-like.

update_conditional_forecast()¶

update_q_forecast()¶