Skip to content

FVSOnline

Jump to bottom
mshettles edited this page Jul 27, 2022 · 7 revisions

How to install the FVSOnline R package (fvsOL) and the rFVS R package using the Git repository source

Author: Nicholas Crookston (ncrookston.fs@gmail.com)

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 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 (ncrookston.fs@gmail.com).

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.
  • 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.
  • You need sqlite3--if you don’t have it search for an installation package for that software and install it. It is needed by the following mdbtools so it might be installed automatically if you first do step 5.
  • You need mdbtools if you need to import any 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.
  • The FVS shared libraries. If you don’t have them, you can get build them from source or get them from FMSC at https://www.fs.fed.us/fvs/software/index.shtml (only available for Windows computers).
  • You need to be “online” to access the Internet.

Steps

  • Start R and run the following commands to get and install the supporting packages:
 neededPkgs = c("devtools", "shiny", "Cairo", "rhandsontable", "ggplot2", "parallel", "RSQLite", "plyr", "dplyr", "colourpicker", "rgl", "leaflet","zip", "openxlsx", "rgdal", "nlme")
install.packages(neededPkgs)
  • Fetch the fvsOL and rFVS packages. Using git you can use the following command to get both. First, make a directory where you want to store the packages, 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
  • 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 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)"
 
 # 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)"
  • 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')"
Clone this wiki locally