Vehicle Allocation#
The vehicle allocation model selects which vehicle would be used for a tour of given occupancy. The alternatives for the vehicle allocation model consist of the vehicles owned by the household and an additional non household vehicle option. (Zero-auto households would be assigned the non-household vehicle option since there are no owned vehicles in the household). A vehicle is selected for each occupancy level set by the user such that different tour modes that have different occupancies could see different operating characteristics. The output of the vehicle allocation model is appended to the tour table with column names vehicle_occup_{occupancy} and the values are the vehicle type selected.
In prototype_mtc_extended, three occupancy levels are used: 1, 2, and 3.5. The auto operating cost
for occupancy level 1 is used in the drive alone mode and drive to transit modes. Occupancy levels 2 and 3.5 are used for shared
ride 2 and shared ride 3+ auto operating costs, respectively. Auto operating costs are selected in the mode choice pre-processors by selecting the allocated
vehicle type data from the vehicles table. If the allocated vehicle type was the non-household vehicle, the auto operating costs uses
the previous default value from prototype_mtc. All trips and atwork subtours use the auto operating cost of the parent tour. Functionality
was added in tour and atwork subtour mode choice to annotate the tour table and create a selected_vehicle
which denotes the actual vehicle used.
If the tour mode does not include a vehicle, then the selected_vehicle
entry is left blank.
The current implementation does not account for possible use of the household vehicles by other household members. Thus, it is possible for a selected vehicle to be used in two separate tours at the same time.
Structure#
Configuration File:
vehicle_allocation.yaml
Result Field:
vehicle_occup_{occupancy}
Configuration#
- settings activitysim.abm.models.vehicle_allocation.VehicleAllocationSettings#
Bases:
LogitComponentSettings
Settings for the joint_tour_scheduling 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', 'NL'] = 'MNL'#
Logit model mathematical form.
- “MNL”
Multinomial logit model.
- “NL”
Nested 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 OCCUPANCY_LEVELS: list = [1]#
Occupancy level
It will create columns in the tour table selecting a vehicle for each of the occupancy levels. They are named vehicle_occup_1, vehicle_occup_2,… etc. if not supplied, will default to only one occupancy level of 1
- Validated by:
update_sharrow_skip
- 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.
- Validated by:
update_sharrow_skip
- field annotate_tours: PreprocessorSettings | None = None#
Preprocessor settings to annotate tours
- 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.vehicle_allocation.vehicle_allocation(state: State, persons: DataFrame, households: DataFrame, vehicles: DataFrame, tours: DataFrame, tours_merged: DataFrame, network_los: Network_LOS, model_settings: VehicleAllocationSettings | None = None, model_settings_file_name: str = 'vehicle_allocation.yaml', trace_label: str = 'vehicle_allocation') None #
Selects a vehicle for each occupancy level for each tour.
Alternatives consist of the up to the number of household vehicles plus one option for non-household vehicles.
The model will be run once for each tour occupancy defined in the model yaml. Output tour table will columns added for each occupancy level.
The user may also augment the tours tables with new vehicle type-based fields specified via the annotate_tours option.
- Parameters:
- stateworkflow.State
- personspd.DataFrame
- householdspd.DataFrame
- vehiclespd.DataFrame
- tourspd.DataFrame
- tours_mergedpd.DataFrame
- network_loslos.Network_LOS
- activitysim.abm.models.vehicle_allocation.annotate_vehicle_allocation(state: State, model_settings: VehicleAllocationSettings, trace_label: str)#
Add columns to the tours table in the pipeline according to spec.
- Parameters:
- model_settingsVehicleAllocationSettings
- trace_labelstr
- activitysim.abm.models.vehicle_allocation.get_skim_dict(network_los: Network_LOS, choosers: DataFrame)#
Returns a dictionary of skim wrappers to use in expression writing.
Skims have origin as home_zone_id and destination as the tour destination.
- Parameters:
- network_losactivitysim.core.los.Network_LOS object
- chooserspd.DataFrame
- Returns:
- skimsdict
index is skim wrapper name, value is the skim wrapper