Trip Scheduling Choice#

This model uses a logit-based formulation to determine potential trip windows for the three main components of a tour.

  • Outbound Leg: The time from leaving the origin location to the time second to last outbound stop.

  • Main Leg: The time window from the last outbound stop through the main tour destination to the first inbound stop.

  • Inbound Leg: The time window from the first inbound stop to the tour origin location.

Structure#

  • Configuration File: trip_scheduling_choice.yaml

  • Core Table: tours

  • Result Field: outbound_duration, main_leg_duration, inbound_duration

Configuration#

settings activitysim.abm.models.trip_scheduling_choice.TripSchedulingChoiceSettings#

Bases: LogitComponentSettings

Settings for the trip_scheduling_choice component.

Config:

  • extra: str = forbid

Fields:
Validators:

  • update_sharrow_skip » all fields

field COEFFICIENTS: Path | None = None#

Coefficients filename.

This is a CSV file giving named parameters for use in the utility expression. If it is not provided, then it is assumed that all model coefficients are given explicitly in the SPEC as numerical values instead of named parameters. This is perfectly acceptable for use with ActivitySim for typical simulation applications, but may be problematic if used with “estimation mode”.

Validated by:

  • update_sharrow_skip

field CONSTANTS: dict[str, Any] = {}#

Named constants usable in the utility expressions.

Validated by:

  • update_sharrow_skip

field LOGIT_TYPE: Literal['MNL', 'NL'] = 'MNL'#

Logit model mathematical form.

  • “MNL”

    Multinomial logit model.

  • “NL”

    Nested multinomial logit model.

Validated by:

  • update_sharrow_skip

field NESTS: LogitNestSpec | None = None#

Nesting structure for a nested logit model.

The nesting structure is specified heirarchically from the top, so the value of this field should be the “root” level nest of the nested logit tree, which should contain references to lower level nests and/or the actual alternatives.

For example, this YAML defines a simple nesting structure for four alternatives (DRIVE, WALK, WALK_TO_TRANSIT, DRIVE_TO_TRANSIT) with the two transit alternatives grouped together in a nest:

NESTS:
  name: root
  coefficient: coef_nest_root
  alternatives:
    - DRIVE
    - WALK
    - name: TRANSIT
      coefficient: coef_nest_transit
      alternatives:
      - WALK_TO_TRANSIT
      - DRIVE_TO_TRANSIT
Validated by:

  • update_sharrow_skip

field SPEC: Path [Required]#

Utility specification filename.

This is sometimes alternatively called the utility expressions calculator (UEC). It is a CSV file giving all the functions for the terms of a linear-in-parameters utility expression.

Validated by:

  • update_sharrow_skip

field annotate_households: PreprocessorSettings | None = None#

Annotate households output tables with additional columns.

These settings are used to add additional columns to the output tables after the logit model is run. They are typically used to add additional attributes that are derived from the model results.

Validated by:

  • update_sharrow_skip

field annotate_persons: PreprocessorSettings | None = None#

Annotate persons output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_tours: PreprocessorSettings | None = None#

Annotate tours output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_trips: PreprocessorSettings | None = None#

Annotate trips output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_vehicles: PreprocessorSettings | None = None#

Annotate vehicles output tables with additional columns.

Validated by:

  • update_sharrow_skip

field compute_settings: ComputeSettings = ComputeSettings(sharrow_skip=False, fastmath=True, use_bottleneck=None, use_numexpr=None, use_numba=None, drop_unused_columns=True, protect_columns=[], performance_log=None)#

Sharrow settings for this component.

Validated by:

  • update_sharrow_skip

field preprocessor: PreprocessorSettings | list[PreprocessorSettings] | None = None#

Chooser preprocessor settings.

This is a set of expressions to be evaluated on the choosers before the logit model is run. It is used to prepare the choosers for the logit model by adding columns that are used in the utility expressions.

Validated by:

  • update_sharrow_skip

field source_file_paths: list[Path] = None#

