Stop Frequency#
The stop frequency model assigns to each tour the number of intermediate destinations a person will travel to on each leg of the tour from the origin to tour primary destination and back. The model incorporates the ability for more than one stop in each direction, up to a maximum of 3, for a total of 8 trips per tour (four on each tour leg).
Intermediate stops are not modeled for drive-transit tours because doing so can have unintended consequences because of the difficulty of tracking the location of the vehicle. For example, consider someone who used a park and ride for work and then took transit to an intermediate shopping stop on the way home. Without knowing the vehicle location, it cannot be determined if it is reasonable to allow the person to drive home. Even if the tour were constrained to allow driving only on the first and final trip, the trip home from an intermediate stop may not use the same park and ride where the car was dropped off on the outbound leg, which is usually as close as possible to home because of the impracticality of coding drive access links from every park and ride lot to every zone.
This model also creates a trips table in the pipeline for later models.
The main interface to the intermediate stop frequency model is the stop_frequency function. This function is registered as an Inject step in the example Pipeline.
Structure#
Configuration File:
stop_frequency.yaml
Core Table:
tours
Result Field:
stop_frequency
Configuration#
- settings activitysim.abm.models.stop_frequency.StopFrequencySettings#
Bases:
LogitComponentSettings
Settings for the stop frequency component.
- Config:
extra: str = forbid
- Fields:
- Validators:
update_sharrow_skip
»all fields
- 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 LOGIT_TYPE: Literal['MNL'] = 'MNL'#
Logit model mathematical form.
- “MNL”
Multinomial logit model.
- 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 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 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 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.stop_frequency.stop_frequency(state: State, tours: DataFrame, tours_merged: DataFrame, stop_frequency_alts: DataFrame, network_los: Network_LOS, model_settings: StopFrequencySettings | None = None, model_settings_file_name: str = 'stop_frequency.yaml', trace_label: str = 'stop_frequency') None #
stop frequency model
For each tour, shoose a number of intermediate inbound stops and outbound stops. Create a trip table with inbound and outbound trips.
Thus, a tour with stop_frequency ‘2out_0in’ will have two outbound and zero inbound stops, and four corresponding trips: three outbound, and one inbound.
Adds stop_frequency str column to trips, with fields
creates trips table with columns:
- person_id - household_id - tour_id - primary_purpose - atwork - trip_num - outbound - trip_count