DecisionWindow¶

class passengersim.core.DecisionWindow¶

Bases: object

Decision Window Model configuration for customer time preferences.

Background and Motivation¶

Airline schedule planning models commonly represent passengers’ departure and arrival time preferences using discrete time-of-day indicators, defined at the hourly level or grouped into periods such as morning, afternoon, and evening. Continuous time-of-day formulations have also been used to capture smoother substitution across adjacent times [2] [3] [4]. These approaches allow demand to vary across specific departure and arrival times and align naturally with the discrete structure of airline schedules, often combined with elapsed time, defined as the total time from block-out of the first flight to block-in of the final flight in a directional itinerary.

An alternative framework for modeling time-of-day preferences is the decision window model, used historically in PODS-based studies. Instead of time-of-day indicators, passengers are assumed to have a preferred travel interval—referred to as a decision window—bounded by an earliest acceptable departure time and a latest acceptable arrival time. Itineraries within the window are acceptable and incur no disutility, while those partially or fully outside require replanning and incur a disutility. This approach parallels ground transportation scheduling models that represent preferences using departure or arrival time windows rather than point-in-time choices [5] [6].

Step 1A: Determine Decision Window Width¶

A decision window is defined as the minimum elapsed clock time in the market plus a schedule tolerance that captures passengers’ flexibility in scheduling their trips.

Elapsed clock time (also called Delta_T) represents the difference between local departure time at origin and local arrival time at destination, accounting for time zone changes but not actual time spent on the aircraft. For example, a flight departing Los Angeles at 8 AM and arriving New York at 4:30 PM has an elapsed clock time of 8.5 hours, even though passengers spend only 5.5 hours on the plane.

Schedule tolerance reflects how much earlier a passenger is willing to depart before their ideal time and how much later they are willing to arrive after their ideal time. The tolerance is passenger-type specific (e.g., business vs. leisure) and varies systematically with market distance.

Systematic Behaviors in Window Generation¶

When generating decision windows, several systematic behaviors are captured:

1. Window size differs by distance: Short-haul markets have narrower windows whereas long-haul markets have wider windows. This reflects that passengers planning short trips have tighter constraints (e.g., day trip with meeting), while those planning long trips have more flexibility in when they can depart and arrive. For very long distance trips (greater than 5000 miles), the window size is capped at 24 hours, reflecting that passengers generally have full-day flexibility for intercontinental travel. This is equivalent to no replanning disutility for such trips.

2. Window size differs by passenger type: Business travelers have narrower windows than leisure travelers on the same route. Business travelers face fixed meeting times and opportunity cost of time, while leisure travelers have discretionary time and stronger price sensitivity, making them more willing to accept inconvenient departure/arrival times for lower fares.

Recommended Schedule Tolerance Values: The following table shows recommended tolerance values (dwm_tolerance parameter, in hours) implemented in PassengerSim. Note these must be set in the customer_choice module as they are customer-type specific.

Distance Range	Business	Leisure
0-500 miles	1.2	2.0
501-1000 miles	3.3	4.6
1001-1500 miles	3.5	4.9
1501-2000 miles	3.8	5.2
2001-2500 miles	4.0	5.5
2501-3000 miles	4.2	5.8
3001-3500 miles	5.4	6.4
3501-4000 miles	10.5	12.7
4001-4500 miles	10.8	13.0
4501-5000 miles	11.0	13.3
5001-25000 miles	24.0	24.0

3. Window placement differs by time-of-day preferences: Once window size is determined, the actual placement within the day is stochastic, based on time-of-day probability distributions that vary as a function of elapsed clock time (Delta_T). Prior empirical studies [3] [4] found that time-of-day preferences varied with direction of travel and number of time zones crossed. For example, eastbound transcontinental flights (which “lose” hours crossing time zones) showed different placement patterns than westbound flights (which “gain” hours). Similarly, markets crossing multiple time zones exhibited different patterns than those within a single time zone, as passengers account for jet lag and body clock adjustments.

