Vehicle Type Choice#
The vehicle type choice model selects a vehicle type for each household vehicle. A vehicle type is a combination of the vehicle’s body type, age, and fuel type. For example, a 13 year old gas powered van would have a vehicle type of van_13_gas.
There are two vehicle type choice model structures implemented:
Simultaneous choice of body type, age, and fuel type.
Simultaneous choice of body type and age, with fuel type assigned from a probability distribution.
Structure#
Configuration File:
vehicle_type_choice.yaml
Input vehicle type data included in prototype_mtc_extended came from a variety of sources. The number of vehicle makes, models, MPG, and electric vehicle range was sourced from the Enivornmental Protection Agency (EPA). Additional data on vehicle costs were derived from the National Household Travel Survey. Auto operating costs in the vehicle type data file were a sum of fuel costs and maintenance costs. Fuel costs were calculated from MPG assuming a $3.00 cost for a gallon of gas. When MPG was not available to calculate fuel costs, the closest year, vehicle type, or body type available was used. Maintenance costs were taken from AAA’s 2017 driving cost study. Size categories within body types were averaged, e.g. car was an average of AAA’s small, medium, and large sedan categories. Motorcycles were assigned the small sedan maintenance costs since they were not included in AAA’s report. Maintenance costs were not varied by vehicle year. (According to `data from the U.S. Bureau of Labor Statistics, there was no consistent relationship between vehicle age and maintenance costs.)
Using the above methodology, the average auto operating costs of vehicles output from :ref:prototype_mtc_extended
was 18.4 cents.
This value is very close to the auto operating cost of 18.3 cents used in prototype_mtc.
Non-household vehicles in prototype_mtc_extended use the auto operating cost of 18.3 cents used in prototype_mtc.
Users are encouraged to make their own assumptions and calculate auto operating costs as they see fit.
The distribution of fuel type probabilities included in prototype_mtc_extended are computed directly from the National Household Travel Survey data and include the entire US. Therefore, there is “lumpiness” in probabilities due to poor statistics in the data for some vehicle types. The user is encouraged to adjust the probabilities to their modeling region and “smooth” them for more consistent results.
Further discussion of output results and model sensitivities can be found here.
Configuration#
- settings activitysim.abm.models.vehicle_type_choice.VehicleTypeChoiceSettings#
Bases:
LogitComponentSettings
Settings for the vehicle_type_choice 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 COLS_TO_INCLUDE_IN_ALTS_TABLE: list[str] = []#
Columns to include in the alternatives table for use in utility calculations.
- Validated by:
update_sharrow_skip
- field COLS_TO_INCLUDE_IN_CHOOSER_TABLE: list[str] = []#
Columns to include in the chooser table for use in utility calculations.
- 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 SIMULATION_TYPE: Literal['simple_simulate', 'interaction_simulate'] = 'interaction_simulate'#
- 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 alts_preprocessor: PreprocessorSettings | None = None#
- Validated by:
update_sharrow_skip
- field annotate_households: PreprocessorSettings | None = None#
- Validated by:
update_sharrow_skip
- field annotate_persons: PreprocessorSettings | None = None#
- Validated by:
update_sharrow_skip
- field annotate_vehicles: PreprocessorSettings | None = None#
- 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 explicit_chunk: float = 0#
If > 0, use this chunk size instead of adaptive chunking. If less than 1, use this fraction of the total number of rows.
- Validated by:
update_sharrow_skip
- field preprocessor: PreprocessorSettings | None = None#
- 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_type_choice.vehicle_type_choice(state: State, persons: DataFrame, households: DataFrame, vehicles: DataFrame, vehicles_merged: DataFrame, model_settings: VehicleTypeChoiceSettings | None = None, model_settings_file_name: str = 'vehicle_type_choice.yaml', trace_label: str = 'vehicle_type_choice') None #
Assign a vehicle type to each vehicle in the vehicles table.
If a “SIMULATION_TYPE” is set to simple_simulate in the vehicle_type_choice.yaml config file, then the model specification .csv file should contain one column of coefficients for each distinct alternative. This format corresponds to ActivitySim’s
activitysim.core.simulate.simple_simulate()
format. Otherwise, this model will construct a table of alternatives, at run time, based on all possible combinations of values of the categorical variables enumerated as “combinatorial_alts” in the .yaml config. In this case, the model leverages ActivitySim’sactivitysim.core.interaction_simulate()
model design, in which the model specification .csv has only one column of coefficients, and the utility expressions can turn coefficients on or off based on attributes of either the chooser _or_ the alternative.As an optional second step, the user may also specify a “PROBS_SPEC” .csv file in the main .yaml config, corresponding to a lookup table of additional vehicle attributes and probabilities to be sampled and assigned to vehicles after the logit choices have been made. The rows of the “PROBS_SPEC” file must include all body type and vehicle age choices assigned in the logit model. These additional attributes are concatenated with the selected alternative from the logit model to form a single vehicle type name to be stored in the vehicles table as the vehicle_type column.
Only one household vehicle is selected at a time to allow for the introduction of owned vehicle related attributes. For example, a household may be less likely to own a second van if they already own one. The model is run sequentially through household vehicle numbers. The preprocessor is run for each iteration on the entire vehicles table to allow for computation of terms involving the presence of other household vehicles.
The user may also augment the households or persons tables with new vehicle type-based fields specified via expressions in “annotate_households_vehicle_type.csv” and “annotate_persons_vehicle_type.csv”, respectively.
- Parameters:
- stateworkflow.State
- personspd.DataFrame
- householdspd.DataFrame
- vehiclespd.DataFrame
- vehicles_merged :pd. DataFrame
- model_settingsclass specifying the model settings
- model_settings_file_name: filename of the model settings file
- trace_label: trace label of the vehicle type choice model
- activitysim.abm.models.vehicle_type_choice.append_probabilistic_vehtype_type_choices(state: State, choices, model_settings: VehicleTypeChoiceSettings, trace_label)#
Select a fuel type for the provided body type and age of the vehicle.
Make probabilistic choices based on the PROBS_SPEC file.
- Parameters:
- stateworkflow.State
- choicespandas.DataFrame
selection of {body_type}_{age} to append vehicle type to
- model_settingsVehicleTypeChoiceSettings
- trace_labelstr
- Returns:
- choicespandas.DataFrame
table of chosen vehicle types
- activitysim.abm.models.vehicle_type_choice.annotate_vehicle_type_choice_households(state: State, model_settings: VehicleTypeChoiceSettings, trace_label: str)#
Add columns to the households table in the pipeline according to spec.
- Parameters:
- stateworkflow.State
- model_settingsVehicleTypeChoiceSettings
- trace_labelstr
- activitysim.abm.models.vehicle_type_choice.annotate_vehicle_type_choice_persons(state: State, model_settings: VehicleTypeChoiceSettings, trace_label: str)#
Add columns to the persons table in the pipeline according to spec.
- Parameters:
- stateworkflow.State
- model_settingsVehicleTypeChoiceSettings
- trace_labelstr
- activitysim.abm.models.vehicle_type_choice.annotate_vehicle_type_choice_vehicles(state: State, model_settings: VehicleTypeChoiceSettings, trace_label: str)#
Add columns to the vehicles table in the pipeline according to spec.
- Parameters:
- stateworkflow.State
- model_settingsVehicleTypeChoiceSettings
- trace_labelstr
- activitysim.abm.models.vehicle_type_choice.get_combinatorial_vehicle_alternatives(alts_cats_dict)#
Build a pandas dataframe containing columns for each vehicle alternative.
Rows will correspond to the alternative number and will be 0 except for the 1 in the column corresponding to that alternative.
- Parameters:
- alts_cats_dictdict
- Returns:
- alts_widepd.DataFrame in wide format expanded using pandas get_dummies function
- alts_longpd.DataFrame in long format
- activitysim.abm.models.vehicle_type_choice.construct_model_alternatives(state: State, model_settings: VehicleTypeChoiceSettings, alts_cats_dict, vehicle_type_data)#
Construct the table of vehicle type alternatives.
Vehicle type data is joined to the alternatives table for use in utility expressions.
- Parameters:
- stateworkflow.State
- model_settingsVehicleTypeChoiceSettings
- alts_cats_dictdict
nested dictionary of vehicle body, age, and fuel options
- vehicle_type_datapandas.DataFrame
- Returns:
- alts_widepd.DataFrame
includes column indicators and data for each alternative
- alts_longpd.DataFrame
rows just list the alternatives
- activitysim.abm.models.vehicle_type_choice.get_vehicle_type_data(state: State, model_settings: VehicleTypeChoiceSettings, vehicle_type_data_file)#
Read in the vehicle type data and computes the vehicle age.
- Parameters:
- stateworkflow.State
- model_settingsVehicleTypeChoiceSettings
- vehicle_type_data_filestr
name of vehicle type data file found in config folder
- Returns:
- vehicle_type_datapandas.DataFrame
table of vehicle type data with required body_type, age, and fuel_type columns
- activitysim.abm.models.vehicle_type_choice.iterate_vehicle_type_choice(state: State, vehicles_merged: DataFrame, model_settings: VehicleTypeChoiceSettings, model_spec, locals_dict, estimator, chunk_size, trace_label)#
Select vehicle type for each household vehicle sequentially.
Iterate through household vehicle numbers and select a vehicle type of the form {body_type}_{age}_{fuel_type}. The preprocessor is run for each iteration on the entire chooser table, not just the one for the current vehicle number. This allows for computation of terms involving the presence of other household vehicles.
Vehicle type data is read in according to the specification and joined to the alternatives. It can optionally be included in the output vehicles table by specifying the COLS_TO_INCLUDE_IN_VEHICLE_TABLE option in the model yaml.
- Parameters:
- vehicles_mergedDataFrame
vehicle list owned by each household merged with households table
- model_settingsdict
yaml model settings file as dict
- model_specpandas.DataFrame
omnibus spec file with expressions in index and one column per segment
- locals_dictdict
additional variables available when writing expressions
- estimatorEstimator object
- chunk_sizeint
- trace_labelstr
- Returns:
- all_choicespandas.DataFrame
single table of selected vehicle types and associated data
- all_chooserspandas.DataFrame
single table of chooser data with preprocessor variables included