Trip Mode Choice#

The trip mode choice model assigns a travel mode for each trip on a given tour. It operates similarly to the tour mode choice model, but only certain trip modes are available for each tour mode. The correspondence rules are defined according to the following principles:

  • Pay trip modes are only available for pay tour modes (for example, drive-alone pay is only available at the trip mode level if drive-alone pay is selected as a tour mode).

  • The auto occupancy of the tour mode is determined by the maximum occupancy across all auto trips that make up the tour. Therefore, the auto occupancy for the tour mode is the maximum auto occupancy for any trip on the tour.

  • Transit tours can include auto shared-ride trips for particular legs. Therefore, ‘casual carpool’, wherein travelers share a ride to work and take transit back to the tour origin, is explicitly allowed in the tour/trip mode choice model structure.

  • The walk mode is allowed for any trip.

  • The availability of transit line-haul submodes on transit tours depends on the skimming and tour mode choice hierarchy. Free shared-ride modes are also available in walk-transit tours, albeit with a low probability. Paid shared-ride modes are not allowed on transit tours because no stated preference data is available on the sensitivity of transit riders to automobile value tolls, and no observed data is available to verify the number of people shifting into paid shared-ride trips on transit tours.

The trip mode choice models explanatory variables include household and person variables, level-of-service between the trip origin and destination according to the time period for the tour leg, urban form variables, and alternative-specific constants segmented by tour mode.

The main interface to the trip mode choice model is the trip_mode_choice function. This function is registered as an Inject step in the example Pipeline.

Structure#

  • Configuration File: trip_mode_choice.yaml

  • Result Field: trip_mode

  • Skim Keys: origin, destination, trip_period

Configuration#

settings activitysim.abm.models.trip_mode_choice.TripModeChoiceSettings#

Bases: TemplatedLogitComponentSettings

Settings for the trip_mode_choice component.

Config:

  • extra: str = forbid

Fields:
Validators:

  • update_sharrow_skip » all fields

field CHOOSER_COLS_TO_KEEP: list[str] = []#
Validated by:

  • update_sharrow_skip

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 COEFFICIENT_TEMPLATE: str | None = None#

Coefficients template filename.

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

Validated by:

  • update_sharrow_skip

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

Named constants usable in the utility expressions.

Validated by:

  • update_sharrow_skip

field FORCE_ESCORTEE_CHAUFFEUR_MODE_MATCH: bool = True#
Validated by:

  • update_sharrow_skip

field LEGACY_COEFFICIENTS: str | None = None#
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 MODE_CHOICE_LOGSUM_COLUMN_NAME: str = 'mode_choice_logsum'#

Column name of the mode choice logsum

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 REDUNDANT_TOURS_MERGED_CHOOSER_COLUMNS: list[str] | None = None#
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 TOURS_MERGED_CHOOSER_COLUMNS: list[str] | None = None#

List of columns to be filtered from the dataframe to reduce memory needs filter chooser table to these fields

Validated by:

  • update_sharrow_skip

field TVPB_recipe: str = 'tour_mode_choice'#
Validated by:

  • update_sharrow_skip

field annotate_trips: PreprocessorSettings | None = None#
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=[])#

Sharrow settings for this component.

Validated by:

  • update_sharrow_skip

field preprocessor: PreprocessorSettings | None = None#

Setting for the preprocessor.

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

field tvpb_mode_path_types: dict[str, Any] = {}#
Validated by:

  • update_sharrow_skip

field use_TVPB_constants: bool = True#
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_mode_choice.trip_mode_choice(state: State, trips: DataFrame, network_los: Network_LOS, model_settings: TripModeChoiceSettings | None = None, model_settings_file_name: str = 'trip_mode_choice.yaml', trace_label: str = 'trip_mode_choice') → None#

Trip mode choice - compute trip_mode (same values as for tour_mode) for each trip.

Modes for each primary tour putpose are calculated separately because they have different coefficient values (stored in trip_mode_choice_coefficients.csv coefficient file.)

Adds trip_mode column to trip table

On this page
Show Source