Trip Destination

The trip location choice model predicts the location of trips (or stops) made along the tour other than the primary destination. Final trips already have a destination (the primary tour destination for outbound trips, and home for inbound trips) so no choice is needed in those cases.

Structure

• Configuration File: trip_destination.yaml

• Core Table: trips

• Result Field: destination

This model is structured as a multinomial logit model using a zone attraction size variable and route deviation measure as impedance. The alternatives are sampled from the full set of zones, subject to availability of a zonal attraction size term. The sampling mechanism is also based on accessibility between tour origin and primary destination, and is subject to certain rules based on tour mode.

All destinations are available for auto tour modes, so long as there is a positive size term for the zone. Intermediate stops on walk tours must be within X miles of both the tour origin and primary destination zones. Intermediate stops on bike tours must be within X miles of both the tour origin and primary destination zones. Intermediate stops on walk-transit tours must either be within X miles walking distance of both the tour origin and primary destination, or have transit access to both the tour origin and primary destination. Additionally, only short and long walk zones are available destinations on walk-transit tours.

The intermediate stop location choice model works by cycling through stops on tours. The level-of-service variables (including mode choice logsums) are calculated as the additional utility between the last location and the next known location on the tour. For example, the LOS variable for the first stop on the outbound direction of the tour is based on additional impedance between the tour origin and the tour primary destination. The LOS variable for the next outbound stop is based on the additional impedance between the previous stop and the tour primary destination. Stops on return tour legs work similarly, except that the location of the first stop is a function of the additional impedance between the tour primary destination and the tour origin. The next stop location is based on the additional impedance between the first stop on the return leg and the tour origin, and so on.

Trip location choice for two- and three-zone models uses presampling by default.

The main interface to the trip destination choice model is the trip_destination function. This function is registered as an Inject step in the example Pipeline. See writing_logsums for how to write logsums for estimation.

Note

Trip purpose and trip destination choice can be run iteratively together via trip_purpose_and_destination.

Configuration

settings activitysim.abm.models.trip_destination.TripDestinationSettings

Settings for the trip_destination component.

New in version 1.2.

Fields:

• ALT_DEST_COL_NAME (str)

• CLEANUP (bool)

• DEST_CHOICE_LOGSUM_COLUMN_NAME (str)

• DEST_CHOICE_SAMPLE_TABLE_NAME (str)

• PRIMARY_DEST (str)

• PRIMARY_ORIGIN (str)

• REDUNDANT_TOURS_MERGED_CHOOSER_COLUMNS (list[str] | None)

• TRIP_ORIGIN (str)

• fail_some_trips_for_testing (bool)

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

field ALT_DEST_COL_NAME: str = 'dest_taz'

Validated by:

• deprecated_destination_prefix

field CLEANUP: bool [Required]

Validated by:

• deprecated_destination_prefix

field DEST_CHOICE_LOGSUM_COLUMN_NAME: str = None

Validated by:

• deprecated_destination_prefix

field DEST_CHOICE_SAMPLE_TABLE_NAME: str = None

Validated by:

• deprecated_destination_prefix

field PRIMARY_DEST: str = 'tour_leg_dest'

Validated by:

• deprecated_destination_prefix

field PRIMARY_ORIGIN: str = 'origin'

Validated by:

• deprecated_destination_prefix

field REDUNDANT_TOURS_MERGED_CHOOSER_COLUMNS: list[str] | None = None

Validated by:

• deprecated_destination_prefix

field TRIP_ORIGIN: str = 'origin'

Validated by:

• deprecated_destination_prefix

field fail_some_trips_for_testing: bool = False

This setting is used by testing code to force failed trip_destination.

Validated by:

• deprecated_destination_prefix

field preprocessor: PreprocessorSettings | None = None

Validated by:

• deprecated_destination_prefix

validator deprecated_destination_prefix  »  all fields

property DESTINATION_SAMPLE_SPEC: Path

Alias for SAMPLE_SPEC.

Deprecated since version 1.3.

property DESTINATION_SPEC: Path

Alias for SPEC.

Deprecated since version 1.3.

Examples

• Prototype MTC

• Prototype ARC

Implementation

activitysim.abm.models.trip_destination.trip_destination(state: State, trips: DataFrame, tours_merged: DataFrame, model_settings: Optional[TripDestinationSettings] = None, model_settings_file_name: str = 'trip_destination.yaml', trace_label: str = 'trip_destination') → None

Choose a destination for all intermediate trips based on trip purpose.

