Getting Started v2
The VisionEval strategic modeling system allows rapid evaluation of land use and transportation scenarios to support scenario planning, and to develop strategies to manage transportation system performance.
Configuring and running VisionEval scenarios is simpler and faster than using traditional travel demand models, and more flexible and detailed than using traditional spreadsheet sketch models. While VisionEval outputs are limited in spatial resolution, the system is very detailed in its analysis of demographics and behavioral responses to a variety of transportation policies and system improvements (captured in a broad range of computed performance metrics).
More detailed information on how VisionEval works and what it can do is contained in the Concepts Primer.
The remainder of this document explains the mechanics of VisionEval: how to install it, and what to do with it after it is installed.
VisionEval runs within the R Statistical Environment on any system for which R is available. There are two paths to installing VisionEval:
-
Install from stand-alone Windows installer:
- Download a zipped folder from the VisionEval website for a specific version of R.
This is the simplest way to quickly get VisionEval on your computer. You will first need to install
- R, at least version 4.0.x, and
- RStudio (a widely-used platform-independent R Visual Environment)
- Copy, clone or 'fork' the system code repository
-
If you area a Mac/Linux user, or if you are interested in contributing to the development of VisionEval modules, models, framework, or visualizer, choose this path.
The current release is hosted at VisionEval on **Github**. Development releases are available at VisionEval-dev. Once you have downloaded or cloned one of the VisionEval repositories, instructions for building a runtime are found in
build/Building.md(or you can locate that file in the repository).
You will need:
Once you have R and RStudio installed, you can retrieve the VisionEval installer itself:
Note: 530 Mb download! Packaged for R 4.0.3
The link above will download a .zip file containing the following:
- The VisionEval framework code
- Sample models including VE-RSPM, VE-RPAT, VE-State and VE-ScenarioViewer
- All necessary R packages
- Documentation (this Getting Started document)
See this page for eventually for other R versions (3.6.1 - 4.0.3) and other operating systems.
After installing R 4.0.3 (or the version of R corresponding to the installer you are retrieving) and RStudio, unzip the VisionEval installer into an empty destination folder of your choice.
To complete the installation and start VisionEval, do this: 1. navigate to the folder into which you unzipped the installer: 2. Double-click
**VisionEval.Rproj**
RStudio will start, and the VisionEval will load. You should see this message:
Loading VisionEval for R 4.0.3
Welcome to VisionEval!
If the VisionEval.Rproj file does not open RStudio when you double-click it,
you can start RStudio directly, then choose File / Open Project... and get
to the same place. By default, RStudio remembers the project you last loaded,
so having done that once you should get back to VisionEval each time you start
RStudio (unless you work on a different project).
If you need to start VisionEval manually for some reason, just start RStudio (or even plain R), change into your installation folder using
- RStudio's
Session / Set Working Directory...menu option, or - In plain R, the
File / Change dir...menu option orsetwdcommand.
Then run this instruction to start VisionEval:
source("VisionEval.R")
VisionEval models and the underlying software framework are written in the R programming language for statistical computing and graphics. The purpose of the model system and framework is to enable models be created in a plug-and-play fashion from modules that are distributed as R packages. A simple R script is used to implement a model by initializing the model environment and then calling modules successively. Scenarios are then constructed through a set of files that provide variant model inputs for evaluation and comparison.
To use VisionEval to evaluate scenarios, there are several elements that users need to set up:
-
Select one of the VisionEval models, customizing it as needed:
- VERSPM – Regional Strategic Planning Model
- VERPAT – Rapid Policy Analysis Tool
- VE-State – VisionEval State-Level Model
Instructions and tutorials for configuring these models are presented in the VisionEval Wiki, which is your entry point to a wealth of documentation on the VisionEval models.
Tutorials for each model are available as well, refer to the visioneval.org site for details.
-
Develop a Base Scenario for the region under analysis. The Base Scenario specifies:
- Model Geography (zone structure), reported as Marea (metropolitan area), AZones (county-sized), and BZones (census-tract-sized)
- Base and Future Years to be evaluated for each scenario (e.g. 2015 and 2040)
- Local Data Files describing Base Scenario conditions in the region (including both observed base year data, and estimates of future year conditions with no scenario policies applied)
-
Develop variant Future Actions and Scenarios, by adjusting specific input elements for the Future Years. The
VEScenariosub-system (described for VERPAT, but available for any of the VisionEval models) contains functions to help build and run scenarios composed of combinations of future actions. -
Run the scenarios, either manually, or using the
VEScenariosub-system -
Extract the results for summarization and further analysis in R or export tabular data files to other data analysis systems.
As described in the model tutorials on the Wiki, a VisionEval Scenario contains the following components:
- The model intialization and description file,
run_model.R - Global parameters in the
/defsfolder - Scenario Input data in the
/inputsfolder
The documentation on the Wiki for each model describes what needs to go into the input files and configuration options, which of the default scenario files you need to change for your model area, and where to obtain the data you need.
VisionEval includes simple R command-line instructions for running
models and their outputs. Once you have received the
Welcome to VisionEval! message, you can perform these operations from the R console (either in R or RStudio):
To list the available models (including those you may create as described below, provided you put them in the standard place), do this:
dir("models")
You'll see a list of available models:
[1] "VE-State" "VE-State-Staged" "VERPAT" "VERPAT_Scenarios"
[5] "VERSPM" "VERSPM_MM" "VERSPM_Scenarios"
To open a model from that list, just do this (remember to save the
result into an R variable, using the assignment operator <- ):
rspm <- openModel("VERSPM")
The resulting R object rspm now lets you work with the VERSPM model
and its sample scenario. You can customize the inputs to the VERSPM
model (in the "models/VERSPM" directory), or you can use this command to
copy the model and test scenario into a new model directory (which we
are calling MY-RSPM):
myrspm <- rspm$copy("MY-RSPM")
After you run that, VisionEval will tell you the directory that contains the copy of the model and its test scenario (the exact directory will depend on your Windows user account and where you installed VisionEval):
"C:/Users/MyVisionEval/Documents/VisionEval/models/MY-RSPM"
You can run the sample scenario like this:
myrspm$run()
The model will give you progress updates as it runs:
Running model stage:
C:/Users/MyVisionEval/Documents/VisionEval/models/MY-RSPM
run_model.R: script entered
run_model.R: library visioneval loaded
[1] "2021-02-04 10:50:20 -- Initializing Model. This may take a while."
[1] "2021-02-04 10:50:41 -- Model successfully initialized."
run_model.R: initializeModel completed
[1] "2021-02-04 10:50:41 -- Starting module 'CreateHouseholds' for year '2010'."
[1] "2021-02-04 10:50:44 -- Finish module 'CreateHouseholds' for year '2010'."
...
[... More messages ... ]
...
[1] "2021-02-04 10:56:13 -- Starting module 'CalculatePtranEnergyAndEmissions' for year '2038'."
[1] "2021-02-04 10:56:15 -- Finish module 'CalculatePtranEnergyAndEmissions' for year '2038'."
run_model.R: run complete.
Model stage C:/Users/MyVisionEval/Documents/VisionEval/models/VERSPM complete
Model Stage: /models/MY-RSPM
Status: Complete
If errors are reported and you would like to see the log, you can open this file from RStudio's file pane (in the directory in which your model scenario is located):
"C:/Users/MyVisionEval/Documents/VisionEval/models/MY-RSPM/Log_2021-02-04_10_50_20..txt"
where the year-day-month_hour_minute_second will be the date and time that the model run
started (what you see next to the "Initializing Model" message).
Extracting information from a completed model run should be done with the VisionEval command line interface. First, make sure your model has run to completion, for example by doing this:
myrspm <- openModel("MY-RSPM")
myrspm$status
[1] "Complete"
If it doesn't say "Complete", please review the instructions above for setting up and running a scenario.
Outputs from VisionEval are saved in the scenario "Datastore", which may be an HDF5 file, or a directory hierarchy containing saved R objects. The default model scenarios all use R object storage. Both of the output file formats are complex and difficult to manipulate manually, so you should use the VisionEval command line interface.
The Datastore is organized hierarchically into "Groups" and "Tables", with each Table containing "Fields" (a.k.a. "Datasets"), each of which is a vector of values organized by model geography, household ID or vehicle ID. You can list the available Groups by doing this:
myrspm$groups
Group Stage Selected
1 2010 1 Yes
2 Global 1 Yes
3 2038 1 Yes
You can list Tables by doing this:
myrspm$tables
Group Table Stage Selected
1 2010 Azone 1 Yes
2 2010 Household 1 Yes
3 2010 Bzone 1 Yes
4 2010 Worker 1 Yes
5 2010 Marea 1 Yes
6 2010 Vehicle 1 Yes
7 2010 Region 1 Yes
8 Global Region 1 Yes
9 Global Marea 1 Yes
10 2038 Azone 1 Yes
11 2038 Household 1 Yes
12 2038 Bzone 1 Yes
13 2038 Worker 1 Yes
14 2038 Marea 1 Yes
15 2038 Vehicle 1 Yes
16 2038 Region 1 Yes
You can get the available Fields in all the tables by doing this:
flds <- myrspm$fields
We have in this example saved the result (an R data.frame) into a variable, since it has a lot of rows (the default RSPM model and scenario geography generates 473 rows). You can inspect that using R data.frame operations, or you can save it out to an external comma-separated values (CSV) file like this:
write.csv(flds, file = "Field-List.csv")
Alternatively, you can use the list function to filter the list of fields and select appropriate
ones. The following command will get the names of all the fields that have been selected (that is, they are
present in at least one selected group + table):
myrspm$list()
But mostly you'll use the list with a pattern, like this:
myrspm$list(pattern="Dvmt")
That will show you the names of all the fields that contain "Dvmt". Then you can select just those fields by doing this:
myrspm$fields <- myrspm$list(pattern="Dvmt")
If you want to get a complete view of the fields you now have selected for extraction, you can do this:
myrspm$list(index=TRUE)
Once you have figured out which groups, tables and fields you're interested in, you can extract them. Remember that if you don't select anything, you will get the entire datastore, which might be pretty big!
To extract data from a scenario Datastore, you can execute this instruction:
myrspm$extract()
Extracting data for Table Azone in Group 2010
Extracting data for Table Bzone in Group 2010
Extracting data for Table Household in Group 2010
Extracting data for Table Marea in Group 2010
[... More "Extracting Data" messages ...]
Extracting data for Table Region in Group Global
Write output file: /models/MY-RSPM/output/Azone_2010_1_2021-02-04_143854.csv
Write output file: /models/MY-RSPM/output/Bzone_2010_1_2021-02-04_143854.csv
Write output file: /models/MY-RSPM/output/Household_2010_1_2021-02-04_143854.csv
[... More "Write output file" messages ...]
Write output file: /models/MY-RSPM/output/Region_Global_1_2021-02-04_143854.csv
That will create a directory called output adjacent to the scenario inputs folder where it will
write one comma-separated file for each Table, naming the files after the Group, Table and the date
and time at which the model was run (NOT the date and time at which the data was extracted). If
you perform the extract, you can verify that all the expected files are there with this command:
dir("models\\MY-RSPM\\output")
And you should see these files:
[1] "Azone_2010_1_2021-02-04_143854.csv"
[2] "Azone_2038_1_2021-02-04_143854.csv"
[3] "Bzone_2010_1_2021-02-04_143854.csv"
[4] "Bzone_2038_1_2021-02-04_143854.csv"
[5] "Household_2010_1_2021-02-04_143854.csv"
[6] "Household_2038_1_2021-02-04_143854.csv"
[7] "Marea_2010_1_2021-02-04_143854.csv"
[8] "Marea_2038_1_2021-02-04_143854.csv"
[9] "Marea_Global_1_2021-02-04_143854.csv"
[10] "Region_2010_1_2021-02-04_143854.csv"
[11] "Region_2038_1_2021-02-04_143854.csv"
[12] "Region_Global_1_2021-02-04_143854.csv"
[13] "Vehicle_2010_1_2021-02-04_143854.csv"
[14] "Vehicle_2038_1_2021-02-04_143854.csv"
[15] "Worker_2010_1_2021-02-04_143854.csv"
[16] "Worker_2038_1_2021-02-04_143854.csv"
The default is to extract all Groups and Tables, and all the Fields within them. You can select a subset just by pushing a list of names into the Groups, Tables or Fields (see the instructions above). For example, the following commands will generate output files containing only the scenario years 2010 and 2038 from the sample model, and leaving out the Global group:
myrspm$groups <- c("2010","2038")
The groups will now look like this:
myrspm$groups
Group Stage Selected
1 2010 1 Yes
2 Global 1 No
3 2038 1 Yes
To clear a selection of groups (or tables or fields), you can just push an empty list, like this:
myrspm$groups <- ""
myrspm$tables <- ""
myrspm$fields <- ""
And then the groups will again have everything selected.
myrspm$groups
Group Stage Selected
1 2010 1 Yes
2 Global 1 Yes
3 2038 1 Yes
A realistic example might be to select all the fields with 'vmt' in their name, from the Marea table in the year groups. So we would do this:
myrspm$groups <- c("2010","2038")
myrspm$tables <- "Marea" # or c("Marea")
myrspm$fields <- myrspm$list(pattern="vmt")
And we can confirm that we are going to get what we want by doing this:
myrspm$list(index=TRUE)
And finally, we can just extract the results into files, using myrspm$extract().
If you want to manipulate the model results within R, using R functions and packages, you can do the following:
results <- myrspm$extract(saveTo = FALSE)
That instruction creates an R list of R data.frames, each of which contains a single Datastore table, applying whatever selections you made. Be aware that extract loads the entire Datastore into memory. So if your model is large, you may want to select a subset of groups or tables. Or you can just save the outputs into files and then load those back into R one at a time for further processing.
The saveTo option can be used to specify an alternate directory, so you can do something like the
following to create an alternate output directory with only selected groups or tables:
myrspm$groups <- c("2010", "2038")
myrspm$extract(saveTo = "years-only")
You will then find a directory called years-only next to the model scenario inputs containing the extracted subset.
If you try to do a new Datastore extract into an existing folder (outputs or whatever),
VisionEval will tell you that the directory already has things in it. You should specify the
overwrite parameter like this to replace the existing files:
myrspm$extract(saveTo = "years-only", overwrite = TRUE)
If you make changes to your scenario inputs and would like to run the model again, you can clear the results like this:
myrspm$clear()
VisionEval will ask you for confirmation, and if you type 'y' and press
<Enter>, the output files will be erased. You'll see something this:
[1] "/models/MY-RSPM/ModelState.Rda"
[2] "/models/MY-RSPM/Datastore"
[3] "/models/MY-RSPM/Log\_2021-02-04\_10\_50\_20.txt"
Clear ALL prior model results? (y/n/c)
y
Model results cleared.
Then you can run your scenario again.
Rather than use the openModel command line interface, it is easy to manually run a VisionEval
scenario by changing to the directory that contains the scenario components and then
source'ing the run_model.R script, with this R command line (or the RStudio Code / Source File... menu option):
source("run_model.R")
You can use that instruction as the basis for R scripts to automate running a lot of scenarios.
To run a VisionEval model from within an operating system batch or shell script, you should change
to your VisionEval model directory, then use the Rscript program to run the model (note the
directory separator will be different on a Macintosh or on Linux):
cd VisionEval\models\MY-RSPM
Rscript run_model.R
Up-to-date information on using VisionEval can be found on the VisionEval Wiki, including information on developing data file inputs, validating the model outputs, and using the outputs to support planning decisions.
- Getting Started
- VisionEval Primer
- Concepts Primer
- VisionEval Models
- VERPAT Tutorial
- VERSPM Tutorial
- VE-RSPM Training
- VE-State Tutorial
- Developer Orientation