Mode Choice Diagnostic Tool
The mode choice diagnostic tool is intended to help analyze SANDAG's activity-based travel model mode choice results. The tool runs a diagnostic synthetic population covering user-defined origin MAZs (i.e. MGRAs) through the activity-based model in order to visualize tour mode choice probabilities and utilities for a target market population. The synthetic population is generated to cover several user-defined key market segment attributes (e.g. auto ownership, income, educational attainment) and uses default values for other market attributes (e.g. employment statuses, number of persons per household). A file of representative tours (work, shopping) is generated for the synthetic population with pre-determined schedules and destinations. The destination MAZs of interest are user-defined. The activity-based model reads in these generated household, person and tour files and outputs tour mode choice probabilities and utilities for each tour and destination. Finally, a Jupyter Notebook based Python diagnostic visualizer plots, maps and charts results and allows users to query results for sample households, persons, tours and destinations. The following sections describe the setup and application of this tool:
- Process Overview
- Configuring the Mode Choice Diagnostic Tool
- Running the Mode Choice Diagnostic Tool
- Visualizing the Mode Choice Diagnostic Results
The mode choice diagnostic tool is broken up into 2 main components: a stand-alone mode choice diagnostic Emme tool and a stand-alone diagnostic visualizer.
The stand-alone mode choice diagnostic Emme tool was created using Python and utilizes the pandas and yaml packages to generate the synthetic population. There are 3 main inputs to stand-alone Emme tool: a list of origin MAZs, a list of destination MAZs and a configuration file.
When creating a scenario folder, a mode choice diagnostic (mcd) directory is created within the scenario directory's input directory. The input/mcd directory will contain the 3 input files (listed above), which users can edit. After a successful mode choice diagnostic run, an mcd directory will be created within the scenario directory's output directory. The output/mcd directory will be populated with the output synthetic population files and the final tour mode choice file.
The mode choice diagnostic tool consists of the following procedures:
First, the mode choice diagnostic tool generates a synthetic population using the specified target market attributes from the configuration file along with the list of specified origin and destination MAZs. The resulting synthetic population files are output to the output/mcd directory.
Next, the mode choice diagnostic tool reads the main SANDAG AB Model properties file, modifies a number of property tokens so that it is compatible with the mode choice diagnostic tool, and then saves a copy of the properties file as sandag_abm_mcd.properties. The new properties file is saved in the same directory as the original properties file (conf directory).
Next, the activity-based model reads in the newly generated synthetic population files and outputs tour mode choice probabilities and utilities for each tour and destination. The resulting tour file, along with other mode choice outputs, are output to the output/mcd directory.
Finally, the results of the tool may be queried, visualized, and explored using the SANDAG Mode Choice Diagnostic Visualizer Notebook. Filter the output data by purpose, mode, income, autos, etc. and superimpose the probability and/or utility results over a map of the region.
Configuring the mode choice diagnostic tool involves specifying target market attributes along with desired origin and destination MAZs.
Users may specify attributes for household, person and tour files that will be used to create synthetic population files for target market segments. The target market attributes are set via the input/mcd/syn_pop_attributes.yaml configuration file. Upon scenario creation, the configuration file is populated with default attributes for the mentioned files.
It should be noted that not all synthetic population file attributes may be set. Attributes such as total number of household members or employment statuses are kept as pre-defined fixed values.
The resulting target households will be generated using all possible combinations of the household attribute values listed in the table below. For each household attribute, users must specify all desired category values of said attribute so that they are included in the output household files.
| Attribute | Description |
|---|---|
| hinc | Household income(s) |
| veh | Number of vehicles in household(s) |
| hht |
Household/family type(s): 0 = Not in universe (vacant or GQ) 1 = Family household: married-couple 2 = Family household: male householder, no wife present 3 = Family household: female householder, no husband present 4 = Nonfamily household: male householder, living alone 5 = Nonfamily household: male householder, not living alone 6 = Nonfamily household: female householder, living alone 7 = Nonfamily household: female householder, not living alone |
| bldgsz |
Building size(s) - Number of Units in Structure & Quality: 1 = Mobile home or trailer 2 = One-family house detached 3 = One-family house attached 4 = 2 Apartments 5 = 3-4 Apartments 6 = 5-9 Apartments 7 = 10-19 Apartments 8 = 20-49 Apartments 9 = 50 or more apartments 10 = Boad, RV, van, etc. |
| unittype | Household unit type(s): 0 = Non-GQ Household 1 = GQ Household |
Each household has a fixed number of persons (2) where the first person is a worker and the second a non-worker. Therefore, person attributes must contain exactly 2 values (1 for each household member) where the first value corresponds to the worker and the second to the non-worker.
| Attribute | Description |
|---|---|
| age | Age of person |
| sex |
Gender of person 1 = Male 2 = Female |
| miltary |
Military status of person: 0 = N/A Less than 17 Years Old 1 = Yes, Now on Active Duty 2 = Yes, on Active Duty in Past, but Not Now 3 = No, Training for Reserves/National Guard Only 4 = No, Never Served in the Military |
| grade |
School grade of person: 0 = N/A (not attending school) 1 = Nursery school/preschool 2 = Kindergarten 3 = Grade 1 to grade 4 4 = Grade 5 to grade 8 5 = Grade 9 to grade 12 6 = College undergraduate 7 = Graduate or professional school |
| educ |
Educational attainment: 0 = N/A (Under 3 years) 1 = No schooling completed 2 = Nursery school to 4th grade 3 = 5th grade or 6th grade 4 = 7th grade or 8th grade 5 = 9th grade 6 = 10th grade 7 = 11th grade 8 = 12th grade no diploma 9 = High school graduate 10 = Some college but less than 1 year 11 = One or more years of college no degree 12 = Associate degree 13 = Bacehlor's degree 14 = Master's degree 15 = Professional degree 16 = Doctorate degree |
Like person attributes, tour attributes must contain exactly 2 values (1 for each household member) where the first value corresponds to the worker and the second to the non-worker.
| Attribute | Description |
|---|---|
| start_period |
Start Period: 1 = Before 5:00AM 2 = 5:00AM-5:30AM 3 through 39 is every half hour time slots 40 = After 12:00AM |
| end_period |
End Period: 1 = Before 5:00AM 2 = 5:00AM-5:30AM 3 through 39 is every half hour time slots 40 = After 12:00AM |
| av_avail |
Autonomous vehicle availability for the tour: 0 = No 1 = Yes |
In addition to target market synthetic population attributes, users may specify both the desired origin and destination MAZs via the input/mcd/origin_mgra.csv and input/mcd/destination_mgra.csv files, respectively. All specified origin MAZs will be populated with the target market households and persons. Every household worker will have a mandatory work tour destined to each of the specified destination MAZs. Similarly, every non-worker will have a non-mandatory shop tour destined to the same MAZ as the worker.
Users may launch the stand-alone mode choice diagnostic Emme tool via the Emme Modeller interface (as described in Run the Model). Within the Emme Modeller, the mode choice diagnostic GUI may be accessed via SANDAG toolbox > Diagnostic > Mode choice diagnostic. To commence the tool, users simply need to click on Run, as is shown in the figure below.
Launch the MC Visualizer Jupyter Notebook and configure using the Diagnostic Tool outputs. Users must ensure Jupyter is installed on their system. The mc_utils.py helper file must be in the same directory as the notebook. Users will also need a MGRA shapefile of the study region in addition to the Diagnostic Tool outputs.