Getting Started

Overview

The VE software framework is 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 also distributed as R packages. A simple R script is used to implement a model by initializing the model environment and then calling modules successively.

The repository is organized into two directories:

• The sources directory contains the following directories:
  • visioneval framework package
  • VE modules such as VESimHouseholds and VESyntheticFirms
  • VE models such as VERPAT, VERSPM, and VEState
  • VEGUI graphical user interface for running and viewing tabular results
  • VEScenarioViewer interactive multiple-run scenario viewer / visualizer for viewing results
• The api directory contains documentation of the model system. The model system design document is the most complete at the present time. VisionEval framework functions are documented in a network visualization of the functions and their call relationships.

Installation and Setup

1. Install R version 3.4.2 or later in a location where you have write access.
2. Start R and source the install script. This script may take quite some time to run.

• Sourcing the script can be done via: source("https://raw.githubusercontent.com/gregorbj/VisionEval/master/install.R")
• If working within a proxy server (like ODOT), uncomment the four commented lines at the top of the script in order to get access to GitHub.
• If working with an R install without write access to its library folder (like ODOT), first change your library location to a write accessible location. See help('.libPaths').

Running VE Models

There are multiple ways to run VisionEval models. VisionEval models can be run via the command line or via the GUI, and can be run for one scenario or multiple scenarios in parallel. Results can be viewed in tabular form or with the interactive VEScenarioViewer. This repository contains three complete example models - VERPAT, VERSPM, and VEState.

Running the models from the R command line

1. Git clone this repository to your computer in order to get the example models. A zipped version of the repository is available here for download.
2. Start R and run the following commands:

#VERPAT
full_path = "your/path/to/VisionEval/sources/models/VERPAT"
setwd(full_path)
source("run_model.R")

#VERSPM
full_path = "your/path/to/VisionEval/sources/models/VERSPM/Test1"
setwd(full_path)
source("run_model.R")

#VEState
full_path = "your/path/to/VisionEval/sources/models/VE-State"
setwd(full_path)
source("run_model.R")

3. See the VERPAT tutorial for more information.

Running VEGUI to then run a model

1. Git clone this repository to your computer in order to get the example models. A zipped version of the repository is available here for download.
2. Start R and run the following commands:

library("shiny")
full_path = "your/path/to/VisionEval/sources/VEGUI"
setwd(full_path)	
runApp('../VEGUI')

3. VEGUI should launch in your browser
4. Click "Select Scenario Script" and navigate to the VERPAT, VERSPM, or VEState run_model.R script in your local repository
5. Click "Run" and then "Run Model" to run the model
6. See the VERPAT tutorial for more information.

Note: VEGUI works best using parallel processing but some Windows machines have problems due to lack of administrator access to open ports. In that case, set planType = "sequential" in your/path/to/VisionEval/sources/VEGUI/global.R.

Running Multiple Scenarios of a Model

1. Git clone this repository to your computer in order to get the example models. A zipped version of the repository is available here for download.
2. Start R and run the following commands, which run hundreds of scenarios in parallel for a number of hours:

#VERPAT
full_path = "your/path/to/VisionEval/sources/models/VERPAT_Scenarios"
setwd(full_path)
source("run_model.R")

#VERSPM
full_path = "your/path/to/VisionEval/sources/models/VERSPM_Scenarios"
setwd(full_path)
source("run_model.R")

Note: To run these using multiple processors, be sure to specify planType = "multiprocess" in the run_model.R script. Some Windows machines have problems with the parallel processing due to lack of administrator access to open ports. In that case, set planType = "sequential".

3. Explore the relationship between input scenarios and results using VEScenarioViewer. Try the interactive VERPAT and VERSPM examples scenario viewers (visualizers).
4. See the VERPAT tutorial for more information.

Develop Branch

The current release version of VisionEval is on the master branch. The current development version is on the develop branch. When working on develop (or a branch other than master), make sure to install the correct branch version of the packages and to use the branch example data. To download, install, and test the develop branch resources, do the following:

1. Git clone (i.e. copy) the develop branch to your computer.

git clone --branch develop --depth 1 git@github.com:gregorbj/VisionEval.git 

2. Run the same R commands above

A zipped version of the develop branch is available here.