The trip (or stop) location choice model predicts the location of trips (or stops) along the tour other than the primary destination. This model is structured as a multinomial logit model using a zone attraction size variable and route deviation measure as impedance. The alternatives are sampled from the full set of zones, subject to availability of a zonal attraction size term (i.e., it is non-zero). The sampling mechanism is also usually based on accessibility between tour origin and primary destination, and can be subject to certain rules based on tour mode.

Parameters:

stateworkflow.State

tripsDataFrame

The trips table. This table is edited in-place to add the trip destinations.

tours_mergedDataFrame

The tours table, with columns merge from persons and households as well.

model_settingsTripDestinationSettings, optional

The settings used in this model component. If not provided, they are loaded out of the configs directory YAML file referenced by the model_settings_file_name argument.

model_settings_file_namestr, default “trip_destination.yaml”

This is where model setting are found if model_settings is not given explicitly. The same filename is also used to write settings files to the estimation data bundle in estimation mode.

trace_labelstr, default “free_parking”

This label is used for various tracing purposes.

Context Variables

The following variables are made available for use in this component’s utility specifications:

• network_los (Network_LOS): A reference to the main network_los object for this model.

• size_terms (DataFrameMatrix): This DataFrameMatrix offers a specialized two-dimension lookup wrapper on an array, to access the size terms by alternative zone and trip purpose by label simultaneously. When sharrow is enabled for this model, this value also embeds a special linked array accessible as size_terms['sizearray'], which automatically compiles to point to the alternative destination zone and the ‘purpose_index_num’ (an integer offset value instead of a label, which should be set in a preprocessor).

• size_terms_array (numpy.ndarray): A numpy array of size term values, with rows for zones and columns for trip purposes. This is just the raw data underneath the size_terms value above.

• timeframe (str): Contains the constant value “trip”.

• odt_skims (Skim3dWrapper or DatasetWrapper): Skims giving the LOS characteristics from the fixed trip origin to each alternative destination, by time period.

• dot_skims (Skim3dWrapper or DatasetWrapper): Skims giving the LOS characteristics from each alternative destination backwards to the fixed trip origin, by time period.

• dpt_skims (Skim3dWrapper or DatasetWrapper): Skims giving the LOS characteristics from each alternative destination to the tour final destination, by time period.

• pdt_skims (Skim3dWrapper or DatasetWrapper): Skims giving the LOS characteristics backwards to each alternative destination from the tour final destination, by time period.

• od_skims (SkimWrapper or DatasetWrapper): Skims giving the LOS characteristics from the fixed trip origin to each alternative destination.

• dpt_skims (SkimWrapper or DatasetWrapper): Skims giving the LOS characteristics from each alternative destination to the tour final destination.

The following TransitVirtualPathLogsumWrapper values are also available, only for 3-zone models:

• tvpb_logsum_odt

• tvpb_logsum_dot

• tvpb_logsum_dpt

• tvpb_logsum_pdt

Additional Related Functions

activitysim.abm.models.trip_destination.trip_destination_sample(state: State, primary_purpose, trips, alternatives, model_settings, size_term_matrix, skim_hotel, estimator, chunk_size, trace_label)

Returns:

destination_sample: pandas.dataframe

choices_df from interaction_sample with (up to) sample_size alts for each chooser row index (non unique) is trip_id from trips (duplicated for each alt) and columns dest_zone_id, prob, and pick_count

dest_zone_id: int

alt identifier from alternatives[<alt_col_name>]

prob: float

the probability of the chosen alternative

pick_countint

number of duplicate picks for chooser, alt

activitysim.abm.models.trip_destination.compute_logsums(state: State, primary_purpose, trips: DataFrame, destination_sample, tours_merged: DataFrame, model_settings: TripDestinationSettings, skim_hotel, trace_label: str)

Calculate mode choice logsums using the same recipe as for trip_mode_choice, but do it twice for each alternative since we need out-of-direction logsum (i.e . origin to alt_dest, and alt_dest to half-tour destination)

Returns:

adds od_logsum and dp_logsum columns to trips (in place)

activitysim.abm.models.trip_destination.compute_ood_logsums(state, *args, **kwargs)

activitysim.abm.models.trip_destination.trip_destination_simulate(state: State, primary_purpose, trips, destination_sample, model_settings: TripDestinationSettings, want_logsums, size_term_matrix, skim_hotel, estimator, trace_label)

Chose destination from destination_sample (with od_logsum and dp_logsum columns added)

Returns:

choices - pandas.Series

destination alt chosen