At-work Subtour Scheduling#

The at-work subtours scheduling model selects a tour departure and duration period (and therefore a start and end period as well) for each at-work subtour. This model uses person time_windows.

This model is the same as the mandatory tour scheduling model except it operates on the at-work tours and constrains the alternative set to available person time_windows. The at-work subtour scheduling model does not use mode choice logsums. The at-work subtour frequency model can choose multiple tours so this model must process all first tours and then second tours since isFirstAtWorkTour is an explanatory variable.

Choosers: at-work tours Alternatives: alternative departure time and arrival back at origin time pairs WITHIN the work tour departure time and arrival time back at origin AND the person time window. If no time window is available for the tour, make the first and last time periods within the work tour available, make the choice, and log the number of times this occurs. Dependent tables: skims, person, land use, work tour Outputs: at-work tour departure time and arrival back at origin time, updated person time windows

The main interface to the at-work subtours scheduling model is the atwork_subtour_scheduling function. This function is registered as an Inject step in the example Pipeline.

Structure#

  • Configuration File: tour_scheduling_atwork.yaml

  • Core Table: tours

  • Result Field: start, end, duration

  • Skims keys: workplace_taz, alt_dest, MD time period, MD time period

Configuration#

settings activitysim.abm.models.atwork_subtour_scheduling.TourSchedulingSettings#

Bases: LogitComponentSettings

Config:

  • extra: str = forbid

Fields:

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

  • COEFFICIENTS ()

  • CONSTANTS ()

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

  • LOGIT_TYPE ()

  • LOGSUM_PREPROCESSOR (str)

  • LOGSUM_SETTINGS (Path | None)

  • NESTS ()

  • SIMULATE_CHOOSER_COLUMNS (list[str] | None)

  • SPEC (Path | None)

  • SPEC_SEGMENTS (dict[str, LogitComponentSettings])

  • TOUR_SPEC_SEGMENTS (dict[str, str])

  • compute_settings ()

  • explicit_chunk (float)

  • preprocessor (PreprocessorSettings | None)

  • source_file_paths ()

Validators:

  • update_sharrow_skip » all fields

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.

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

Named constants usable in the utility expressions.

Validated by:

  • update_sharrow_skip

field DESTINATION_FOR_TOUR_PURPOSE: str | dict[str, 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 LOGSUM_PREPROCESSOR: str = 'preprocessor'#
Validated by:

  • update_sharrow_skip

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

  • update_sharrow_skip

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.

Validated by:

  • update_sharrow_skip

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

  • update_sharrow_skip

field TOUR_SPEC_SEGMENTS: dict[str, str] = {}#
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 explicit_chunk: float = 0#

If > 0, use this chunk size instead of adaptive chunking. If less than 1, use this fraction of the total number of rows.

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

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.atwork_subtour_scheduling.atwork_subtour_scheduling(state: State, tours: DataFrame, persons_merged: DataFrame, tdd_alts: DataFrame, skim_dict: SkimDict | SkimDataset, model_settings: TourSchedulingSettings | None = None, model_settings_file_name: str = 'tour_scheduling_atwork.yaml', trace_label: str = 'atwork_subtour_scheduling') → None#

This model predicts the departure time and duration of each activity for at work subtours tours

On this page
Show Source