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:

1. Simultaneous choice of body type, age, and fuel type.

2. 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.

Fields:

• COEFFICIENTS (pathlib.Path | None)

• COLS_TO_INCLUDE_IN_VEHICLE_TABLE (list[str])

• CONSTANTS (dict[str, typing.Any])

• FLEET_YEAR (int)

• LOGIT_TYPE (Literal['MNL', 'NL'])

• NESTS (activitysim.core.configuration.logit.LogitNestSpec | None)

• PROBS_SPEC (str | None)

• REQUIRE_DATA_FOR_ALL_ALTS (bool)

• SIMULATION_TYPE (Literal['simple_simulate', 'interaction_simulate'])

• SPEC (pathlib.Path)

• VEHICLE_TYPE_DATA_FILE (str | None)

• WRITE_OUT_ALTS_FILE (bool)

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

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

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

• combinatorial_alts (dict | None)

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

• sharrow_skip (bool)

• source_file_paths (list[pathlib.Path])

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 COLS_TO_INCLUDE_IN_VEHICLE_TABLE: list[str] = []

field CONSTANTS: dict[str, Any] = {}

Named constants usable in the utility expressions.

field FLEET_YEAR: int [Required]

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 PROBS_SPEC: str | None = None

field REQUIRE_DATA_FOR_ALL_ALTS: bool = False

field SIMULATION_TYPE: Literal['simple_simulate', 'interaction_simulate'] = 'interaction_simulate'

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 VEHICLE_TYPE_DATA_FILE: str | None = None

field WRITE_OUT_ALTS_FILE: bool = False

field annotate_households: PreprocessorSettings | None = None

field annotate_persons: PreprocessorSettings | None = None

field annotate_vehicles: PreprocessorSettings | None = None

field combinatorial_alts: dict | None = None

field preprocessor: PreprocessorSettings | None = None

field sharrow_skip: bool = False

Skip sharrow when evaluating this component.

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.

validator nests_are_for_nl  »  NESTS

Checks that nests are provided if (and only if) LOGIT_TYPE is NL.

Examples

• Prototype MTC

Implementation

activitysim.abm.models.vehicle_type_choice.vehicle_type_choice(state: State, persons: DataFrame, households: DataFrame, vehicles: DataFrame, vehicles_merged: DataFrame, model_settings: Optional[VehicleTypeChoiceSettings] = 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’s activitysim.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