Non-Mandatory Destination Choice#

The non-mandatory tour destination choice model chooses a destination zone for non-mandatory tours. The three step (sample, logsums, final choice) process also used for mandatory tour destination choice is used for non-mandatory tour destination choice.

Non-mandatory tour location choice for multiple_zone_systems models uses presampling by default.

The main interface to the non-mandatory tour destination choice model is the non_mandatory_tour_destination function. This function is registered as an Inject step in the example Pipeline. See :ref:writing_logsums for how to write logsums for estimation.

Structure#

  • Configuration File: non_mandatory_tour_destination.yaml

  • Core Table: tours

  • Result Field: destination

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

Configuration#

settings activitysim.abm.models.non_mandatory_destination.TourLocationComponentSettings#

Bases: LocationComponentSettings

Fields:

  • ALT_DEST_COL_NAME (str)

  • CHOOSER_FILTER_COLUMN_NAME (str | None)

  • CHOOSER_ID_COLUMN (str)

  • CHOOSER_ORIG_COL_NAME (str)

  • CHOOSER_SEGMENT_COLUMN_NAME (str | None)

  • CHOOSER_TABLE_NAME (str | None)

  • COEFFICIENTS (pathlib.Path | None)

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

  • DEST_CHOICE_COLUMN_NAME (str | None)

  • DEST_CHOICE_LOGSUM_COLUMN_NAME (str | None)

  • DEST_CHOICE_SAMPLE_TABLE_NAME (str | None)

  • IN_PERIOD (int | dict[str, int] | None)

  • LOGSUM_PREPROCESSOR (str)

  • LOGSUM_SETTINGS (pathlib.Path)

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

  • MODELED_SIZE_TABLE (str | None)

  • MODEL_SELECTOR (Literal['workplace', 'school', None])

  • ORIG_ZONE_ID (str | None)

  • OUT_PERIOD (int | dict[str, int] | None)

  • SAMPLE_SIZE (int)

  • SAMPLE_SPEC (pathlib.Path)

  • SAVED_SHADOW_PRICE_TABLE_NAME (str | None)

  • SEGMENTS (list[str] | None)

  • SEGMENT_IDS (dict[str, int] | None)

  • SHADOW_PRICE_TABLE (str | None)

  • SIMULATE_CHOOSER_COLUMNS (list[str] | None)

  • SIZE_TERM_SELECTOR (str | None)

  • SPEC (pathlib.Path)

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

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

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

  • sharrow_skip (bool)

  • source_file_paths (list[pathlib.Path])

field ALT_DEST_COL_NAME: str [Required]#
field CHOOSER_FILTER_COLUMN_NAME: str | None = None#
field CHOOSER_ID_COLUMN: str = 'person_id'#
field CHOOSER_ORIG_COL_NAME: str [Required]#
field CHOOSER_SEGMENT_COLUMN_NAME: str | None = None#
field CHOOSER_TABLE_NAME: str | None = None#
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 DEST_CHOICE_COLUMN_NAME: str | None = None#
field DEST_CHOICE_LOGSUM_COLUMN_NAME: str | None = None#
field DEST_CHOICE_SAMPLE_TABLE_NAME: str | None = None#
field IN_PERIOD: int | dict[str, int] | None = None#
field LOGSUM_PREPROCESSOR: str = 'preprocessor'#
field LOGSUM_SETTINGS: Path [Required]#

Settings for the logsum computation.

field LOGSUM_TOUR_PURPOSE: str | dict[str, str] | None = None#
field MODELED_SIZE_TABLE: str | None = None#
field MODEL_SELECTOR: Literal['workplace', 'school', None] = None#
field ORIG_ZONE_ID: str | None = None#

This setting appears to do nothing…

field OUT_PERIOD: int | dict[str, int] | None = None#
field SAMPLE_SIZE: int [Required]#

This many candidate alternatives will be sampled for each choice.

field SAMPLE_SPEC: Path [Required]#

The utility spec giving expressions to use in alternative sampling.

field SAVED_SHADOW_PRICE_TABLE_NAME: str | None = None#
field SEGMENTS: list[str] | None = None#
field SEGMENT_IDS: dict[str, int] | None = None#
field SHADOW_PRICE_TABLE: str | None = None#
field SIMULATE_CHOOSER_COLUMNS: list[str] | None = None#
field SIZE_TERM_SELECTOR: str | None = None#
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_households: PreprocessorSettings | None = None#
field annotate_persons: PreprocessorSettings | None = None#
field annotate_tours: 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.

Examples#

Implementation#

activitysim.abm.models.non_mandatory_destination.non_mandatory_tour_destination(state: State, tours: DataFrame, persons_merged: DataFrame, network_los: Network_LOS, model_settings: Optional[TourLocationComponentSettings] = None, model_settings_file_name: str = 'non_mandatory_tour_destination.yaml', trace_label: str = 'non_mandatory_tour_destination') → None#

Given the tour generation from the above, each tour needs to have a destination, so in this case tours are the choosers (with the associated person that’s making the tour)