Joint Tour Scheduling

The joint tour scheduling model selects a tour departure and duration period (and therefore a start and end period as well) for each joint tour. This model uses person time_windows. The primary drivers in the models are accessibility-based parameters such as the auto travel time for the departure/arrival hour combination, demographics, and time pattern characteristics such as the time windows available from previously scheduled tours. The joint tour scheduling model does not use mode choice logsums.

The main interface to the joint tour purpose scheduling model is the joint_tour_scheduling function. This function is registered as an Inject step in the example Pipeline.

Structure

• Configuration File: joint_tour_scheduling.yaml

• Core Table: tours

• Result Field: start, end, duration

• Skims Keys: TAZ, destination, MD time period, MD time period

Configuration

settings activitysim.abm.models.joint_tour_scheduling.TourSchedulingSettings

Bases: LogitComponentSettings

Fields:

• ALTS_PREPROCESSOR (PreprocessorSettings | dict[str, PreprocessorSettings])

• COEFFICIENTS (Path | None)

• CONSTANTS (dict[str, Any])

• DESTINATION_FOR_TOUR_PURPOSE (str | dict[str, str] | None)

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

• LOGSUM_PREPROCESSOR (str)

• LOGSUM_SETTINGS (Path | None)

• NESTS (LogitNestSpec | None)

• SIMULATE_CHOOSER_COLUMNS (list[str] | None)

• SPEC (Path | None)

• SPEC_SEGMENTS (dict[str, LogitComponentSettings])

• TOUR_SPEC_SEGMENTS (dict[str, str])

• preprocessor (PreprocessorSettings | None)

• sharrow_skip (bool)

• source_file_paths (list[Path])

Validators:

• nests_are_for_nl » NESTS

field ALTS_PREPROCESSOR: PreprocessorSettings | dict[str, PreprocessorSettings] = {}

If the alternatives preprocessor is a single PreprocessorSettings object, it is assumed to be an unsegmented preprocessor. Otherwise, the dict keys give the segements.

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 CONSTANTS: dict[str, Any] = {}

Named constants usable in the utility expressions.

field DESTINATION_FOR_TOUR_PURPOSE: str | dict[str, str] | None = None

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

Logit model mathematical form.

• “MNL”

  Multinomial logit model.

• “NL”

  Nested multinomial logit model.

field LOGSUM_PREPROCESSOR: str = 'preprocessor'

field LOGSUM_SETTINGS: Path | 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 SIMULATE_CHOOSER_COLUMNS: list[str] | None = None

field SPEC: Path | None = None

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. If SPEC_SEGMENTS is given, then this unsegmented SPEC should be omitted.

field SPEC_SEGMENTS: dict[str, LogitComponentSettings] = {}

field TOUR_SPEC_SEGMENTS: dict[str, str] = {}

field preprocessor: PreprocessorSettings | None = None

Setting for the preprocessor.

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.

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.joint_tour_scheduling.joint_tour_scheduling(state: State, tours: DataFrame, persons_merged: DataFrame, tdd_alts: DataFrame, model_settings: Optional[TourSchedulingSettings] = None, model_settings_file_name: str = 'joint_tour_scheduling.yaml', trace_label: str = 'joint_tour_scheduling') → None

This model predicts the departure time and duration of each joint tour