SEMCOG Activity-based Travel Demand Model
User Guide

1 Introduction

This document is intended to serve as a user guide to describe the overall structure of the SEMCOG Activity-based Modeling (ABM) system, the model setup and running procedures, and the model system inputs and outputs. The user guide describes the SEMCOG ABM version – ActSim One, that has been developed by RSG in collaboration with SEMCOG, the Metropolitan Planning Organization for Southeast Michigan.

The SEMCOG ActSim model is an integrated regional model and is based on the open-source ActivitySim modeling package for resident travel within the region, and the r-freight package for SEMCOG’s Commercial Vehicle (CV) travel. TransCAD Transportation Planning Software is used to run the whole model. Figure 1 below shows the overall SEMCOG ABM system with the model’s input and output data. In the Models box below, the steps bordered in red are done in TransCAD, steps in green are done in Python, and steps in blue are done in R.

Figure 1: SEMCOG ABM overview

The following sections of the user guide cover the following topics:

• The system architecture which describes the high-level model entities
• The ABM model’s software design
• The ABM model’s input and output files
• Model installation and run
• Working with ActivitySim
• Working with model outputs
• Setting up the model for scenario testing

2 System Architecture

This section of the user guide introduces the overall ABM system architecture. The SEMCOG ABM, similar to the trip-based model, is implemented within the TransCAD transportation planning software. In short, TransCAD first carries out the skimming procedure, the results of which are then read in by ActivitySim and the SEMCOG Commercial Vehicle Model (CVM). The main output of ActivitySim and CVM, the OD demand matrices, are then used by TransCAD to carry out assignments and produce relevant summaries and reports. In the following subsections, these steps are described in more detail.

Figure 2: Model System - SEMCOG ActSim

2.1 Network processing and skimming

TransCAD initiates the model run by reading in the highway network, transit route system, and the TAZ land use data in its proprietary database format. TransCAD uses these inputs to create the highway and transit skims, with the outputs being in the proprietary mtx format in addition to the open-source omx format. The highway skims are generated by mode (single-occupancy vehicle (SOV), high-occupancy vehicle with 2 passengers (HOV2), high-occupancy vehicle with 3+ passengers (HOV3)), time of day (early morning (EA), peak morning (AM), mid-day (MD), peak afternoon (PM), late night (EV)), and impedance (travel time and distance) therefore creating a total of 30 highway skim files. Transit skimming is done by transit market (local, premium, mix), access/egress mode (walk, park-ride, reverse park-ride, kiss-ride, reverse kiss-ride), time of day (EA, AM, MD, PM, EV), and impedances by transit operator (e.g. IVT, fare, transfer, etc.), creating a total of 1933 transit skim tables.

2.2 Airport and External trip distribution

The resident Airport and External trip production tables are read in by TransCAD, where a destination choice model distributes the trips and creates the resident OD demand matrices by time of day. The input data to the external models are productions and attractions at each external station. The input to the airport model are the zonal enplanement data.

2.3 ActivitySim

As the next model step, TransCAD initiates the ActivitySim framework through a batch file. Before running ActivitySim itself, the batch file pools together all the skim tables created by TransCAD into one large omx file to be read in more efficiently by ActivitySim. In addition, and as required by the 2-zone ActivitySim structure, the batch file also calls on a python script to create the MAZ-MAZ walk and bike skims and MAZ-stop access/egress walk skims using the All-street network. Finally, the batch file runs ActivitySim and combines the airport and external OD matrices with the internal OD matrices produced by ActivitySim to create the final passenger OD matrices for the region.

Figure 3: SEMCOG ActivitySim structure

2.4 Commercial vehicle model

Following running ActivitySim, TransCAD initiates the commercial vehicle model (CVM) to generate the truck OD matrices by time of day and by three truck classes (Light, Medium, Heavy). These OD matrices are then combined with the passenger ODs, with the resulting output being the total OD matrices (by time of day) to be read in by the assignment procedure.

Figure 4: SEMCOG CVM structure

2.5 Highway and transit assignment

TransCAD carries out the highway and transit assignment using the total OD matrices and runs a feedback loop until the convergence criteria are achieved or the user defined number of feedback loops are met. Then TransCAD runs the transit assignment during the last feedback.

3 Software Design

3.1 SEMCOG ABM Software Architecture

