How to install the FVSOnline R package (fvsOL) and the rFVS R package using the Git Repository Source

Author: Nicholas Crookston ([email protected])
Last Updated: May 2025 by Daniel Wagner

Contents

• Introduction
• Prerequisites
• Steps

Introduction

FVSOnline is an interface to the Forest Vegetation Simulator using the Shiny web application framework which is implemented using the R programming language for the server code and html plus JavaScript for the client code. FVSOnline also relies on rFVS (see rFVS) to interact with FVS.

FVSOnline can be run on a local computer where the "server" is a local R session and the "client" is a browser. This document describes how to set up the FVSOnline in this "Onlocal" configuration using the public source code stored stored on GitHub. These instructions do not describe how to install FVS itself (it is a separate collection of programs that actually runs the projections). You will need to get the shared geographic variant libraries (.dlls on Windows) from the FVS website or build them yourself following the instructions located at: https://github.com/USDAForestService/ForestVegetationSimulator/wiki/.

FVSOnline is offered as an R package called fvsOL. Note that fvsOL requires a second package, rFVS, that contains the R functions that directly interact with the FVS shared libraries. The installation process of these two packages use the R package management tools and R and are detailed below.

FVSOnline runs in a true client/server configuration. If you are interested in setting it up in on a server, contact Nicholas Crookston ([email protected]).

Prerequisites

• R must be installed for your system and must be “findable” from the a shell script command. That is, you must have it installed so you can run R and Rscript from a terminal window. If you can not start both R and Rscript you man need to adjust your system path environment so these programs can be run from the terminal window. If using a Bash shell from RTools, you may need to add the following to rtoolsXX/home/UserName/.bash_profile:

PATH=${PATH}:/c/RLocation/bin

• Having a “make” utility is helpful but if you don’t have it you can run the necessary commands from the terminal window.
• Having the “Git” utility is helpful but you can alternatively go to the GitHub website (https://github.com/USDAForestService/ForestVegetationSimulator-Interface/archive/refs/heads/main.zip) and download the necessary zip files and unzip them.
• Mdbtools -- required to import data from Microsoft Access databases. You do not need mdbtools if your data are in Excel, .csv files, or sqlite3. Here is a source that uses “brew” to install the software from https://formulae.brew.sh/formula/mdbtools You may find other sources.
• Sqlite3-- Required for database input / output. It is also used by mdbtools and may be installed automatically with mbdtools.
• The FVS shared libraries. If you don’t have them, you can get build them from source or get them from the software page of the official FVS website (only available for Windows computers).

Steps

• Start R and run the following commands to get and install the supporting packages once selecting you preferred CRAN mirror:

neededPkgs = c("devtools", "shiny", "Cairo", "rhandsontable", "ggplot2", "RSQLite", "plyr", "dplyr", "colourpicker", "rgl", "leaflet","zip", "openxlsx", "nlme", "shinyFiles")
install.packages(neededPkgs)

• Fetch the fvsOL and rFVS source code. Using git you can use the following command to get both. First, make a directory where you want to store the repository, start a terminal (on Windows you can use powershell or another shell). If you don’t have git, then point your browser to the GitHub web site and download the zip files for packages rFVS and fvsOL.

git clone https://github.com/USDAForestService/ForestVegetationSimulator-Interface.git

The fvsOL build requires rFVS as a dependency, so rFVS must be built first.

• From an RTools or terminal window prompt, change directories to the rFVS directories, if you have make, then simply type make.

• From an RTools or terminal window prompt, change directories to the fvsOL directories, if you have make, then simply type make.

• If you don’t have make, then run these commands from the terminal window.

 # build rFVS: the documents, the package, and then install the package
 Rscript --default-packages=devtools -e "devtools::document(pkg='rFVS')"
 Rscript --default-packages=devtools -e "devtools::build(pkg='rFVS')"
 Rscript --default-packages=devtools -e "devtools::install(pkg='rFVS',type='source',repos=NULL)"

 # build the required “parms.Rdata” file from the source
 Rscript fvsOL/parms/mkpkeys.R
 
# build the help file
 Rscript inst/extdata/mkhelp.R
 
 # build fvsOL: the documents, the package, and then install the package
 Rscript --default-packages=devtools -e "devtools::document(pkg='fvsOL')"
 Rscript --default-packages=devtools -e "devtools::build(pkg='fvsOL')"
 Rscript --default-packages=devtools -e "devtools::install(pkg='fvsOL',type='source',repos=NULL)"

• You can create an FVS Project directory anywhere on the file system. By convention, this directory is often named FVSProjects and contains subdirectories the each contain the data for a project. You could, for example, use these commands:

 cd
 mkdir FVSProjects
 cd FVSProjects
 mkdir Project_1
 cd Project_1

• Now start fvsOL. If you don’t store the FVS shared libraries in the project directory, then replace the FVSbin string with the path name to the shared libraries (see alternative example below).

 R -e "require(fvsOL);fvsOL(fvsBin='FVSbin')"

• Here is an alternative example. Let's say that you store the FVS binaries in a directory on a “Z:” drive (Windows) named myFVSbin. You could start FVSOnline using the following command (notice the use of the forward slash'/', its use is important because the backslash is an escape character in R and using it would require you use two backslashes as in Z:\myFVSbin).

 R -e "require(fvsOL);fvsOL(fvsBin='Z:/myFVSbin')"

• It is worth noting the default installation directory structure of FVS from the website is as follows:

PathTo/FVS
├── Blank Databases
├── FVSSoftware
│   ├── FVSbin
│   ├── mdbtools
|   ├── R
│   |── SQLite
|   |── FVS_Icon.bat
|   |── FVS_Icon.vbs
|   |── FVSprojects.Rexec
│   └── OnlocalIcon.ico
├── Project_1
├── Training Guides
├── !ReadMe_FVS.txt
└── license.txt

Therefore, starting FVS when your current directory is Project_1 would be:

R -e "require(fvsOL);fvsOL(fvsBin='../FVSSoftware/FVSbin')"

If you have any questions about this Wiki or FVS in general, please reach out to our help desk at [email protected]