Joint Tour Destination#
The joint tour destination choice model operate similarly to the usual work and school location choice model, selecting the primary destination for travel tours. The only procedural difference between the models is that the usual work and school location choice model selects the usual location of an activity whether or not the activity is undertaken during the travel day, while the joint tour destination choice model selects the location for an activity which has already been generated.
The tour’s primary destination is the location of the activity that is assumed to provide the greatest impetus for engaging in the travel tour. In the household survey, the primary destination was not asked, but rather inferred from the pattern of stops in a closed loop in the respondents’ travel diaries. The inference was made by weighing multiple criteria including a defined hierarchy of purposes, the duration of activities, and the distance from the tour origin. The model operates in the reverse direction, designating the primary purpose and destination and then adding intermediate stops based on spatial, temporal, and modal characteristics of the inbound and outbound journeys to the primary destination.
The joint tour destination choice model is made up of three model steps:
sample - selects a sample of alternative locations for the next model step. This selects X locations from the full set of model zones using a simple utility.
logsums - starts with the table created above and calculates and adds the mode choice logsum expression for each alternative location.
simulate - starts with the table created above and chooses a final location, this time with the mode choice logsum included.
Joint tour location choice for multiple_zone_systems models uses presampling by default.
The main interface to the model is the joint_tour_destination function. This function is registered as an Inject step in the example Pipeline. See writing_logsums for how to write logsums for estimation.
Structure#
Configuration File:
joint_tour_destination.yaml
Core Table:
tours
Result Field:
destination
Skims Keys:
TAZ, alt_dest, MD time period
Configuration#
- settings activitysim.abm.models.joint_tour_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 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 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 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 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.joint_tour_destination.joint_tour_destination(state: State, tours: DataFrame, persons_merged: DataFrame, network_los: Network_LOS, model_settings: Optional[TourLocationComponentSettings] = None, model_settings_file_name: str = 'joint_tour_destination.yaml', trace_label: str = 'joint_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)