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 four directories:
  • visioneval framework package
  • VE modules such as VESimHouseholds and VESyntheticFirms
  • VE models such as VERPAT and VERSPM
  • VEGUI graphical user interface for running and viewing tabular results of VE models
  • VEScenarioViewer interactive multiple-run scenario viewer / visualizer for viewing results of VE models
• 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.5 in a location where you have write access.
2. Start R and source the install script. This script may take up to 20 minutes 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, 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 two complete example models - VERPAT and VERSPM.

Running VERPAT or VERSPM 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")

3. See the VERPAT tutorial for more information.

Running VEGUI to then run VERPAT or VERSPM

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 or VERSPM 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.

Running Multiple Scenarios of VERPAT or VERSPM

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")

3. Explore the relationship between input scenarios and results using VEScenarioViewer. Try the VERPAT and VERSPM examples.
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.