The SEMCOG ActSim is implemented in and run primarily by the TransCAD transportation planning software platform produced by Caliper (https://www.caliper.com/tcovu.htm). The model uses TransCAD version 8, build 22365, and has a graphical user interface (GUI) programmed in TransCAD’s GISDK scripting language that is used to manage scenarios, start model runs, produce output reports, and run other modeling utilities.

ActivitySim, a python-based activity-based model package (https://activitysim.github.io/activitysim), is run through TransCAD and models the internal resident model trips (with the exception of airport trips). The version of ActivitySim implemented for SEMCOG is 1.0.4, and the python version required is 3.9+.

SEMCOG CVM is also run through TransCAD and models the freight trips in the region. The CVM is programmed in R, an open source statistical programming platform available from The Comprehensive R Archive Network (https://cran.r-project.org/). The CV model uses R version 4.1.2 for Windows (64 bit) (https://cran.r-project.org/bin/windows/base/old/4.1.2/R-4.1.2-win.exe).

This section of the user guide describes the structure of the overall model system, covering:

• Overall model system file structure

• Software GUI implementation in TransCAD

• Overall description of the model steps

3.1.1 Overall Model System File Structure

The latest version of the SEMCOG ActSim is hosted on GitHub (https://gitHub.com/SEMCOG/SEMCOG_TDM.git), which is accessible upon approval by SEMCOG since currently it is a private repository. The installation process is described later in the User Guide in the Running the Model chapter. Once installed, the final folder structure is flexible in terms of the location of the root model directory, but the relative structure of the folders and the folder names should be maintained the same to allow the different parts of the TDM to work together.

Inside that directory, the model has the file structure shown in the figure below, with five primary directories:

• The ABM folder which contains the ActivitySim configuration files and scripts.

• The AddIn folder which contains the TransCAD add-in files including the GISDK scripts and the compiled TransCAD GUI file.

• The CVM folder which contains the CV model’s scripts, parameters, inputs that do not vary across scenarios, and additional R function libraries.

• The Model Runs folder which contains folders for each scenario and within those folders the scenario specific inputs and outputs.

• The Tasks folder which contains scripts related to model estimation, calibration, survey processing, validation, and visualization.

Figure 5: SEMCOG ABM file structure

* ABM                                 ABM directory
  + configs                           ABM configuration files
  + configs_mp                        ABM multiprocessing configuration files
  + scripts                           ABM batch files, pre-ActivitySim preparation scripts 
  + visualizer                        ABM visualizer scripts
* AddIn                               TransCAD add-in directory
  + bmp                               TransCAD GUI images
  + rsc                               TransCAD GISDK scripts
* CVM                                 CVM scripts and files
  + dev                               CVM estimation and calibration files          
  + lib                               CVM data and script files
* Model Runs                          Scenarios directory
  + SEMCOG_ABM                        Scenario directory containing
    - Input                           Model input
    - Output                          Model output
* Tasks                               Model estimation, calibration, and survey processing scripts
* README.md                           Model repository README file

The contents of the SEMCOG ABM folders are described in more detail below.

3.1.2 SEMCOG ABM TransCAD GUI

This subsection goes over the overall model GUI structure and design, while, the Running the Model chapter discusses model installation, including setting up the TransCAD Add-in and ActivitySim.

The Figure below shows the SEMCOG ABM GUI that controls the model run. The scenarios created to run the model are shown in the top window. Double-clicking on the scenario name will bring up the model input and output paths in addition to the model parameters.

Figure 6: SEMCOG model TransCAD GUI

Clicking on the blue button in the Run Model tab will open up the list of steps to run as part of the SEMCOG ABM. The figure below shows the steps in the model.

Figure 7: SEMCOG ABM model steps

As the figure above shows, there are six main steps in running the model:

• Model Initialization: This step starts by setting up the required directories in the scenario output folder and exports network data which are later needed to create 2-zone specific skims within the ActivitySim step. Following this step, the microzone-level land use data is aggregated to the TAZ level to be used by any model step requiring TAZ-level data. Highway and transit network input data are then read in and processed and TransCAD builds the highway and transit networks which are later used for skimming and assignment.

• Network skimming: This step carries out the highway and transit skimming. In the first feedback loop of the model, the skimming is done using free-flow speeds, but the later loops will provide congested skim tables based on the last loop’s assignment results.

• External and airport models: This step distributes the airport and external trips (read in as input) using a simplified destination choice model. These models are implemented as GISDK macros.

• ActivitySim: This step is run by calling on ActivitySim Preprocessing, ActivitySim, ActivitySim Postprocessing. and the Visualizer batch files.

  • The ActivitySim Preprocessing batch file calls on a number of python scripts to prepare all the input files needed to un ActivitySim:

    • COUNTY.py: This script creates a skim-like table where each column denotes the county district to which a destination zone belongs. This table helps determine what district each alternative destination zone belongs to in a destination choice model.

    • build_omx.py: TransCAD creates one skim table for each combination of period, mode, and impedance. This script pools together all these skim files into one skims.omx file to be read in by ActivitySim.

    • 2-zone_prep.py: This script creates the 2-zone specific skims needed by ActivitySim. These skims include MAZ-MAZ walk and bike times in addition to the MAZ-stop access/egress times by transit market. The skimming procedure is done using the python Pandana library and the All-street network.

  • Following the preprocessing step, the ActivitySim batch file runs ActivitySim. The postprocessing step, then, calls on the following batch file to process the ActivitySim output:

    • add_auxiliary_demand.py: This script reads in the OD matrices produced by ActivitySim, separates the highway and transit ODs into different files, and adds up the airport and external ODs. The result of this step is the total passenger OD trips

  • The Visualizer batch file calls on the Visualizer script to create the ABM Visualizer based on the ActivitySim output.

• Commercial Vehicle Model: This step runs the CVM, whose output, the freight ODs, are combined with the passenger ODs to create the total OD matrices ready for assignment. The CVM step runs the RUN_SEMCOG_CVTM batch file and consists of the the following three models, followed by trip table and summary dashboard creation scripts:

  • FIRM SYNTHESIS MODEL which develops a list of business establishment locations and processes zonal land use data used to generate truck trip demand in later steps of the CV model.

  • LONG-DISTANCE TRUCK MODEL which estimates long-haul freight truck travel to and from the region, as well as external to external truck travel through the region.

  • COMMERICAL VEHICLE TOURING MODEL (CVTM), which estimates demand for local deliveries and the provision of services by non-freight carrying trucks. The tours and trips simulated to serve this demand, when combined with the travel from the long-distance truck model, means that the CV model simulates all truck movements within, to, from, and through the region.

• Trip assignment: This step runs the highway and transit assignments. The model feedback step is also run before starting the next feedback loop iteration, if needed.

4 Data Inputs & Outputs

This section of the report discusses the model input and output in more detail.

4.1 Input files

At a high level, the input data to the SEMCOG ABM include:

• TransCAD-related inputs:

  • Highway network, transit route system, and TAZ land use data: these inputs are used by the TransCAD software to create the highway and transit skims and subsequently carry out highway and transit assignments.

  • IE/EE trip tables: The Internal-External and External-External demand tables are read in by TransCAD where a trip distribution model creates the OD matrices for the non-internal trips.

• ActivitySim-related inputs:

  • All-street network, synthetic population, and MAZ land use data: this set of inputs are read in by the ActivitySim framework to first create the MAZ-MAZ walk and bike skims, MAZ-stop transit access/egress skims, and then run the activity-based model for the region.

• CVM-related inputs:

  • CVM-related input data: this set of inputs is read in by the Commercial Vehicle Model (CVM) to create the CV OD trip tables. For more information, refer to the CVM Model User Guide.

These input data are located within Model_Runs/Scenario_folder/Inputs directory. The structure of the Input folder is as follows:

Figure 1: SEMCOG ABM Input folder Structure

* Input                           Model input folder

  + AQ                            Air quality analysis files
  
  + EJ                            Environmental justice analysis files
  
  + Network                       Highway network and transit route system, 
                                  Count file for validation, and assignment loading factors
  
  + Params                        Transit-related parameters
  
  + SE_Data                       Socio-economic data input files used by ActivitySim and the CVM
  
  + Visualizer                    scripts and batch file to run the ActivitySim visualizer
  
  + Zonal_Data                    TAZ and MAZ GIS files, External and Airport trip files
  

4.1.1 SE_Data folder

The SE Data folder mainly contains input required by ActivitySim. Table 1 below shows the contents of the folder in more detail:

Table 2: List of files in the Data folder

File	Description	File.type
households.csv	Synthetic household-level population used by ActivitySim	csv
persons.csv	Synthetic person-level population used by ActivitySim	csv
land_use.csv	Land use data at the microzone (MAZ) level; used by ActivitySim	csv
land_use_taz.csv	Land use data at the TAZ level; used by TransCAD skimming	csv
TAZSocioEconomicsBuffer.csv	SE data for the buffer zones of the region, used by the CVM	csv

The synthetic population data includes a household file and a person file. The attributes in these file are provides in the tables below.

Table 3: Synthetic households file attributes

Field	Description	Scale
household_id	Unique household ID number	Integer, any value
taz	Transportation analysis zone of home location	Integer
maz	Micro-analysis zone of home location	Integer
type	Type of unit	Integer, 1 <96> housing unit; 3 <96> non-institutional groups quarters
hincp	Household income in 2019$	Numeric, dollars in ACS year
adjinc	2019 adjustment factor for dollar amounts	Numeric
persons	Number of persons in the household	Integer, 1 and up
children	Number of children in the household	Integer, 1 and up
hht	Household/family type	Integer, 1 - family household: married-couple; 2 - family household: male householder, no wife present; 3 - family household: female householder, no husband present; 4 - non-family household: male householder living alone; 5 - non-family household: male householder, not living alone; 6 - non-family household female householder, living alone; 7 - non-family household: female householder, not living alone
cars	Number of vehicles available	Integer, 0 - zero vehicle; 1 - one vehicle; 2 - two vehicles; 3 - three vehicles; 4 - four vehicles; 5 - five vehicles; 6 - six or more vehicles
race_id	Race code for the household	Integer
age_of_head	Age of the head of household	Integer

Table 4: Synthetic persons file attributes

Field	Description	Scale
household_id	Unique household ID number	Integer, any value
person_id	Unique person ID number	Integer, any value
age	Person’s age in years	Integer, 0 and up
sex	Gender	Integer, 1 - male; 2 - female
esr	Employment status recode	Integer, 0 . N/A (less than 16 years old); 1. Civilian employed, at work; 2. Civilian employed, with a job but not at work; 3. Unemployed; 4. Armed forces, at work; 5. Armed forces, with a job but not at work; 6. Not in labor force
wkhp	Usual hours worked per week past 12 months	Integer, 0. N/A (less than 16 years old/did not work during the past 12 months); 01..98. 1 to 98 usual hours; 99. 99 or more usual hours
wkw	Weeks worked during past 12 months	Integer,0 .N/A (less than 16 years old/did not work during the past 12 months); 1. 50 to 52 weeks worked during past 12 months; 2. 48 to 49 weeks worked during past 12 months; 3. 40 to 47 weeks worked during past 12 months; 4. 27 to 39 weeks worked during past 12 months; 5. 14 to 26 weeks worked during past 12 months; 6. less than 14 weeks worked during past 12 months
schg	Grade level attending	0. N/A (not attending school); 1. Nursery school/preschool; 2. Kindergarten; 3. Grade 1; 4. Grade 2; 5. Grade 3; 6. Grade 4; 7. Grade 5; 8. Grade 6; 9. Grade 7; 10. Grade 8; 11. Grade 9; 12. Grade 10; 13. Grade 11; 14. Grade 12; 15. College undergraduate years (freshman to senior);16. Graduate or professional school beyond a bachelor’s degree
mil	Military service	Integer, b. N/A (less than 17 years old); 1. Now on active duty; 2. On active duty in the past, but not now; 3. Only on active duty for training in Reserves/National Guard; 4. Never served in the military
member_id	Member ID in household	Integer
race_id	Person<92>s race	Integer
naicsp	NAICSP industry code	string code
maz_seqid	Micro-analysis zone of home location	Integer
zone_id	Transportation analysis zone of home location	Integer
relate	Relationship	Integer

There are two land use files in the Data folder with similar attributes. The land_use.csv has MAZ as its unit, while land_use_taz.csv is TAZ-based. The MAZ land use is used by ActivitySim, while the TAZ one is used by TransCAD for skimming and assignment procedures. The table below shows the contents of the land use file.

Table 5: Land use file attributes

Field	Description
MAZ	MAZ identifier number
TAZ	TAZ identifier number
COUNTY	Numeric county identifier; useful for data summaries, possibly destination choice
DISTRICT20	Useful for data summarization
Parking_hourly	Hourly parking cost in dollars
Parking_daily	Daily parking cost in dollars
Parking spaces	Number of available parking spaces in an MAZ
AreaType	Area type designation. 1=CBD; 2=Urban Economic Activity Area; 3=Urban; 4=Suburban; 5=Rural
Univ_Tier	Name of university
Univ_Enrollment	This field should be the enrollment of the university by MAZ; university enrollment should be apportioned to university zones based on sq. footage of buildings and/or parking lots.
tot_acres	Total acres
tot_hhs	Total households
hhs_pop	Household population
grppop	Group quarters population
tot_pop	Total population
K_8	Kindergarten <96> Grade 8 enrollment
G9-12	Grade 9 - 12 enrollment
tot_emp	Total employment
e01_nrm	Natural resources employment
e02_constr	Construction employment
e03_manuf	Manufacturing employment
e04_whole	Wholesale employment
e05_retail	Retail employment
e06_trans	Transportation employment
e07_utility	Utility employment
e08_infor	Information services employment
e09_finan	Financial services employment
e10_pstsvc	Professional science & technical services employment
e11_compmgt	Management of companies and enterprises employment
e12_admsvc	Administrative support and waste services employment
e13_edusvc	Education employment
e14_medfac	Medical facilities employment
e15_hospit	Hospital employment
e16_leisure	Leisure and hospitality employment
e17_othsvc	Other services employment
e18_pubadm	Public Administration employment
TERMINAL	Terminal time in minutes, used for parking access/egress time in CBD for mode choice. Must be estimated.

4.1.2 Network folder

The Network folder contains the highway network and transit route system, highway count file for validation, and assignment loading factors. The Table below shows the contents of the folder in more detail:

Table 6: List of files in the Network folder

File	Description	File.type
CountTable.bin	Count data for highway validation	bin
COUNTS_00_16.dbf	Yearly AADT and AWDT data	dbf
HwyKC20.dbd	Highway network	dbd
RtKC20.rts	Transit route system	rts
SpdCAP_LU.bin	Free-flow speed and capacity of facility types in addition to the loading factors	bin
TURNPRO20.bin	Turn penalty table	bin
V17_SEMCOG_tRoad1.dbd	All-street network; used to create MAZ skims	dbd
Zone_Fare.mtx	Zonal fare matrix currency info, used in transit calculations	mtx
Zones10_2899.bin	TAZ data file including area type, county, and district	bin

4.1.3 Parameters folder

The Parameters folder contains transit and highway-related skimming parameters. The Table below shows the contents of the folder in more detail:

Table 7: List of files in the Parameters folder

File	Description	File.type
ExternalParams.bin	External parameter file to adjust external distances, used in highway skimming	bin
MODETABLE.bin	Transit mode table information, used in transit skimming	bin
ModeXferTable.bin	Transit mode transfer table, used in transit skimming	bin
transitPara_abm.bin	Transit parameters table, used in transit skimming	bin
TTLookup.dbd	Terminal time look up table, used in highway skimming	bin

4.1.4 Zonal_Data folder

The zonal data folder contains TAZ/MAZ geographies and external and airport trip tables. The Table below shows the contents of the folder in more detail:

Table 8: List of files in the SED folder

File	Description	File.type
1.Firms.Rdata	Base Year Firm Synthesis Output Database	Rdata
Airport_STrip_2020.bin	Airport enplanement data	bin
Zones10_2899.dbd	TAZ geography shape	dbd
SEMCOG_MAZ_V1_Draft.dbd	MAZ geography shape d	bd
External_2020EE.bin	External-External OD trip matrices	bin
External_2020IE.bin	EI/IE trip production table to be distributed	bin
base_transcad_taz.csv	Socioeconomic data for the internal zones	csv
CVM_Externals.csv	List of the external stations and an indication of whether they are active	csv
CVM_EE_Region.csv	Growth rates for external to external truck traffic	csv
CVM_IEEI_Region.csv	Growth rates for internal to external and external to internal truck traffic	csv
Facilities.csv	Descriptions of high-intensity freight locations	csv

4.1.5 Visualizer folder

The Visualizer folder contains the script and data needed to create the ABM Visualizer. The table below shows the contents of the folder in more detail:

Table 9: List of files in the Visualizer folder

File	Description	File.type
data folder	containing survey and ActivitySim data to be visualized	NA

4.2 Output files

At a high level, the output folder from the SEMCOG ABM includes:

• ActivitySim-related outputs:

  • Tour and trip files: these ActivitySim outputs include data on all the tours and trips generated from the model including mode, purpose, and time of day bin.

  • Internal OD tables: These outputs are the internal trip OD matrices (by time of day) produced by Activitysim to be used in assignment.

  • ABM visualizer

• CVM-related outputs:

  • CVM OD matrices

  • CVM visualizer

• TransCAD outputs:

  • Highway and transit skims (.mtx and .omx)

  • External and airport OD tables by time of day produced by the trip distribution macro (to be used in assignment).

  • Loaded highway and transit networks

  • Reports

These output files are located within Model_Runs/Scenario_folder/Outputs. The structure of the Output folder is as follows:

Figure 8: SEMCOG ABM output folder Structure

* Output                          Model output folder
  
  + Activitysim                   ActivitySim output files
  
  + CVM                           Commercial Vehicle Model output files
  
  + EXTAirport                    External and airport trip distribution model output                        
  
  + HAssign                       Highway assignment-related outputs
  
  + HNet                          Highway network used for skimming and assignment
  
  + skims                         highway and transit skim files
  
  + TNet                          Transit network used for skimming and assignment
  
  + TrnAssign                     Transit assignment-related outputs
  
  + WorkingFiles                  Exported All street network, MAZ shapefile, 
                                  and transit network system used for 2-zone specific skimmings
  
  + Report files                  TransCAD report files and ABM visualizer    

4.2.1 ActivitySim folder

The ActivitySim folder contains output from running ActivitySim. The Table below shows the contents of the folder in more detail:

Table 10: List of files under ActivitySim output folder

File	Description	File.type
activitysim.log	Model run progress terminal output	log
data_dict.csv	List of variables in each model dataframe	csv
final_accessibility.csv	Accessibility measures created by ActivitySim	csv
final_checkpoints.csv	Land use data at the TAZ level; used by TransCAD skimming	csv
final_households.csv	Synthetic households file with the additional variables created during model run	csv
final_land_use.csv	Land use file with the additional variables created during model run	csv
final_persons.csv	Synthetic persons file with the additional variables created during model run	csv
final_tours.csv	All the tours created by ActivitySim and their attributes	csv
final_trips.csv	All the trips created by ActivitySim and their attributes	csv
final_school_shadow_prices.csv	Final shadow prices for school location choice	csv
final_workplace_shadow_prices.csv	Final shadow prices for workplace location choice	csv
mp_accessibility_i-activitysim.log	Model terminal output per process i for running the accessibility step	log
mp_households_i-activitysim.log	Model terminal per process i for running the model	log
timing_log.csv	Run time for each step	csv
trips_period.omx	Internal OD matrices per period	omx

The final_households.csv table contains all the original synthetic household population in addition to the ones created in ActivitySim. The table below shows the additional attributes of households created by ActivitySim.

Table 11: List of final_households.csv attributes

Field	Description	Scale
hhsize	household size	integer
auto_ownership	auto ownership level	integer
home_zone_id	MAZ ID of home location	integer
TAZ	TAZ ID of home location	integer
sample_rate	household sample rate	float
income	household income	integer
income_in_thousands	household income in thousands	float
income_segment	4-level segmented income: low(<$30K), medium (>$30K, <$60K), high (>$60K, <$100K), very high (>$100K)	integer
median_value_of_time	median household value of time (according to income)	float
hh_value_of_time	household value of time	float
num_workers	number of workers in the household	integer
num_non_workers	number of non-workers in the household	integer
num_drivers	number of drivers in the household	integer
num_adults	number of adults in the household	integer
num_children	number of children in the household	integer
num_young_children	number of young children in the household	integer
num_children_5_to_15	number of children aged 5-15 yrs in the household	integer
num_children_6_to_12	number of children aged 6-12 yrs in the household	integer
num_children_16_to_17	number of children aged 16-17 yrs in the household	integer
num_college_age	number of college age children in the household	integer
num_young_adults	number of young adults in the household	integer
non_family	non-family household	boolean
family	family household	boolean
home_is_urban	home is in urban area	boolean
home_is_rural	home is in rural area	boolean
home_county	county home is located in	string
home_in_detroit	home is in detroit area	boolean
num_predrive_child	number of predriving age children in household	integer
num_nonworker_adults	number of nonworker in adults area	integer
num_fullTime_workers	number of fulltime workers in the household	integer
num_partTime_workers	number partTime in workers in the household	integer
retired_adults_only_hh	households with only retired persons	boolean
hh_work_auto_savings_ratio	time saved driving vs. taking transit to work	float
num_under16_not_at_school	number of under 16 persons not in school in the household	integer
num_travel_active	number of persons who travel in the household (with M or N CDAP pattern)	integer
num_travel_active_adults	number of adults who travel in the household (with M or N CDAP pattern)	integer
num_travel_active_preschoolers	number of preschoolers who travel in the household (with M or N CDAP pattern)	integer
num_travel_active_children	number of children who travel in the household (with M or N CDAP pattern)	integer
num_travel_active_non_preschoolers	number of non-preschoolers who travel in the household (with M or N CDAP pattern)	integer
participates_in_jtf_model	household with joint tours	boolean
joint_tour_frequency	joint tour in frequency of the household	string
num_hh_joint_tours	number joint in tours a household makes	integer

The final_persons.csv table contains all the original synthetic persons population in addition to the ones created in ActivitySim. The table below shows the additional attributes of persons created by ActivitySim.

Table 12: List of final_persons.csv attributes

Field	Description	Scale
age_0_to_5	person’s age is between 0 and 5	boolean
age_6_to_12	person’s age is between 6 and 12	boolean
age_16_to_19	person’s age is between 16 and 20	boolean
age_16_p	person’s age more than 16	boolean
adult	person is an adult	boolean
male	person is male	boolean
female	person is female	boolean
pemploy	employment type	integer
pstudent	student type	integer
ptype	person type category	integer
has_non_worker	person’s household has nonworker	boolean
has_retiree	person’s household has retiree	boolean
has_preschool_kid	person’s household has preschooler	boolean
has_driving_kid	person’s household has driving age child	boolean
has_school_kid	person’s household has school age child	boolean
has_full_time	person’s household has full time worker	boolean
has_part_time	person’s household has part time worker	boolean
has_university	person’s household has a university student	boolean
student_is_employed	person is a student and is employed	boolean
is_student	person is a student	boolean
is_gradeschool	persons is a gradeschooler	boolean
is_highschool	person is a high schooler	boolean
is_university	person is a university student	boolean
school_segment	school segment type (1: gradeschool, 2: highschool, 3: university)	integer
is_worker	person is a worker	boolean
home_zone_id	MAZ ID of home location	integer
hh_child	number of children in the household	integer
PNUM	member ID of person	integer
income	household income	integer
income_in_thousands	household income in thousands	flo
income_segment	4-level segmented income: low(<$30K), medium (>$30K, <$60K), high (>$60K, <$100K), very high (>$100K)	integer
is_fulltime_worker	person is full-time worker	boolean
is_parttime_worker	person is part-time worker	boolean
naicsp_recode	nacisp code with -9 values recoded to 0	integer
industry_naics	high-level naicsp code category (based on first digit)	integer
naics_category	high-level naicsp code category (based on first two digits)	integer
value_of_time	persons’s value of time	float
is_income_less25K	household income <$25K	boolean
is_income_25K_to_60K	household income >$25K & <$60K	boolean
is_income_60K_to_120K	household income >$60K & <$120K	boolean
is_income_greater60K	household income >$60K	boolean
is_income_greater120K	household income >$120K	boolean
is_non_worker_in_HH	persons’s household has a non-worker	boolean
is_all_adults_full_time_workers	all adults are full-time workers in the household	boolean
is_pre_drive_child_in_HH	person’s household has a predriving age child	boolean
has_young_children	person’s household has young children	boolean
has_children_6_to_12	person’s household has children aged between 6 and 12	boolean
home_county	county home is located in	integer
school_zone_id	MAZ ID of school location	integer
distance_to_school	distance in miles to school	float
roundtrip_auto_time_to_school	round trip auto travel time to school	float
original_school_zone_id	original MAZ school zone ID before univ_location_zone_override model	integer
workplace_zone_id	MAZ ID of workplace location	integer
workplace_location_logsum	workplace location logsum	float
distance_to_work	distance in miles to work	float
workplace_in_cbd	person’s workplace zone is in CBD	integer
work_zone_area_type	area type of workplace zone	integer
roundtrip_auto_time_to_work	round trip auto travel time to work	float
work_auto_savings	time saved driving vs. taking transit to work	float
work_auto_savings_ratio	scaled time saved driving vs. taking transit to work (-1,1)	float
umich_student	person is a UM student	boolean
umich_worker	persons works at UM	boolean
dest_hourly_peak_parking_cost	hourly parking cost at destination	float
work_from_home	person works from home	boolean
transit_pass_subsidy	person receives transit subsidy	boolean
transit_pass_ownership	person has transit pass	boolean
free_parking_at_work	person gets free parking at work	boolean
telecommute_frequency	telecommute frequency	integer
cdap_activity	CDAP pattern	integer
travel_active	person travels out of home	boolean
under16_not_at_school	person is under 16 and does not go to school	boolean
has_preschool_kid_at_home	person has preschool kid at home	boolean
has_school_kid_at_home	person has school kid at home	boolean
mandatory_tour_frequency	frquency of manadatory tours	integer
work_and_school_and_worker	persons is a worker and goes to work and school	boolean
work_and_school_and_student	persons is a student and goes to work and school	boolean
num_mand	number of mandatory tours for each person	integer
num_work_tours	number of work tours for each person	integer
has_pre_school_child_with_mandatory	presence of pre school kid with mandatory tours	boolean
has_driving_age_child_with_mandatory	presense of driving age school children with mandatory tours	boolean
num_joint_tours	number of joint tours for each person	integer
non_mandatory_tour_frequency	non-mandatory tours for each person	integer
num_non_mand	number of non mandatory tours	integer
num_escort_tours	number of escort tours	integer
num_eatout_tours	number of eatout tours	integer
num_shop_tours	number of shopping tours	integer
num_maint_tours	number of maintenance tours	integer
num_discr_tours	number of discretionary tours	integer
num_social_tours	number of social tours	integer
num_non_escort_tours	number of non-escort tours	integer
num_shop_maint_tours	number of shopping and maintenance tours	integer
num_shop_maint_escort_tours	number of shopping and maintenance and escort tours	integer
num_add_shop_maint_tours	number of additional shopping and maintenance tours	integer
num_soc_discr_tours	number of social and discretionary tours	integer
num_add_soc_discr_tours	number of additional social and discretionary tours	integer

The final_land_use.csv table contains all the original land use fields in addition to the ones created in ActivitySim. The table below shows the additional land use attributes created by ActivitySim.

Table 13: List of final_land_use.csv attributes

Field	Description	Scale
AE_LOCAL	local transit access/egress distance based on All-street network	float
AE_PRM	premium transit access/egress distance based on All-street network	float
household_density	total household divided by zone area	float
employment_density	total employment divided by zone area	float
density_index	desnity index defined as (household_density * employment_density)/(employment_density + household_density)	float

The final_accessibility.csv table contains all the accessibility measures created in ActivitySim. The table below shows accessibility measures created by ActivitySim.

Table 14: List of final_accessibility.csv attributes

Field	Description	Scale
zone_id	MAZ zone ID	integer
auPkRetail	destination retail accessibility by auto at peak time	float
auPkTotal	destination total accessibility by auto at peak time	float
auOpRetail	destination retail accessibility by auto at off-peak time	float
auOpTotal	destination total accessibility by auto at off-peak time	float
trPkRetail	destination retail accessibility by transit at peak time	float
trPkTotal	destination total accessibility by transit at peak time	float
trPKHH	destination residential accessibility by transit at peak time	float
trOpRetail	destination retail accessibility by transit at off-peak time	float
trOpTotal	destination total accessibility by transit at off-peak time	float
nmRetail	destination retail accessibility by non-motorized modes	float
nmTotal	destination total accessibility by non-motorized modes	float

The final_joint_tour_participants.csv table contains data on the joint tours in ActivitySim. The table below shows these data.

Table 15: List of final_joint_tour_participants.csv attributes

Field	Description	Scale
participant_id	persons ID of participant	integer
tour_id	tour ID	integer
household_id	household ID	integer
person_id	persons ID of participant	integer
participant_num	nuumber of persons on tour	integer

The final_tours.csv table contains all the information on the tours created in ActivitySim. The table below shows the attributes of ActivitySim tours.

Table 16: List of final_tours.csv attributes

Field	Description	Scale
tour_id	Tour ID	integer
person_id	Person id	integer
tour_type	Tour type: work, school, othmaint, social, eatout, shopping, othdiscr, escort, eat, maint, business	string
tour_type_count	Number of tours of tour_type parent has (parent’s max tour_type_num)	integer
tour_type_num	If there are multiple of the same type tours, they will be numbered	integer
tour_num	Index of tour (of any type) for parent tour	integer
tour_count	Number of tours of any type for parent (parent’s max tour_num)	integer
tour_category	Category of tour. One of ‘mandatory’, ‘non_mandatory’, ‘atwork’, or ‘joint’	integer
number_of_participants	Number of participants on a tour	integer
destination	MAZ ID for tour destination	integer
origin	MAZ ID for tour origin	integer
household_id	Household ID of the person making the tour	integer
tdd	ID of the in-outbound bin combination	integer
start	Start half hour bin of tour, ranging 1-48	integer
end	End half hour bin of tour, ranging 1-48	integer
duration	Tour duration in half hour unit	integer
composition	Composition of a joint tour: all adults, all children, mixed	string
destination_logsum	Tour destination logsum	float
tour_mode	Tour mode	string
mode_choice_logsum	Mode choice logsum	float
atwork_subtour_frequency	Frequency of atwork subtours for workers	integer
parent_tour_id	ID of the parent tour if current tour is a subtour	integer
stop_frequency	Number of stops on a tour	integer
primary_purpose	Primary purpose of the tour: work, school, univ, othmaint, social, eatout, shopping, othdiscr, escort, atwork	string
univ_parking_zone_id	Parking zone ID for UM tours.	integer

The final_trips.csv table contains all the information on the trips created in ActivitySim. The table below shows the attributes of ActivitySim trips.

Table 17: List of final_trips.csv attributes

Field	Description	Scale
trip_id	Trip ID	integer
person_id	ID of the person trip belongs to	integer
household_id	ID of the household person belongs to	integer
primary_purpose	Purpose of the tour trip belongs to: work, school, univ, othmaint, social, eatout, shopping, othdiscr, escort, atwork	string
trip_num	Index of trip in the tour	integer
outbound	Outbound trip direction	boolean
trip_count	Number of trips on a tour	integer
destination	MAZ ID for trip destination	integer
origin	MAZ ID for trip origin	integer
tour_id	ID of tour trip belongs to	integer
purpose	trip purpose: othmaint, home, othdiscr, atwork, work, social, eatout, shopping, escort, school, univ, parking	string
destination_logsum	Trip destination logsum	float
original_school_zone_id	School zone ID	integer
parked_at_university	Indicator for a trip an auto trip ending in a university parking	boolean
depart	Departure half hour bin: 1-48	integer
tour_includes_parking	Indicator of a tour that includes parking	boolean
trip_id_pre_parking	ID of the trip before parking occurs	integer
trip_mode	Trip mode	string
mode_choice_logsum	Trip mode choice logsum	float

4.2.2 CVM folder

The main tabular outputs from the CV model for a particular scenario in addition to the CVM dashboard are included in this folder. The output files are either .csv format files or R binary format files (.Rdata) that contain compressed tables. In addition, the CV model adds trip tables to the .omx trip tables in the Output/HAssign folder for the scenario. These outputs are described in more detail in the CVM model documentation.

4.2.3 EXTAirport folder

The EXTAirport folder contains output from running the external and airport trip distribution models. The table below shows the contents of the folder in more detail:

Table 18: List of files under the EXTAirport folder

File	Description	File.type
AIRPORT_period.mtx	Airport OD matrix by period	mtx
AIRPORT_period.omx	Airport OD matrix by period	omx
EI_OD_period.mtx	External-Internal OD matrix by period	mtx
EI_OD_period.omx	External-Internal OD matrix by period	omx
IE_OD_period.mtx	Internal-External OD matrix by period	mtx
IE_OD_period.omx	Internal-External OD matrix by period	omx
PA_AIRPORT.mtx	Airport PA matrix	mtx
PA_EI.mtx	External-Internal PA matrix	mtx
PA_IE.mtx	Internal-External PA matrix	mtx

4.2.4 HAssign folder

The HAssign folder contains output related to running the highway assignment. The Table below shows the contents of the folder in more detail:

Table 19: List of files under the HAssign folder

File	Description	File.type
ASIM_period.omx	Highway-only OD demand matrix by period	omx
EXTAirport_period.omx	Combined airport and external OD matrix by period	omx
OD_period.omx	Total OD demand matrices by period including passenger and freight	omx
Flow_period.bin	Network flows by period as a result of the assignment step	bin
Feedback.txt	Feedback convergence by period	txt
IterLogPERIOD.bin	Assignment convergence per iteration and by period	bin
SelectSummary.bin	Select assignment summary	bin

4.2.5 HNet folder

The HNet folder contains the constructed highway network. The Table below shows the contents of the folder in more detail:

Table 20: List of files under the HAssign folder

File	Description	File.type
semcog_hwy.net	Highway network	net

4.2.6 Skims folder

The skims folder contains highway and transit skim files generated by the TransCAD skimming process. It also contains the skims.omx file, which is the omx file containing all the skim tables and is read in directly by ActivitySim.

4.2.7 TrnAssign folder

The TrnAssign folder contains output related to running the transit assignment. The table below shows the contents of the folder in more detail:

Table 21: List of files under the TrnAssign folder

File	Description	File.type
OD_TRN_period.omx	Transit-only OD demand matrix by period	omx
ONOFF_DY_ALL.bin	Table of boarding and alighting passengers at transit stops, by route	bin
OD_period.omx	Total OD demand matrices by period including passenger and freight	bin
transit_total.csv	Total number of transit trips	csv
WFLOW_DY_ALL.bin	Transit Access/Egress Flows	bin
AFLOW_DY_ALL.bin	Aggregate transit flows by route	bin
TFLOW_DY_ALL.bin	Transit flows by route and from stop to stop	bin

4.2.8 WorkingFiles folder

The WorkingFiles folder contains output from the Export files step to be used in 2-zone specific skimming. The table below shows the contents of the folder in more detail:

Table 22: List of files under the WorkingFiles folder

File	Description	File.type
links_all.shp	All-street network link shapefile	shp
nodes_all.shp	All-street network node shapefile	shp
nodes_net.shp	Highway network node shapefile	shp
links_net.shp	Highway network link shapefile	shp
route_lines.csv	Transit network transit line data	csv
route_stops.csv	Transit network transit stops data	csv
SEMCOG_MAZ_V1_Draft.shp	Microzone shapefile	shp

5 Running the Model

5.1 Introduction

This chapter discusses how to install the SEMCOG ABM and run it. If the user wishes to only run a new scenario on a machine where the model has already been set up, they may refer to the Setting up the Model for Scenario Testing section.

5.2 Hardware Requirements

The SEMCOG ABM runs on a windows machine, with the minimum and recommended system specification as follows:

• Minimum specification:
  • Operating System: 64-bit Windows 7, 64-bit Windows 8 (8.1) or 64-bit Windows 10
  • Processor: 8-core CPU processor
  • Memory: 128 GB RAM
  • Disk space: 150 GB
• Recommended specification:
  • Operating System: 64-bit Windows 7, 64-bit Windows 8 (8.1) or 64-bit Windows 10
  • Processor: Intel CPU Xeon Gold / AMD CPU Threadripper Pro (12+ cores)
  • Memory: 256 GB RAM
  • Disk space: 150 GB

Note that, in general, a higher CPU core count and RAM will result in faster run times.

5.3 Software Requirements and Installation

Two software applications, TransCAD and Anaconda, should be installed on the computer that will be used to run the model.

The overall modeling system is an integrated model that is controlled by and primarily runs in the TransCAD transportation planning software platform produced by Caliper (https://www.caliper.com/tcovu.htm). The ABM uses TransCAD version 8, build 22365. The ABM has a graphical user interface (GUI) programmed in TransCAD’s GISDK scripting language that is used to manage scenarios, start model runs, produce output reports, and run other modeling utilities.

ActivitySim is run through the TransCAD software and is an open-source python package based on Anaconda. Anaconda is a distribution of python (and R) that makes development and package management more straightforward (https://www.anaconda.com/). Required python packages to run ActivitySim is included in an Anaconda environment that should be installed before running the model. Before attempting the guided model installation below, Anaconda needs to be installed on the machine. Any Anaconda version after 2021.04 that comes with python 3.9+ should be installed. The installation process is straightforward by downloading and running the installer (https://www.anaconda.com/download) and following the installation prompts.

5.4 Installing the Model

The model setup steps are as follows:

• Step 1: Clone the SEMCOG_TDM GitHub repository, or copy the provided model zipped folder to the desired directory.

• Step 2: Install ActivitySim

• Step 3: Download Model Inputs from Box

• Step 4: Set up the TransCAD Add-In

5.4.1 Cloning the SEMCOG_TDM GitHub repository

The SEMCOG ABM code is hosted on GitHub and can be retrieved by anyone with proper access. To clone the model code repository, use either a GitHub tool such as GitHub Desktop (download and install from https://desktop.GitHub.com/), or use Git commands.

• If using a GitHub tool such as GitHub Desktop: First use your browser to go to model repository (https://GitHub.com/SEMCOG/SEMCOG_TDM.git), then Find the green Code button, click, and then choose Open with GitHub Desktop.

Figure 9: Using GitHub Desktop to clone model repository

• if using Git terminal: open Git terminal, change directory to your desired location, and use git clone -b develop_2zone.https://GitHub.com/SEMCOG/SEMCOG_TDM.git to clone the repository.

Alternatively, the downloaded zipped model code folder can be used to set up the model as well.

5.4.2 Install ActivitySim

5.4.2.1 Check Anaconda installation directory

Anaconda needs to be installed before setting up ActivitySim. First, check the directory to which Anaconda is installed to on the machine, and if it differs from C:\ProgramData\Anaconda3, update the Anaconda installation directory in the ABM stage of the Parameters tab in the Scenario Editor within the TransCAD Add-In after setting up the Addin Set up the TransCAD Add-in

*Figure 10: Updating Anaconda installation directory in ABM_semcog_abm.bat*

5.4.2.2 Install the Anaconda environment

Before installing the ActivitySim package, the Anaconda environment that contains the other required python packages needs to be installed.

• Open the Anaconda Prompt from the Start menu, and navigate (cd) to the model folder and then SEMCOG_TDM\ABM\Scripts.

• Then, install the ActivitySim environment using the following command: conda env create -f environment.yaml. Following this command, an environment named activitysim is installed.

• To check all the installed environments on a machine, use this command: conda env list. You should be able top see activitysim listed there following the previous step.

• This environment already comes with activitysim version 1.0.4 installed.

• To check the path to which this environment is installed, first activate the environment using conda activate activitysim, and then use echo %CONDA_PREFIX%. If the first portion of the directory of the installed environment (up to the envs\activitysim) differs from where Anaconda is installed, update the ENV_DIR ABM parameter in the TransCAD Add-in as discussed in Set up the TransCAD Add-in. Only use the first portion of the directory up to the envs\activitysim to update this parameter.

The figure below shows an example of how to change directory and install the Anaconda environment. It assumes that the cloned model repository (SEMCOG_TDM) is located under C:\RSG_test.

Figure 11: Installing Anaconda environment for ActivitySim

5.4.3 Install Pandoc

The CVM dashboard creation requires the installation of Pandoc 1.19. To install, go to directory CVM\lib, find the pandoc windows installer, open and follow prompts.

5.4.4 Download Model Inputs from Box

Download or copy the input files, and Unzip (‘extract here’) inside the Scenario Input folder (/SEMCOG_TDM/ABM/Model_Runs/SEMCOG_ABM/Input).

5.4.5 Set up the TransCAD Add-in

Now, set up the TransCAD Add-In in TransCAD using the GIS Developers Kit. Open TransCAD and go to Tools > GIS Developer's Kit > GISDK Toolbar to load the toolbar.

• On the toolbar, click on the Compile to UI button, and compile the files in SEMCOG_TDM/AddIn/rsc into a set of DBD files in SEMCOG_TDM/AddIn. Compile:

  • SEMCOG Helper Utilities.rsc into util_ui.dbd
  • SEMCOG Scenario Manager.rsc into scen_ui.dbd
  • SEMCOG_ActivitySim.rsc into semcog_abm.dbd
  • SEMCOG_Dashboard.rsc into dash_ui.dbd
  • SEMCOG_Interop.lst into interop_ui.dbd
  • SEMCOG_Report.rsc into report_ui.dbd
  • Note: SEMCOG_Interop.lst compiles SEMCOG_AQ.rsc, SEMCOG_AT_Toolbox.rsc, and SEMCOG_EJ.rsc.
    

• Go to Tools > GIS Developer’s Kit > Setup Add-Ins… and click “Add”.

• In Settings, select Dialog Box,

• In Description type “SEMCOG ABM”

• In Name type “SEMCOG Model”

• In UI Database browse to SEMCOG_TDM/AddIn/semcog_abm.dbd

Figure 12: Set up the TransCAD Add-In

• Open the SEMCOG_ABM Addin, and create a new Scenario by clicking on the green plus button.

Figure 13: Set up the TransCAD Add-In

• In the opened window set the Scenario Name: SEMCOG_ABM (user defined, match with the folder name in Model_Runs)

• Set the Input Dir to :SEMCOG_TDM/ABM/Model_Runs/SEMCOG_ABM/Input

• Set the Output Dir to : SEMCOG_TDM/ABM/Model_Runs/SEMCOG_ABM/Output

• In the Input tab, set the batch files to the correct path. By default, TransCAD looks for these files in the Input folder, while the ActivitySim batch files are located under ABM/Script, and the CVM batch file is under CVM.

• In the General tab, set the number of feedback iterations.

• In the Parameters tab:

  • Set BaseScenario to 1 in the INI stage. This parameter makes sure the CVM runs for the base 2020 year.

  • In the ABM stage, set the Anaconda_DIR to where Anaconda is installed. Also set the ENV_DIR to where the environment is installed as discussed in Install the Anaconda environment.

  • In the ABM stage, set BASE_IS_SURVEYto 1 if you want the ABM visualizer to compare model output to survey data. Otherwise, set the value to 0, and set the BASE_SCEN_NAME to the desired base scenario. The base scenario folder with all the input and output files should be present in the Model_runs folder.

  • Click on OK to finish setting up the Scenario.

The model is now set up. Click on Initialization to start the full model run.

6 Working with ActivitySim

This section delves deeper into how ActivitySim runs and how user can configure ActivitySim.

6.1 ActivitySim configs files

The configs files used to run ActivitySim are located under ABM in the model code folder.

Figure 14: SEMCOG ABM configs folders

* ABM                                 ABM directory

  + configs                           ABM configuration files
  + configs_mp                        ABM multiprocessing configuration files

The configs folder contains all the models’ UECs (utility equation calculator) and settings files. The auto ownership model, for example, has three config files:

* auto_ownership configs

  + auto_ownership.csv                  Main model file including all the model variables
                                        and cofficients names           
  + auto_ownership_coefficients.csv     Coefficient file including the value of the coefficients
                                        used in the main file 
  + auto_ownership.yaml                 Model settings defining the model type

The figure below shows the auto ownership main model file auto_ownership.csv. Each row of the file is a model variable, such as num_drivers (number of drivers), and the last five columns show the model alternatives, here being the households with differing number of cars. A new variable can be added to the model by defining it under the Expression column and giving it a Label and Description.

Figure 15: Auto ownership UEC file

The coefficients for a new variable need to be named in the main file, with the associated values set in the coefficients file.

Figure 16: Auto ownership coefficient file

6.2 ActivitySim multiprocessing configs files

ActivitySim can be and is set to run in multiprocessing mode to reduce runtime. The configs_mp folder contains the settings file that set the parameters of the multiprocessing in addition to other model run details and parameters.

* ABM                                 ABM directory
  
  + configs_mp                        ABM multiprocessing configuration files
    - logging.yaml                    yaml file for model logs
    - settings.yaml                   multiprocessing settings file read by activitysim
    - settings_source.yaml            multiprocessing settings file controlled through the batch file;
    - shadow_pricing.yaml             shadow pricing settings

When ActivitySim is called to run through TransCAD, the batch file sets the appropriate sample size per iteration in the settings_source.yaml, and this file then overwrites the settings.yaml with the correct information. The settings.yaml file, which contains the information on sample size, number of processors to use, and model steps and is then read in by ActivitySim.

Therefore, if user is running ActivitySim from TransCAD, and not directly from the command prompt, settings_source.yaml should be edited to change model run specifications. Figures 18-19 below show the contents of the settings.yaml file. In addition, if the user wishes to change the sample size per feedback loop iteration, they need to update the SAMPLE_ITERATION parameter at the top of the ABM\Scripts\run_semcog_abm_activitysim.bat batch file.

The top portion of the settings.yaml is used to set the sample size the model runs with, in addition to multiprocessing settings. As Figure 18 below shows:

• households_sample_size line sets the number of households to run the model with.

• chunk_size line sets the available RAM in the machine to use to run ActivitySim

• num_processes line sets how many CPU physical cores to use to run the model

• chunk_training_mode line sets what mode to run the model in. The options include “training”, and “production”. In training, the model runs once to estimate the best way to allocate memory to run each step, and then saves the information in cache.csv for later runs. The production mode makes use of this information to run the model more efficiently. the next subsection discusses more details on how to run the model in training mode.

Figure 17: configs_mp/settings.yaml (1)

The next portion of the settings file contains the model steps. ActivitySim has the ability to run up to a certain model, or resume after a successfully-run previous step.

• To only run the model up to a certain step, simply comment out (add # at the beginning of the line) all the model steps following that model.

• To resume the model run after a successfully-run previous step, add the name of the step in front of the resume after line.

Figure 18: configs_mp/settings.yaml (2)

6.3 Running ActivitySim in training mode

In general, before running ActivitySim for the first time on a new machine, it needs to be run in training_mode to efficiently handle memory usage. RSG, however, has ran the model in training mode once and has successfully used the cache on different machines. So in general, the provided cache.csv should help run the model on a different server as well.

However, should the model crash with an OutofMemory error on a first attempt on a new machine, ActivitySim should be run in training mode first to generate a new cache.csv file. To do so, change the chunk_training_mode line to training in the settings_source.yaml file, set household_sample_size: 0 and chunk_size to 80% of the available RAM on the machine (value is in bytes, so a value of 200_000_000_000 is equivalent to 200GB). If the skimming steps have already been run, run only the ActivitySim step from the TransCAD AddIn, otherwise run all the model steps preceding to ActivitySim in the TransCAD Add-In as well.

7 Working with Model Outputs

In addition to the outputs described in previous sections, the final outputs of the SEMCOG ActSim model include the loaded highway links and detailed transit boardings at transit stops. The loaded highway links, segmented by time-of-day period, can be found under the Output/HAssign/Flow_period.bin directory. These files include travel time, speed, VMT, and flow (by vehicle type) for each link in the network. The daily transit boardings data may be found under the Output/TrnAssign/ONOFF_DY_ALL.bin directory. This file includes alighting, boarding, and transfer information for each transit route at a specific stop.

7.1 Model reports and summaries

The SEMCOG ABM has several utility reports and visualizers that help with analyzing model inputs and outputs. This section of the User Guide discusses these utility reports and visualizers.

7.1.1 ActivitySim Visualizer

The ActivitySim Visualizer is created to summarize the synthetic population input in addition to all the ActivitySim model outputs. The Visualizer is an html file that can be opened in a web browser without the need to internet access, and consists of five tabs.

• Welcome tab provides general information about the visualizer next to a map of the SEMCOG region overlayed by the TAZ layer.

• Overview tab provides a general summary of the model input and output, such as the person type distribution of the synthetic population and total tours, trips, stops and VMT.

• Long term tab summarizes the model output data from long term models such as auto ownership in addition to work from home and telecommuting frequency distribution.

• Tour level tab summarizes various tour level aspects of the model, including tour frequencies by person type, Daily Activity Patterns, tour time-of-day distributions, tour length distributions, and tour mode choice.

• Trip level tab summarizes various trip level aspects of the model, including stop frequencies, trip distances, trip time of day, and trip mode choice.

The ActivitySim Visualizer may be found under the Model_Runs/Scenario_name/Output directory.

Figure 19: ActivitySim Visualizer

7.1.2 CVM Dashboard

The CVM dashboard (visualizer) is generated by the dashboard component of the CV model. This visualization dashboard summarizes results from the CV model only and is contained in a scenario specific file called ReportDashboard.html. The dashboard is saved in the Output/CVM folder. The dashboard contains multiple tabs that can be accessed from the drop down menus along the top of the dashboard.

For more information on the CVM dashboard, refer to the CVM User Guide.

Figure 20: CVM dashboard

7.1.3 TransCAD report utilities

7.1.4 Summary Report

TransCAD summary report mainly provides assignment summaries and validations and can be run by selecting the Create Report option in the model Add-In. Running the report utility generates SEMCOG_ABM_SummaryDetailed.html in the Output directory and can be opened with a browser without the need to internet access.

Figure 21: TransCAD summary report utility

7.1.5 Air Quality (AQ) report

The Air Quality (AQ) report summarizes key information used for air quality analysis. This report, accessible in the Utilities tab, is run in two steps as show in the Figure below: calculating the HPMS factors, and creating the AQ report.

The input data required to run the AQ report are in Input\AQ directory, and running the report creates a new Output/AQ directory for the report output.

Figure 22: TransCAD AQ report

7.2 Other TransCAD Utility functions

The Utilities tab include a number of other tools which can be accessed from the Other Utilities button.

7.2.1 Remove Progress Bar

This tool will remove the remaining progress bar after a model crash.

7.2.2 Save Feedback Speeds

This tool will copy speeds used in the final iteration of a complete model run with speed feedback onto the input network.

7.2.3 Update Area Type

This tool was used to define area type during the E7 model development. It produces a map that can be edited interactively, and can also perform TAZ and district-based area type calculations based on activity density. Area type calculations can be modified by editing the macro named “CalcZoneAT” in the SEMCOG_AT_Toolbox.rsc script and then re-compiling the edited script into the interop_ui.dbd user interface. To run the AT Toolbox, an integer field named AT2015 must be present on the TAZ geographic file. This field can be updated for the base year when starting the toolbox from a base year scenario.

7.2.4 Count VMT Tool

This tool estimates the regional VMT based on sampling counts. It reads in the Highway, Count table, and annual counts data (located in the Input/Networks folder) in addition to the Daily highway flows (located in the Output/HAssign), and writes out the VMT_Trends.bin file to the Output directory.

8 Setting up the Model for Scenario Testing

Creating and testing scenarios allow for investigating the impacts of a series of input changes in creating alternative modeled futures. This section of the User Guide describes how the user can create a new scenario in TransCAD, and how to change key inputs to the model. This section also discusses the calibration of some models of interest such as work from home or telecommuting frequency to investigate their potential impacts on the model outputs.

8.1 Creating scenarios in TransCAD

The steps to create a new scenario in TransCAD is similar to what was described in Running the model chapter. Following the launch of the SEMCOG model interface in TransCAD (Tools -> Add-Ins -> SEMCOG Model), a list of created scenarios is shown in the top window of the Model Add-In. The row of tools right under the scenario window allows for creating, copying, deleting, or reordering model scenarios. After creating a new scenario, User should follow by going to the Model_Runs directory, and creating a new folder with the same name. Within this new scenario folder, both Input and Output folders should exist. In addition, User should remember to copy the cache.csv file from a previous scenario to the Output/ActivitySim/cache directory in the new scenario folder.

Figure 23: Creating new scenarios in TransCAD

Figure 24: Creating a new scenarios should be followed by creating a folder with a similar name Under Model_runs directory

8.2 Changing model input data

The Input folder under the Model_run/Scenario_name directory contains all of the model input data (with the exception of the CVM common input data which is located under the CVM directory). Based on the scenario description, the model user can change the data in the relevant folders.

8.2.1 Changing network data

Changing the highway or transit networks requires modifying the HwyKC20.dbd or RtKC20.rts files located under the Input/Networks directory in TransCAD. These changes can include adding/deleting highway links and modifying their attributes or modifying transit routes and their headway.

Highway network physical editing in TransCAD can be done through Tools -> Editing menu. For transit network physical edits, the user first needs to enable the Route Systems menu under the Procedures menu (if not already enabled), and then use Editing Toolbox under the Route Systems menu to edit the network. Modifying network attributes can be done directly from the Dataview for each network.

8.2.2 Changing land use data and synthetic population

The land use and synthetic population (households and persons) data are located under the Input/Data directory. Any land use changes, such as in zonal employment, or synthetic population changes, such as in households’ income, can be done by opening the respective files in a csv editor (e.g. Microsoft Excel) and modifying the relevant fields. The model user should be sure to not change the attribute names, however. In addition, note that changes to the number of households in the land-use file should be reflected in the synthetic population and this is not done internally in the model - it needs to be done in coordination with SEMCOG staff.

8.2.3 Calibrating ActivitySim models of interest / changing model constants

Although it is generally not advisable to change model UECs independently, model user may modify some ActivitySim models of interest in order to see the impact of changing certain attributes not included in the input data. Such attributes may include auto ownership, tour and trip mode choice, work-from-home share and telecommuting frequency. All these calibrations are essentially based on adding calibration constants to the model-of-choice specification file. Below, we discuss an example of telecommute frequency calibration in more detail.

To change telecommuting frequencies in the model, model user can calibrate the model to the desired population shares by adding alternative specific constants to the UECs. The process to calibrate telecommute frequency is automated using a Jupyter Notebook script. The script reads in the telecommute frequency model specification and coefficient files (ABM/confgis/telecommute_frequency.csv and ABM/confgis/telecommute_frequency_coeff.csv, respectively), and calculates the calibration constants for each alternative using Ln(target_count/model_count) formula and based on the provided targets. These constants are then added as new rows to the model specification file. The script, then, runs a set number of iterations until convergence is met.

Figure 25: Adding calibration constants to telecommute frequency model specification

In addition, ActivitySim uses a series of constants and factors stored in ABM/configs/constants.yaml. These constants include transit pass discount factors (used in the mode choice models to compute appropriate transit fare discounts), auto driving cost per mile (18.29 cents for drive alone), and maximum allowable walk distances to access/egress transit stops (0.85mile for local transit and 1.2miles for premium, based on the survey data analysis). Model user can open the constants file in a general text editor and change the constants as needed.

Table 23: Transit pass discount factors located in the ABM/configs/constants.yaml directory

Person.type	DDOT	SMART	AAATA	UM	Other
Full-time worker	0.74	0.65	0.08	0	0.34
Part-time worker	0.73	0.54	0.16	0	0.60
College student	0.68	0.61	0.02	0	0.35
Non-worker	0.67	0.58	0.25	0	0.68
Retiree	0.36	0.15	0.05	0	0.25
Driving-age student	0.44	0.21	0.12	0	0.75
Non-driving age student	0.42	0.12	0.17	0	0.84