Step 1B: Placement of Window Using Time-of-Day Demand Distribution¶

The time-of-day distribution is defined as a function of elapsed clock time (Delta_T) rather than individual markets, allowing the model to generalize across markets with similar elapsed times regardless of distance, direction of travel, or time zones crossed. For example, markets with a 4-hour Delta_T—whether a 500-mile north-south route, a 1,500-mile eastbound transcontinental segment, or a 2,500-mile westbound transatlantic segment—share the same time-of-day distribution because passengers experience similar “clock time” travel durations and thus have similar departure time preferences.

The time-of-day distribution creates heterogeneity in window placement across passengers, capturing that different individuals have different preferred departure times (e.g., some prefer early morning, others late afternoon). These distributions vary systematically with Delta_T based on empirically observed patterns: short Delta_T markets typically show strong morning and evening peaks (for business travel before/after work), while longer Delta_T markets exhibit more uniform distributions reflecting greater scheduling flexibility.

Example: Decision Window Generation¶

PassengerSim implements a decision window model derived from the framework originally developed for PODS and documented in MIT lecture materials [1]. The following example illustrates how a decision window is generated for a specific passenger:

Scenario: Business traveler on a medium-haul market (e.g., Boston to Chicago)

• Market characteristics: * Distance: 850 nautical miles * Shortest elapsed clock time (Delta_T): 2.5 hours (accounting for time zones) * Applies distance range: 501-1000 miles

• Step 1 - Determine tolerance: * Mean tolerance for business traveler at this distance: 3.3 hours (from tolerance table) * Standard deviation: k_factor × 3.3 = 0.3 × 3.3 = 1.0 hour * Random draw from N(3.3, 1.0) → e.g., 3.7 hours (constrained to ≥ 0)

• Step 2 - Calculate window width: * window_width = shortest_elapsed_time + tolerance * window_width = 2.5 + 3.7 = 6.2 hours

• Step 3 - Determine window placement: * Time-of-day distribution (dwm_tod) for medium Delta_T: peaks at 7-9 AM and 5-7 PM * Random draw from distribution → e.g., selects 8:00 AM as window midpoint * Window spans: 8:00 AM ± (6.2 hours / 2) = 4:54 AM to 11:06 AM (local time)

• Result: This passenger will consider any itinerary departing between 4:54 AM and arriving by 11:06 AM (in local times) as acceptable with no schedule penalty. Itineraries outside this window incur disutilities based on how far they fall outside the window, as specified by the ChoiceModel parameters (replanning_alpha/beta or early_dep/late_arr S-curve functions).

Additional Notes¶

Representative Departure Day: PassengerSim uses a representative departure day approach. The time-of-day preference distributions represent an “average” day and do not vary across multiple days of the week (e.g., weekday vs. weekend patterns are not separately modeled). This simplification is consistent with most airline revenue management systems, which aggregate demand patterns across days of the week within a departure time period.

Customer Segments and Tolerance Table: The recommended tolerance table assumes two customer types labeled “business” and “leisure”. To use these defaults with more than two customer segments, either: (1) expand the tolerance table to include additional customer types with their own tolerance values, or (2) map your customer segments to the business/leisure categories to use this table. For example, a “premium business” segment might map to business tolerances, while “vacation” and “visiting friends/relatives” segments might both map to leisure tolerances.

Step 2: Itinerary Evaluation and Penalties¶

Once generated, each offered itinerary is evaluated against the passenger’s window:

• Fully Inside: Both departure and arrival within window → no penalty

• Early Departure: Departure before window start → early departure penalty

• Late Arrival: Arrival after window end → late arrival penalty

• Both Early and Late: Both conditions → both penalties apply

The penalty functional form (binary vs. S-curve) is specified in the ChoiceModel class via replanning_alpha/beta or early_dep/late_arr parameters, while DecisionWindow defines the window generation logic.

References

