Non-Mandatory Tour Frequency#
The non-mandatory tour frequency model selects the number of non-mandatory tours made by each person on the simulation day. It also adds non-mandatory tours to the tours in the data pipeline. The individual non-mandatory tour frequency model operates in two stages:
A choice is made using a random utility model between combinations of tours containing zero, one, and two or more escort tours, and between zero and one or more tours of each other purpose.
Up to two additional tours of each purpose are added according to fixed extension probabilities.
The main interface to the non-mandatory tour purpose frequency model is the non_mandatory_tour_frequency function. This function is registered as an Inject step in the example Pipeline.
Structure#
Configuration File:
non_mandatory_tour_frequency.yaml
Core Table:
persons
Result Field:
non_mandatory_tour_frequency
Configuration#
- settings activitysim.abm.models.non_mandatory_tour_frequency.NonMandatoryTourFrequencySettings#
Bases:
LogitComponentSettings
Settings for the non_mandatory_tour_frequency component.
- Fields:
NESTS (activitysim.core.configuration.logit.LogitNestSpec | None)
annotate_persons (activitysim.core.configuration.base.PreprocessorSettings | None)
annotate_tours (activitysim.core.configuration.base.PreprocessorSettings | None)
preprocessor (activitysim.core.configuration.base.PreprocessorSettings | None)
- Validators:
nests_are_for_nl
»NESTS
- 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 LOGIT_TYPE: Literal['MNL', 'NL'] = 'MNL'#
Logit model mathematical form.
- “MNL”
Multinomial logit model.
- “NL”
Nested multinomial logit model.
- 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 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 SPEC_SEGMENTS: list[NonMandatoryTourSpecSegment] = []#
- field annotate_persons: PreprocessorSettings | None = None#
Preprocessor settings to annotate persons
- field annotate_tours: PreprocessorSettings | None = None#
Preprocessor settings to annotate tours
- field preprocessor: PreprocessorSettings | None = None#
Setting for the preprocessor.
- 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_tour_frequency.non_mandatory_tour_frequency(state: State, persons: DataFrame, persons_merged: DataFrame, model_settings: Optional[NonMandatoryTourFrequencySettings] = None, model_settings_file_name: str = 'non_mandatory_tour_frequency.yaml', trace_label: str = 'non_mandatory_tour_frequency') None #
This model predicts the frequency of making non-mandatory trips (alternatives for this model come from a separate csv file which is configured by the user) - these trips include escort, shopping, othmaint, othdiscr, eatout, and social trips in various combination.