Skip to main content

VisionEval User Guide

14 VisionEval Module Build Process

knitr::opts_chunk$set(echo = TRUE, results=‘hide’)

14.1 (Re)Building VisionEval

This chapter describes the build process for VisionEval. The VisionEval “build process” (re)builds VisionEval packages to incorporate default, localized, or custom data in the module’s model estimation and data processing steps in order to update data resources and estimated model coefficients.

This chapter sets out the process for updating these datasets that VisionEval modules use during any of the model runs.

For the VisionEval models to access any of these updated data requires re-building of the VisionEval package source. The reason that a package must be rebuilt before it is available for use in VisionEval is that VisionEval creates its own R environment with its own VisionEval modules built as R packages.

14.1.1 What is an R “package”?

R is a community-based project and depends upon a community of re-usable, reproducible, and shareable code. To facilitate this, R uses a standardized method for bundling a collection of code and data into a built into a shareable binary “package”. Packages can then be downloaded and installed into your local R library. An R environment can only access the packages installed in a local R library.

14.1.2 Why is this relevant?

VisionEval relies on this fundamental package framework for sharing code and data from its modules. In order to alter the data used within a VisionEval module (i.e., an R Package) it must be repackaged, or re-built, using the new data. Otherwise, if only the source data is altered and not re-built, the VisionEval environment fails to recognize the updated data.

14.1.3 How are packages built?

14.1.3.1 Build vs Runtime Environment

It is crucial for users to understand the distinction between the VisionEval runtime environment and the VisionEval build environment. VisionEval begins as source code and data in the build environment from which the VisionEval R packages are built, and a runtime environment is created. VisionEval models can only be run from a runtime environment where the built packages are loaded (into an R session) and used by R to perform the model steps. The VisionEval runtime environment will be referred to as VisionEval from this point on in the document.

14.2 Where do we Start the ‘Re-Building’ Process

The process for obtaining the source code used for rebuilding or updating any module within VisionEval depends on how a user obtained the current runtime:

  • Users who installed a pre-built VisionEval runtime environment using a VisionEval installer.

  • Users who created a VisionEval runtime environment through a build environment by obtaining the source code from GitHub.

The processes for both types of users are described below. Additionally, the process for advanced users who may want to build VisionEval natively from the source code for development or on non-Windows computers is described at the end of this section.

14.2.1 Users who installed VisionEval through the VisionEval installer

Users at this point should have a full VisionEval installed and running. If not visit https://visioneval.org/docs/getting-started.html#installation-and-setup and follow the path 1 listed to download and install the base model.

14.2.1.1 Software Requirements

  • R – R for windows can be downloaded here: https://cran.rstudio.com/ (The most recent version is usually supported in VisionEval within a few weeks of its release). It is suggested to use an R version that aligns with the VE R version. The Cran website includes links to past versions although the most current is the one often highlighted on the first page.

  • RStudio – RStudio for windows can be downloaded here: https://posit.co/download/rstudio-desktop/

14.2.1.2 (Re)Building Package

Rebuilding a package in this VisionEval setup will require source code for the specific build that was installed (specific R, operating system, etc.) which is made available in a zip file that you can get from the Github release. Be sure to pick the version corresponding your installed version of R and VisionEval. This zip file contains the source code and default data for all the VisionEval packages that can be easily installed in VisionEval using R native command “install.packages” or RStudio build tools. The user can download and unzip the zip file into their VisionEval directory. After unzipping a src folder will be present alongside ve-lib. Each VisionEval package is present in a sub-folder of src and you can change files there and rebuild the package as described below.

The source code of these packages contains code and data upon which the modules are built. This data can then be updated with localized or custom data and the module can be rebuilt into VisionEval. The process of rebuilding is explained in more detail in the section of this document.

14.2.2 Users who created VisionEval through source code from GitHub

For advanced users who have a complete VisionEval built using the source code from GitHub, the process for updating and rebuilding individual modules and packages can be done without the need to download additional source code material. A version of the source code, easily installable in R, is created during the “build process”.

Note: if you want to install a complete VisionEval model from the source code please see the section VisionEval Full Build Process.

14.2.2.1 Additional Software Requirements

14.2.2.2 (Re)Building Packages Using Package Sources

The source code created during the build process can be used to rebuild packages in this VisionEval setup. The process of rebuilding is the same as before, the only difference is the location of the source code relative to the VisionEval setup.

VisionEval build environment allows for a single VisionEval package to be created, modified, and installed (aka “built”) into an existing VisionEval that had been previously created from a full install build. This is useful for creating or modifying single packages and their constituent modules within the VisionEval framework. The build process can be used to incorporate localized or custom data into VisionEval by making a change to a module and then rebuilding it.

14.2.3 VisionEval Full Build Process

Advanced users may want to build VisionEval natively from the source code for development or on non-Windows computers. This process can take several hours the first time it runs. For more details, see instruction in build/Building.md.

  1. Install RTools. The easiest way is to download and run the RTools windows install. RTool4.0 has been tested, but RTool4.3 should also work.

  2. Clone or “fork” a copy of the VisionEval from the Github repository (https://github.com/VisionEval/VisionEval) into a directory of your choice (e.g., C:/Users/<``user name``>/Documents/VisionEval-Source) using:

  1. Start VisionEval by double clicking the VisionEval.RProj file in the newly cloned VisionEval-Source directory.

  2. Start the build process by entering ve.build``() into the console. This will start the process of downloading and installing every R package dependencies required by VisionEval as well as installing the VisionEval framework specific packages. The output will look something like this:

  • This will take a while, potentially over an hour. Once completed, you’ve successfully performed a full build install of the VisionEval runtime environment.
  1. A new folder called ‘built’ will be created your source directory, populated with a sub-folder for the R-version you used to build VisionEval with:\
    VisionEval-Source\built\visioneval\<your R version number e.g., 4.1.``3``>\

  • This will contain a few key folders:

    • src: The VisionEval package source.

    • ve-lib: The package library containing all built and installed R packages.

    • runtime: The built model runtime.