[1] Boeing Commercial Airplanes (1993). “The Boeing Passenger Origin-Destination Simulator: A Technical Design Overview.” Boeing Commercial Airplanes Marketing Research and Analysis Group. Available at: https://ocw.mit.edu/courses/16-75j-airline-management-spring-2006/f4cf28d87d1ac891f5fa4ebd5faa557d_lect6b.pdf Accessed January 1, 2026.

[2] Carrier, E. (2003). Modeling airline passenger choice: Passenger preference for schedule in the passenger origin-destination simulator (PODS). MS Thesis, Massachusetts Institute of Technology.

[3] Coldren, G. M., & Koppelman, F. S. (2005). Modeling the competition among air-travel itinerary shares: GEV model development. Transportation Research Part A: Policy and Practice, 39(4), 345-365.

[4] Lurkin, V., Garrow, L. A., Higgins, M. J., Newman, J. P., & Schyns, M. (2016). Accounting for price endogeneity in airline itinerary choice models: An application to Continental U.S. markets. Transportation Research Part A: Policy and Practice, 100, 228-246.

[5] Small, K. A. (1982). The scheduling of consumer activities: Work trips. The American Economic Review, 72(3), 467-479.

[6] Zeid, M. A., & Ben-Akiva, M. (2012). Modeling time-of-day choice in the context of tour-based models. Transportation Research Record, 2302(1), 64-72.

Methods

__init__(*args, **kwargs)
add_parm	Add a parameter value to the decision window model.
get_midpoint	Get decision window midpoint for a given random draw.
get_time_disutility	Get time disutility penalty for an offer.
get_window	Get decision window start and end times.
serialize	Get all parameter values from the decision window model.

Attributes

dwm_tod	Time of Day probability distribution (24 hourly values).
k_factor	Coefficient of variation for random draws in window placement.
name	Name identifier for this decision window model.
random_generator	Random number generator for stochastic window placement.

add_parm()¶

Add a parameter value to the decision window model.

Parameters:

name : str

Name of the parameter to add.

value : float

Primary parameter value.

value2 : float, optional

Secondary parameter value for parameters requiring two values. Default is 0.

Returns:

int – Returns 0 on success.

dwm_tod¶

Time of Day probability distribution (24 hourly values).

A list of 24 values representing the probability distribution for the center-point of the decision window. Must sum to 1.0 (probabilities) or 100.0 (percentages).

Returns:

list[float] – List of 24 probability values.

get_midpoint()¶

Get decision window midpoint for a given random draw.

Used for unit tests and debugging.

Parameters:

z_val : float

Random z-value for stochastic window placement.

snapshot_instruction : optional

Debugging/logging control parameter.

Returns:

float – Decision window midpoint in minutes from midnight.

get_time_disutility()¶

Get time disutility penalty for an offer.

Calculates penalties for short connections and/or long elapsed time. Used for unit tests and debugging.

Parameters:

dmd : Demand

Demand object representing the customer request.

offer : Offer

Offer to evaluate for time-based penalties.

debug : bool

Enable debug output if True.

Returns:

float – Time disutility penalty value.

get_window()¶

Get decision window start and end times.

Used for unit tests and debugging.

Parameters:

dmd : Demand

Demand object representing the customer request.

midpoint : int

Window midpoint in minutes from midnight.

distance : int

Market distance in nautical miles.

z_val : float

An explicit draw from an implied random standard normal distribution. Providing a draw is used for testing, in practice you should generally omit this to get a random draw automatically.

snapshot_instruction : optional

Debugging/logging control parameter.

Returns:

tuple[int, int] – Tuple of (start_time, end_time) in seconds from midnight.

k_factor¶

Coefficient of variation for random draws in window placement.

Returns:

float – The k-factor value.

name¶

Name identifier for this decision window model.

Returns:

str – The name of the decision window model.

random_generator¶

Random number generator for stochastic window placement.

Returns:

Generator – The random number generator object.

serialize()¶

Get all parameter values from the decision window model.

Returns:

None

Notes

This method is not yet fully implemented.