A list of source files from which these settings were loaded.

This value should not be set by the user within the YAML settings files, instead it is populated as those files are loaded. It is primarily provided for debugging purposes, and does not actually affect the operation of any model.

Validated by:

  • update_sharrow_skip

classmethod nests_are_for_nl(nests, values)#

Checks that nests are provided if (and only if) LOGIT_TYPE is NL.

validator update_sharrow_skip  »  all fields#

Examples#

Implementation#

activitysim.abm.models.trip_scheduling_choice.trip_scheduling_choice(state: State, trips: DataFrame, tours: DataFrame, skim_dict: SkimDict | SkimDataset, model_settings: TripSchedulingChoiceSettings | None = None, model_settings_file_name: str = 'trip_scheduling_choice.yaml', trace_label: str = 'trip_scheduling_choice') → None#
activitysim.abm.models.trip_scheduling_choice.generate_schedule_alternatives(tours)#

For a set of tours, build out the potential schedule alternatives for the main leg, outbound leg, and inbound leg. This process handles the change in three steps.

Definitions:
  • Main Leg: The time from last outbound stop to the first inbound stop.

    If the tour does not include any intermediate stops this will represent the full tour duration.

  • Outbound Leg: The time from the tour origin to the last outbound stop

  • Inbound Leg: The time from the first inbound stop to the tour origin

  1. For tours with no intermediate stops, it simple asserts a main leg duration equal to the tour duration.

  2. For tours with an intermediate stop on one of the legs, calculate all possible time combinations that are allowed in the duration

  3. For tours with an intermediate stop on both legs, calculate all possible time combinations that are allowed in the tour duration

Parameters:

tours – pd.Dataframe: Must include a field for tour duration and boolean fields indicating intermediate inbound or outbound stops.

Returns:

pd.Dataframe: Potential time duration windows.

activitysim.abm.models.trip_scheduling_choice.no_stops_patterns(tours)#

Asserts the tours with no intermediate stops have a main leg duration equal to the tour duration and set inbound and outbound windows equal to zero. :param tours: pd.Dataframe: Tours with no intermediate stops. :return: pd.Dataframe: Main leg duration, outbound leg duration, and inbound leg duration

activitysim.abm.models.trip_scheduling_choice.stop_one_way_only_patterns(tours, travel_duration_col='duration')#

Calculates potential time windows for tours with a single leg with intermediate stops. It calculates all possibilities for the main leg and one tour leg to sum to the tour duration. The other leg is asserted with a duration of zero. :param tours: pd.Dataframe: Tours with no intermediate stops. :return: pd.Dataframe: Main leg duration, outbound leg duration, and inbound leg duration

The return dataframe is indexed to the tour input index

activitysim.abm.models.trip_scheduling_choice.stop_two_way_only_patterns(tours, travel_duration_col='duration')#

Calculates potential time windows for tours with intermediate stops on both legs. It calculates all possibilities for the main leg and both tour legs to sum to the tour duration. :param tours: pd.Dataframe: Tours with no intermediate stops. :return: pd.Dataframe: Main leg duration, outbound leg duration, and inbound leg duration

The return dataframe is indexed to the tour input index

activitysim.abm.models.trip_scheduling_choice.get_pattern_index_and_arrays(tour_indexes, durations, one_way=True)#

A helper method to quickly calculate all of the potential time windows for a given set of tour indexes and durations. :param tour_indexes: List of tour indexes :param durations: List of tour durations :param one_way: If True, calculate windows for only one tour leg. If False,

calculate tour windows for both legs

Returns:

np.array: Tour indexes repeated for valid pattern np.array: array with a column for main tour leg, outbound leg, and inbound leg np.array: array with the number of patterns for each tour

activitysim.abm.models.trip_scheduling_choice.get_spec_for_segment(state: State, model_settings: TripSchedulingChoiceSettings, segment: str)#

Read in the model spec :param model_settings: model settings file :param segment: which segment of the spec file do you want to read :return: array of utility equations