ConditionalPathForecast¶

class passengersim.rm.conditional_forecasting.ConditionalPathForecast(*, algorithm: 'additive_pickup' | 'exp_smoothing' | 'multiplicative_pickup' = 'additive_pickup', alpha: float = 0.15, carrier: str = '', minimum_sample: int = 10, cfg: Config | None = None, fare_adjustment: 'mr' | 'ki' | None = 'mr', fare_adjustment_scale: float = 0.25, regression_weight: 'sellup' | 'sellup^2' | 'fare' | 'none' | None = 'sellup', variance_rollup_algorithm: 'tf' | 'dep' = 'tf', variance_is_ratio_of_mean: float = 0.0, max_cap: float = 0.0, q_allocation_algorithm: 'tf' | 'dep' = 'tf')[source]¶

Bases: RmAction

Conditional path-level demand forecasting tool.

Methods

`__init__`(*[, algorithm, alpha, carrier, ...])
`apply_snapshot_filters`(sim, days_prior, ...)	Apply this action's snapshot filters, if any, and return the resulting instruction.
`configure`([fixed])	Create an RmActionFactory for this action with the given configuration.
`get_dcp_index`(days_prior[, allow_between])
`init`(sim)	Initialize the action for the given simulation.
`run`(sim, days_prior)	Execute the action for the given simulation.
`should_run`(sim, days_prior)	Determine if the action should run on the given days_prior.

Attributes

`frequency`	The frequency with which to run this action.
`produces`
`requires`
`snapshot_filter_type`
`algorithm`	Forecasting algorithm.
`alpha`	Exponential smoothing factor.
`fare_adjustment`	Fare adjustment algorithm to use with hybrid or conditional forecasting.
`fare_adjustment_scale`	Fare adjustment scale factor to use with hybrid forecasting.
`weighted_by_ratio`	Weight fare adjustment by the ratio of priceable and yieldable demand.
`q_allocation_algorithm`	How to allocate variance from aggregate Q forecasts to class-level forecasts.
`variance_rollup_algorithm`	How to roll up variance when combining priceable and yieldable forecasts.
`variance_is_ratio_of_mean`	For conditional forecasting, assume that the variance is this ratio of the mean.
`max_cap`	Maximum sellup weighting factor for the conditional forecast.
`dcps`	Set of days prior to departure on which to run this action.
`carrier`	The carrier upon which to apply this action.
`minimum_sample`	The minimum sample number before this action will run.

requires : set[str] = {'path_demand'}¶

produces : set[str] = {'path_forecast'}¶

frequency : Literal['dcp', 'daily', 'daily_pre_dep', 'non_dcp', 'begin_sample', 'end_sample', 'weekly'] = 'dcp'¶

The frequency with which to run this action.

This can be one of the following values: - “dcp”: run only on the specified DCPs. - “daily”: run every day. - “daily_pre_dep”: run every day prior to departure (i.e., days_prior > 0).” - “non_dcp”: run on days that are not in the specified DCPs. - “begin_sample”: run only on the first DCP (i.e., the maximum days_prior). - “end_sample”: run only on the day of departure (i.e., days_prior == 0). - “weekly”: run every 7 days (i.e. when days_prior is a multiple of 7).

The run method of RM actions is actually called every day (as it is implemented as a daily callback), but the first thing the run method should do is check whether it should actually execute on that day, using the should_run method, which uses this frequency setting to determine whether to proceed.

algorithm¶

Forecasting algorithm.

There are several available forecasting algorithms:

additive_pickup: is an additive pickup model, which generates a forecast by considering the “pickup”, or the number of new sales in a booking class, in each time period (DCP). This model is additive in that the forecast of demand yet to come at given time is computed as the sum of forecast pickups in all future time periods. This forecasting model does not consider the level of demand already accumulated, only the demand expected in the future. The forecast is made considering the results from the prior 26 sample days. The additive pickup model ignores the value of the alpha parameter, and it can safely be omitted when using this algorithm.
exp_smoothing: is an exponential smoothing model. This model uses the alpha parameter to control the amount of smoothing applied. It does not (currently) incorporate trend effects or seasonality.
multiplicative_pickup: is a multiplicative pickup model. This model is in development.

alpha¶

Exponential smoothing factor.

This setting is ignored if the forecast algorithm is not “exp_smoothing”.

fare_adjustment : Literal['mr', 'ki', None]¶

Fare adjustment algorithm to use with hybrid or conditional forecasting.

This setting is ignored for other forecast types.

fare_adjustment_scale¶

Fare adjustment scale factor to use with hybrid forecasting.

This setting is ignored for forecast types other than hybrid, or if the fare_adjustment setting is None.

weighted_by_ratio : bool¶

Weight fare adjustment by the ratio of priceable and yieldable demand.

When set to True, the fare adjustment is weighted by the ratio of priceable and yieldable forecasted demand, so that the fare adjustment is applied more heavily when more of the combined demand is priceable. When set to False, the fare adjustment is applied uniformly and in full without regard to the ratio of priceable and yieldable demand.

q_allocation_algorithm : Literal['tf', 'dep']¶: How to allocate variance from aggregate Q forecasts to class-level forecasts.

variance_rollup_algorithm¶: How to roll up variance when combining priceable and yieldable forecasts.

apply_snapshot_filters(sim: Simulation, days_prior: int, *args, **kwargs) → SnapshotInstruction | None¶

Apply this action’s snapshot filters, if any, and return the resulting instruction.

If there are no snapshot filters, or if none of the filters trigger, then this returns None.

classmethod configure(fixed: dict[str, Any] | None = None, **kwargs) → RmActionFactory¶

Create an RmActionFactory for this action with the given configuration.

Each keyword argument name should correspond to a parameter in the RmAction subclass’s __init__ method. The value of each keyword argument will be the keyword argument used in the RmSys that uses this factory.

Fixed values can be provided via the fixed parameter, which is a dictionary of parameter names to fixed values. These values will always be passed to the RmAction constructor, and cannot be overridden via the RmSys.

get_dcp_index(days_prior: int, allow_between: bool = False) → int¶

init(sim: Simulation)¶

Initialize the action for the given simulation.

This is a hook called once at the beginning of the simulation, after the entire network and all core data structures have been set up but before any simulation samples have been run. It can be used to perform any necessary setup before the first call to run. By default, this does nothing, but subclasses can override it if needed.

should_run(sim: Simulation, days_prior: int) → bool¶: Determine if the action should run on the given days_prior.

snapshot_filter_type : type[GenericSnapshotFilter] = None¶

variance_is_ratio_of_mean : float¶

For conditional forecasting, assume that the variance is this ratio of the mean.

When this is set to a value greater than zero, the variance of the forecast is set to this fixed ratio of the mean. Note that many algorithms for optimization use the forecast standard deviation, which is the square root of the variance, but it is the variance that is set to this ratio times the mean.

When set to zero (the default), the variance is computed from mean squared error of the linear regression model used to compute the mean.

This setting is used only for conditional forecasting.

dcps : set[int]¶: Set of days prior to departure on which to run this action.

carrier¶: The carrier upon which to apply this action.

minimum_sample¶: The minimum sample number before this action will run.

max_cap : float¶

Maximum sellup weighting factor for the conditional forecast.

If set to a value greater than zero, the weighting factor used in the regression model for conditional forecasting is capped at this value. If set to zero (the default), there is no cap applied.

run(sim: Simulation, days_prior: int)[source]¶

Execute the action for the given simulation.

Subclasses must implement this method.