Tour Mode Choice

The mandatory, non-mandatory, and joint tour mode choice model assigns to each tour the “primary” mode that is used to get from the origin to the primary destination. The tour-based modeling approach requires a reconsideration of the conventional mode choice structure. Instead of a single mode choice model used in a four-step structure, there are two different levels where the mode choice decision is modeled: (a) the tour mode level (upper-level choice); and, (b) the trip mode level (lower-level choice conditional upon the upper-level choice).

The mandatory, non-mandatory, and joint tour mode level represents the decisions that apply to the entire tour, and that will affect the alternatives available for each individual trip or joint trip. These decisions include the choice to use a private car versus using public transit, walking, or biking; whether carpooling will be considered; and whether transit will be accessed by car or by foot. Trip-level decisions correspond to details of the exact mode used for each trip, which may or may not change over the trips in the tour.

The mandatory, non-mandatory, and joint tour mode choice structure is a nested logit model which separates similar modes into different nests to more accurately model the cross-elasticities between the alternatives. The eighteen modes are incorporated into the nesting structure specified in the model settings file. The first level of nesting represents the use a private car, non-motorized means, or transit. In the second level of nesting, the auto nest is divided into vehicle occupancy categories, and transit is divided into walk access and drive access nests. The final level splits the auto nests into free or pay alternatives and the transit nests into the specific line-haul modes.

The primary variables are in-vehicle time, other travel times, cost (the influence of which is derived from the automobile in-vehicle time coefficient and the persons’ modeled value of time), characteristics of the destination zone, demographics, and the household’s level of auto ownership.

The main interface to the mandatory, non-mandatory, and joint tour mode model is the tour_mode_choice_simulate function. This function is called in the Inject step tour_mode_choice_simulate and is registered as an Inject step in the example Pipeline. See writing_logsums for how to write logsums for estimation.

Structure

• Configuration File: tour_mode_choice.yaml

• Core Table: tours

• Result Field: mode

• Skims Keys: TAZ, destination, start, end

Configuration

settings activitysim.abm.models.tour_mode_choice.TourModeComponentSettings

Bases: TemplatedLogitComponentSettings

Fields:

• COEFFICIENTS (pathlib.Path | None)

• COEFFICIENT_TEMPLATE (str | None)

• COMPUTE_TRIP_MODE_CHOICE_LOGSUMS (bool)

• CONSTANTS (dict[str, typing.Any])

• FORCE_ESCORTEE_CHAUFFEUR_MODE_MATCH (bool)

• LOGIT_TYPE (Literal['MNL', 'NL'])

• LOGSUM_CHOOSER_COLUMNS (list[str])

• MODE_CHOICE_LOGSUM_COLUMN_NAME (str | None)

• NESTS (activitysim.core.configuration.logit.LogitNestSpec | None)

• SPEC (pathlib.Path)

• annotate_tours (activitysim.core.configuration.base.PreprocessorSettings | None)

• nontour_preprocessor (activitysim.core.configuration.base.PreprocessorSettings | list[activitysim.core.configuration.base.PreprocessorSettings] | None)

• preprocessor (activitysim.core.configuration.base.PreprocessorSettings | list[activitysim.core.configuration.base.PreprocessorSettings] | None)

• sharrow_skip (bool)

• source_file_paths (list[pathlib.Path])

• tvpb_mode_path_types (dict[str, typing.Any] | None)

• use_TVPB_constants (bool)

Validators:

• nests_are_for_nl » NESTS

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”.

field COEFFICIENT_TEMPLATE: str | None = None

Coefficients template filename.

For a segmented model component, this maps the named parameters to segment-specific names.

field COMPUTE_TRIP_MODE_CHOICE_LOGSUMS: bool = False

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

Named constants usable in the utility expressions.

field FORCE_ESCORTEE_CHAUFFEUR_MODE_MATCH: bool = True

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

Logit model mathematical form.

• “MNL”

  Multinomial logit model.

• “NL”

  Nested multinomial logit model.

field LOGSUM_CHOOSER_COLUMNS: list[str] = []

field MODE_CHOICE_LOGSUM_COLUMN_NAME: str | None = None

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:

• nests_are_for_nl

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.

field annotate_tours: PreprocessorSettings | None = None

field nontour_preprocessor: PreprocessorSettings | list[PreprocessorSettings] | None = None

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

field sharrow_skip: bool = False

Skip sharrow when evaluating this component.

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.

field tvpb_mode_path_types: dict[str, Any] | None = None

field use_TVPB_constants: bool = True

validator nests_are_for_nl  »  NESTS

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

Examples

• Prototype MTC

• Prototype ARC

Implementation

activitysim.abm.models.tour_mode_choice.tour_mode_choice_simulate(state: State, tours: DataFrame, persons_merged: DataFrame, network_los: Network_LOS, model_settings: Optional[TourModeComponentSettings] = None, model_settings_file_name: str = 'tour_mode_choice.yaml', trace_label: str = 'tour_mode_choice') → None

Tour mode choice simulate

activitysim.abm.models.tour_mode_choice.create_logsum_trips(state: State, tours: DataFrame, segment_column_name: str, model_settings: TourModeComponentSettings, trace_label: str)

Construct table of trips from half-tours (1 inbound, 1 outbound) for each tour-mode.

Parameters:

tourspandas.DataFrame

segment_column_namestr

column in tours table used for segmenting model spec

model_settingsTourModeComponentSettings

trace_labelstr

Returns:

pandas.DataFrame

Table of trips: 2 per tour, with O/D and purpose inherited from tour

activitysim.abm.models.tour_mode_choice.append_tour_leg_trip_mode_choice_logsums(state: State, tours)

Creates trip mode choice logsum column in tours table for each tour mode and leg

Parameters:

tourspd.DataFrame

Returns:

tourspd.DataFrame

Adds two * n_modes logsum columns to each tour row, e.g. “logsum_DRIVE_outbound”

activitysim.abm.models.tour_mode_choice.get_trip_mc_logsums_for_all_modes(state: State, tours: DataFrame, segment_column_name: str, model_settings: TourModeComponentSettings, trace_label: str)

Creates pseudo-trips from tours and runs trip mode choice to get logsums

Parameters:

tourspandas.DataFrame

segment_column_namestr

column in tours table used for segmenting model spec

model_settingsTourModeComponentSettings

trace_labelstr

Returns:

tourspd.DataFrame

Adds two * n_modes logsum columns to each tour row, e.g. “logsum_DRIVE_outbound”

activitysim.abm.models.tour_mode_choice.get_trip_mc_logsums_for_all_modes(state: State, tours: DataFrame, segment_column_name: str, model_settings: TourModeComponentSettings, trace_label: str)

Creates pseudo-trips from tours and runs trip mode choice to get logsums

Parameters:

tourspandas.DataFrame

segment_column_namestr

column in tours table used for segmenting model spec

model_settingsTourModeComponentSettings

trace_labelstr

Returns:

tourspd.DataFrame

Adds two * n_modes logsum columns to each tour row, e.g. “logsum_DRIVE_outbound”