VE State Development History
The VE-State approach of developing VisionEval modules that work with modules already developed for VE-RSPM (implementing the GreenSTEP statewide model in the VisionEval model system) is described in this Detailed Approach. The entries below report on the 2018 development status of VE-State at significant development milestones. Each item had a corresponding project issue where reviewers provided comments.
Most of the VE-RSPM code should work with VE-State unless there are errors in the coding which don't allow a module or modules to work with multiple Mareas or Azones. The VE-RSPM modules were developed with test inputs having just one Azone and one Marea. The purpose of this task is to test VE-RSPM with multiple Azones and Mareas, to identify problematic code, and to correct the code so that it will run. This task has been completed. The test and modifications to VE-RSPM modules are in the develop branch of the VisionEval GitHub repository.
Test datasets were developed by duplicating the RVMPO datasets that were used to test VE-RSPM. These datasets have one Azone, named RVMPO, and one Marea, also named RVMPO. The duplicate Azones are named RVMPOA, RVMPOB, and RVMPOC. The duplicate Mareas are named RVMPOX and RVMPOY. Azones RVMPOA and RVMPOB are associated with RVMPOX while the RVMPOC Azone is associated with the RVMPOY Marea. The Bzones in each Azone were duplicated as well and named (using A, B, C) to associate them with Azones. The Bzone centroid locations for the duplicated Bzones are offset in latitude so that they don't overlap. These test data are located in the Test2 directory of the VERSPM directory. The 'revise_inputs.R' script in the directory is used to create the multi-Azone, multi-Marea datasets.
VE-RSPM was run first for the base year and then for both the base year and future year to identify issues. Issues with a few modules were identified and corrected. Following are problems that were identified and corrected:
-
CalculateBaseRoadDvmt module in the VETravelPerformance package - The ComSvcDvmtHhDvmtFactor is applied by Marea but had only one entry. The calculations were corrected so there is an entry for each Marea.
-
CalculateFutureRoadDvmt module in the VETravelPerformance package - The procedures for calculating commercial service DVMT and heavy truck DVMT by Marea were not properly vectorized. Changes were made to vectorize.
-
CalculateComEnergyAndEmissions module in the VETravelPerformance package - A single value of heavy truck ecodrive factor for rural portions of Mareas is needed but multiple values were provided. This was corrected by calculating a weighted average value.
-
CalculatePTranEnergyAndEmissions module in the VETravelPerformance package - Code to calculate DVMT by Marea and powertrain type wrongly multiplied DVMT by Marea over the wrong dimention of the DVMT proportions matrix by Marea and powertrain type. This was corrected.
With the corrections, the multi-Azone, multi-Marea tests run successfully.
Bzone Synthesis: Synthesizing Zones with Activity Density, Diversity, and Destination Accessibility Characteristics
NOTE: THE DOCUMENTATION REFERRED TO IN THE STATUS REPORT HAS BEEN REPLACED. A COPY HAS BEEN RETAINED IN THE INST/MODULE_DOCS DIRECTORY OF THE VESIMLANDUSE MODULE. PLEASE REFER TO DOCUMENTATION EXPLAINED IN NEXT STATUS UPDATE FOR CURRENT DOCUMENTATION Methods have been developed for synthesizing Bzones in urbanized areas, allocating the numbers of households and jobs in each, and attributing each with activity density, diversity, and destination accessibility characteristics. Documentation of the methods is included in a new VESimHouseholds directory of the modules directory in the develop branch. Here is the link. I have opened an issue #204 that you can use to comment on the method.
VE-State is still in a development stage with work yet to be completed on developing and testing Bzone synthesis modules in the VESimLandUse package. Following are changes. Note that these changes are in the develop branch of the repository.
A standardized approach to module documentation has been developed and a documentModule function has been added to the visioneval package to support it. Module documentation is included as a commented block of markdown text at the head of the source file. The block is delineated by <doc> and </doc> tags. Special tags can also be embedded to load text, tables, and figures for documentation. These are saved in the model estimation part of the script. For example the summary statistics for a regression model can be saved as text. These can then be embedded in the documentation. A call to the documentModule function is placed near the bottom of the module script. When the script is run, the function reads in the documentation block and also the module specifications. From the specifications it creates tables documenting all the module inputs, datasets the module requests from the datastore, and datasets the module produces. The module documentation and all resources like image files that are inserted are saved to the inst/module_docs directory of the package.
Documentation has been added for all the VE-RSPM and VE-State modules except for those in the VETravelPerformance package. The easiest way to read the documentation is to do so on GitHub. Navigate to the package of interest in the develop branch of the repository. The documentation is in the inst/module_docs directory. For example, following is the location for documentation of modules in the VESimHouseholds package:
https://github.com/VisionEval/VisionEval/tree/master/sources/modules/VESimHouseholds/inst/module_docs
There is a documentation file for each module in the package. The module documentation file name is the module name with as .md suffix. Click on this and GitHub will show the documentation neatly formatted with embedded text, tables and figures.
VE-RSPM used the DevType data item (Urban, Rural) in a number of modules. This didn't line up with what is being done in VE-State and would not allow modules developed for VE-RSPM to work with VE-State. What is termed DevType (development type) needs to be called LocType (location type) to be consistent with place type terminology. LocType was added throughout the code (hasn't been done yet in VETravelPerformance package yet) to make consistent. LocType has 3 types: Urban, Town, Rural.
The data for estimating the models for synthesizing Bzones is large and time intensive to produce. Because of this, the process of aggregating and processing the data have be relegated to its own package. You can read the documentation at the following link: https://github.com/visioneval/VisionEval/blob/master/sources/modules/VESimLandUseData/inst/module_docs/MakeSimBzoneEstDataset.md
The Bzone synthesis process is quite involved and is informed by a number of models that are estimated from the dataset described above. The CreateSimBzoneModels module estimates and documents these models. You can read the documentation at the following link:
https://github.com/visioneval/VisionEval/blob/master/sources/modules/VESimLandUse/inst/module_docs/CreateSimBzoneModels.md
It is possible that the models for allocating employment to sectors (retail, service, other) may be dropped. Employment by sector is only used for the purpose of calculating an entropy measure of land use mixing. It has proven challenging to write a function to implement these models that won't come across some conditions that cause failure. Since the only purpose of this process is to calculate an entropy measure, it may be easier and more failure proof to calculate the entropy measure for the model estimation dataset and then estimate a model to calculate the entropy measure.
The VisionEval system uses Initialize modules to do extra checks for input data when needed so that input errors are caught before a model is run to avoid failures and cryptic error messages due to unacceptable data. An Initialize module has been developed to check the Bzone synthesis inputs to check that proportions add up to 1.
Some additional needed checks have been identified:
- Check that proportions of urbanized area jobs add up to 1 across the urbanized proportions of Azones in the Marea
- Check that area inputs for Towns and Urban LocTypes are consistent with the activity in those types to avoid situations where the resulting density is too high or too low to be reasonable (and to avoid failure of the density distribution model)
A module has been developed for synthesizing Bzones. This module creates SimBzones for all Azones. These SimBzones have the following attributes:
- Activity density value (households and jobs per acre)
- Activity density level
- Land use mixing level
- Number of households
- Number of jobs
- Destination accessibility value
- Destination accessibility level
- Location type
- Area type
- Development type
The functions for carrying this out have been developed and tested using the Oregon dataset. Additional documentation and specifications are needed to complete the module.
Test inputs have been created using Oregon data to run the modules in the VESimHouseholds package and the modules in the VESimLandUse package (described above). Tests have been run on these modules and all run successfully.
A new module test setup has been developed. Previously, the datastore, inputs, and definitions files to test a package were all contained in the tests directory of the package. This caused the following problems:
- Excess storage. There is a lot of data redundancy in the datastores when each package contains the datastore its module needs. This would be a big problem for testing VE-State which has a lot of data.
- Difficult to test for alternate models. This has shown up in testing RSPM and RPAT models. A lot of steps are needed to avoid naming conflicts. Including VE-State into the mix would add more complexity.
- Difficult to add regression testing in future. This requires a central place for definition and input files and datastore.
The new system puts the test resources and outputs (defs, inputs, datastore) in a central Test_Data directory in the modules directory. There are subdirectories for each model (has to be done for RPAT). There are some new test functions and test script. In the new testing, the resources are copied to the tests directory of the package, the tests are performed, and then the results are copied back to the central repository. Each model has it's own test script. This enables testing for multiple models to be accommodated.
All the VE-State inputs to date are in the Test_Data/VE-State directory. As work progresses on VE-State, this is how testing will be handled. Conversion of VE-RSPM testing is yet to be done.
Modules in the VETravelPerformance package were reworked to support VE-State. In addition, documentation was added for all modules. The framework code was changed to support 'soft' references to modules that are called and datasets that are loaded from other packages.
Documentation in the standard module documentation format developed for VE has been added to all the modules. This is an important addition because several of the modules are complex and would be difficult to understand without documentation. in the source package this documentation is contained in the 'inst/module_docs' directory. In the installed package it is in the 'module_docs' directory of the package. All of the documentation files are in markdown format. The name of a module documentation file is the name of the module concatenated with the '.md' suffix.
A new 'CalculateRoadDvmt' module replaces the 'CalculateBaseRoadDvmt' and 'CalculateFutureRoadDvmt' modules. The new module checks whether the model is being run for the base or 'future' year and performs the appropriate calculations. This this will make it easier for users to set up a model run script. Also, the 'CalculateFutureRoadDvmt' name can add to confusion because the model can be run for past years as well. For example, the Oregon DOT runs the model for 1990 because the basis for Oregon's GHG reduction goals is 1990.
Code in several modules was changed in several places to recognize and respond to the "None" marea name. VE code requires all azones to have an associated marea, even for azones that do not include an urbanized area. The marea name for azones that don't include an urbanized area must be "None". The code uses this name to determine what calculations to perform and what values to expect. For example, when the marea is "None" then the values of "LocType" will only be "Rural" or "Town" and the urban area congestion model will not be run.
The structure of some of the input files were changed and additions to data checks were made. The key DVMT input files are the 'region_base_year_dvmt.csv' and 'marea_base_year_dmvt.csv' files. The 'region_base_year_dvmt.csv' file is used to identify a state (by postal code), the basis for growing heavy truck DVMT (population or income), a base year region total DVMT, and the basis for growing commercial service vehicle (i.e. commercial light-duty vehicle) DVMT (household DVMT, population, or income). The 'marea_base_year_dvmt. csv' file is used to identify an urbanized area name (must be consistent with list, see Initialize module documentation), the light-duty vehicle DVMT on urbanized area roads, and the heavy truck DVMT on urbanized area roads. The modules offer several alternatives for calculating roadway DVMT to support VE-State and VE-RSPM modules. For the region heavy truck DVMT, the user can specify a value or may specify the state. In the latter case, the model will use data from Highway Statistics (per capita values) to calculate a base year region heavy truck DVMT from the base year population and the per capita value. In the case of a VE-RSPM model, it is better not to use the state per capita heavy truck value because that may be unrepresentative. The region value should be input or if it is not, the value is calculated from the marea values. The marea values may be input, or alternately the name(s) of urbanized areas corresponding to the marea(s) are provided. If an urbanized area name is provided, per capita values calculated from Highway Statistics are used. The documentation for the 'Initialize' module lists all the urbanized areas for which data area included.
The modules recognize rural speeds and congestion as well as urban speeds and congestion. For each household, the average speed and congestion effects are determined by the proportions of their DVMT that are on rural and urban roads. The 'CalculateRoadDvmt' module has a very simple function for doing this. Refer to the module documentation for more information.
The VE framework code has been modified to enable 'soft' references in addition to 'hard' references to modules and package datasets. At times it is necessary for a module to call another module or to use a dataset from a different package to do some calculations. Previously module calls (identified in Call specifications) accessing package datasets had to have 'hard' references. The module call or package dataset had to be reference by package and module (or dataset name) using the standard R syntax 'PackageName::ModuleName' or 'PackageName::DatsetName'. This causes problems for referring to different packages that contain the modules or datasets. For example, the user may have different VEPowertrainsAndFuels packages for different vehicle powertrain scenarios (e.g. ZEV standards vs. CAFE standards). With hard referencing, there can only be a VEPowertainsAndFuels scenario. With soft referencing, the module only needs to reference the module name or the dataset name. The visioneval code finds the package which contains the module/dataset in the list of packages used in the model. This list is included in the 'RequiredVEPackages' parameter in the 'run_parameters.json' file. Now users can have as many different VEPowertrainsAndFuels packages as they want to represent different vehicle powertrain futures. For example, ODOT has a VEPowertrainsAndFuelsAP20180302 package as a business-as-usual scenario and a VEPowertrainsAndFuelsSTSRec2017 package as an alternative which assumes more adoption of advanced vehicle powertrains. Switching to 'soft' references enables users to maintain different versions of packages and makes it easier for module developers to create improved versions of packages that will work with the VE model system.
All the modules for VE-State have been completed and tested. Three packages have been created to house the modules that are used in VE-State instead of the modules used in VE-RSPM.
-
The VESimLandUseData package joins Smart Location Database, Census, and National Transit Database data and sets it up to be used in model estimation. Documentation of the models is here.
-
The VESimLandUse package contains the following modules that synthesize Bzones from Azone and Marea characteristics and attribute them with a variety of characteristics. The model estimations are contained and documented in the CreateSimBzoneModels.R script. Documentation of the models starts here. Other modules in the package are:
- CreateSimBzones
- SimulateHousing
- SimulateEmployment
- Simulate4DMeasures
- SimulateUrbanMixMeasure
- AssignCarSvcAvailability
- AssignDemandManagement
- AssignParkingRestrictions
-
The VESimTransportSupply is almost a copy of the VETransportSupply. The difference is that the Bzone transit accessibility measure is modeled rather than an input. Documentation of the models ishere. and here.
The VE-State code now resides in the master branch of the repository. It will be merged into the develop and master branches.
A VE-State model has been created and tested that it runs successfully. An installer is available VisionEval download page. Note: The pilot test dataset was mocked-up and should not be used beyond the tests for this project.
Documentation of VE-State inputs includes:
- VE-RSPM Quick Schematic (short handout on VE-RSPM steps; applies to VE-State with minor differences)
- File Summary (non-Bzone VE-RSPM files are typically inputs for both models VE-State specific files are included at the end,)
- VE-State Inputs by geography (quick summary, insightful to contrast with VE-RSPM list)
- The March 2019 Training Notes covers key points about VE-RSPM methods and inputs (household, car service, light and heavy duty freight). In particular, it summarizes key VE-RSPM changes relative to GreenSTEP code (Section 2) and approach to Calibration & Validation (Section 10).
Potential Future VE-State Updates:
- VE-State Tutorials/Training plan. Develop VE-State Tutorials, as extension of VE-RSPM with broader geography and different/more simple inputs. Include list of inputs/outputs. Provide guidance on data sources, best practices, and defaults, where possible. Plan & execute VE-State training. Case studies of state applications (including real-world input files) noting what policy Qs were answered, how the models are supported and maintained within the agency. A better explanation of the various geography definitions with examples (Azone, Bzone, Marea, LocType, place type - area & development types, region), including a complex area with multiple interacting Mareas.
- Testing. Successful real-world application of VE-State covering a range of Marea conditions (e.g., test in smaller urban areas, in addition to the 9 larger areas documented), and sensitivity tests compared to literature review expectations. Test if GreenSTEP income-auto-ownership relationship issues that MdDOT found, is improved under improved VE-State methods (see discussion here).
Tool Integration.
- Develop Place Types tool (PlaceTypes_USA utilizing blockgroup-based 2010 EPA SLD dataset) to assist with land use inputs and scenarios, as well as envisioning other relevant policy actions (e.g., parking coverage).
- Facilitate linking VisionEval with agency's existing synthetic population datasets (base & future year)(eg. create a VEPopGenImporter module)
- Apply VE-State simBzone code to create RPAT bzone geography to make RPAT fully modular with the other VE Tools. Capture expanded VE-RPAT functionality (e.g., safety metrics, broader TDM inputs)
- Implement EERPAT in VE-State and capture expanded EERPAT functionality (eg. commodity flow/FAF forecasts)
- Code.
- Consider merging VESimTransportSupply with VETransportSupply; This would allow VE-RSPM models to simulate transit accessibility if more detail was provided. This would however require some other changes to the VELandUse package; notably assigning development types and area types to Bzones.
- In simBzone methods, Marea controls could be shifted to Azone controls if fit to SLD data was found to be better. Such efforts are facilitated by the availability of the VESimLandUseData package.
- In the future VE-RSPM upgrade to multi-model model, any considerations needed for VE-State use of those modules should be considered.
Method/Input updates.
- Input Detail. Identify and allow more detailed VE-RSPM inputs where agencies have available statewide data (e.g., transit accessibility average by MArea, employment forecast by type).
- Intercity Commute. VE-State randomly assigns workers to jobs within their Azone (VE-RSPM uses gravity model) for rural or town jobs, as well as to other Azones in the Marea for urban jobs. Might consider 'outOfAzone' if can provide commute distances (e.g. LEHD). Might consider using place types to better relate job location to residence location.
- Diversity. Estimation of activity diversity as a function of density was the weakest of the VE-State simLandUse estimated D values. Consider alternative methods or additional inputs to improve this calculation.
- TransitD. Current VE-State code scales transit accessibility to be in-line with regional transit levels (see here). This is important for input consistency, but locks the scenario into the historical mix of coverage vs. frequency. Future upgrades could seek a way to enable users to change that mix while still remaining consistent with regional service levels.
- DesignD. More guidance on the user input of adjustments to 2010 DesignD average could be developed (see here), including values of different metropolitan areas, and/or sensitivity testing of the impact of this measure.
The VE-State pilot project is now closed. A special thank you to our Oversight Team for keeping with us in this VE-State Pilot project. The Team was represented by staff from FHWA (EERPAT & VE Pooled fund), Volpe, Oregon DOT, Maryland DOT/Baltimore Met Council, WSDOT, Cambridge Systematics, RSG, and Oregon Systems Analytics.
- Getting Started
- VisionEval Primer
- Concepts Primer
- VisionEval Models
- VERPAT Tutorial
- VERSPM Tutorial
- VE-RSPM Training
- VE-State Tutorial
- Developer Orientation