5  Install

This chapter describes the process for installing and configuring the FluvialGeomorph toolbox and its required software components.

Software Requirements

Here is a summary of the software that must be installed to use the FluvialGeomorph toolbox. The rest of this chapter will describe how to complete these installations.

  • Windows OS (10+ recommended, Server 2019). ArcGIS desktop GIS applications are only provided by ESRI for the Windows platform.
  • R Statistical Computing Language (4.x+ recommended)
  • RStudio Desktop (1.3+ recommended)
  • TauDEM (5.3.7+ recommended)
  • ArcGIS Pro (2.6+ recommended)
  • ArcGIS Desktop (10.8+ recommended), optional, limited support
  • FluvialGeomorph toolbox, latest version

Install R

R is a statistical computing environment required to perform calculations and report generation (R Core Team (2020)).

  • Ensure that R is installed.
  • R version 4.x or greater is recommended.
  • Ensure that RTools is installed. You will need either RTools35 for R v3.5.x or RTools40 for R v4.x. RTools is required for compiling R packages from source. It is highly recommended, but not strictly required.
  • Ensure that your RTools installation is on the system PATH (i.e., open a command prompt window, use the path command). If not, set your user environment PATH variable to the appropriate (depending on the R major version) RTools bin directory (e.g., C:\Rtools\bin, C:\rtools40\usr\bin).

Install RStudio

Rstudio is an Integrated Development Environment (IDE) for R that streamlines development and troubleshooting.

  • Ensure that Rstudio is installed.
  • RStudio version 1.4 or greater is recommended.
  • RStudio is recommended, but not strictly required.
  • Update your currently installed R packages to the latest version. On the RStudio tools menu, select “Check for Package Updates…”. Click the “Select All” button and click the “Install Updates” button.
  • If asked to compile packages from source, select “Yes” if you installed RTools.

Install ArcGIS Pro

ESRI ArcGIS Pro is the GIS application where the FluvialGeomorph analysis will be performed and where the toolbox will be accessed.

  • Ensure that ArcGIS Pro is installed.
  • ArcGIS Pro version 2.6+ is recommended.

Limited ArcMap support

ESRI ArcMap can currently be used to run the FluvialGeomorph toolbox, but use of ArcGIS Pro provides more functionality (e.g., charting, map templates, etc.). As the ArcMap application approaches end of life, it will no longer be supported by the FluvialGeomorph toolbox. As ArcMap is a 32-bit application, some R functions currently do not always perform as expected under 32-bit R. If you expect to get the most out of the FluvialGeomorph toolbox, migrate now to ArcGIS Pro to take advantage of the latest data formats, geoprocessing speed, Python 3, and 64-bit R.

Install arcgisbinding

The ESRI arcgisbinding R package allows ArcGIS Pro and ArcMap to read and write to R sessions. Installing it through ArcGIS Pro also enables it for use in ArcMap as well.

Install the latest arcgisbinding version

  • In ArcGIS Pro, on the top menu, click “Project”, and click “Options” on the left menu.
  • In the “Options” dialog box, click “Geoprocessing” on the left menu.
  • On the “Geoprocessing” page, scroll down to the “R-ArcGIS Support” section.
  • In the “R-ArcGIS Support” section, verify the installed R version for ArcGIS to use.
  • Select an R version in the 4.x series.
  • From the “Installed ‘arcgisbinding’ package version:” dropdown menu, choose the “Check package for updates” option.

Download a specific arcgisbinding package version

Sometimes the FluvialGeomorph toolbox requires a specific version of the arcgisbinding package. Check the version compatibility matrix in the release notes for guidance. If the FluvialGeomporph toolbox release you are using specifies a particular combination of software versions, please manually download the specified version using these instructions:

  • Navigate to the following URL: https://github.com/R-ArcGIS/r-bridge
  • In the “Releases” section on the middle-right side of the page, click the “+ xx releases” link.
  • Download the v1.0.1.239 version. This file is named: arcgisbinding_1.0.1.239.zip
  • Note the location of the file you just downloaded. We will use it in a following step.

Install a specific arcgisbinding package version

  • In ArcGIS Pro, on the top menu, click “Project”, and click “Options” on the left menu.
  • In the “Options” dialog box, click “Geoprocessing” on the left menu.
  • On the “Geoprocessing” page, scroll down to the “R-ArcGIS Support” section.
  • In the “R-ArcGIS Support” section, verify the installed R version for ArcGIS to use.
  • Select an R version in the 3.6.x series.
  • Below the “Detected R home directories” drop-down menu, you will see the arcgisbinding package section. From the drop-down, choose the “Update from file” option. Navigate to the arcgisbinding_1.0.1.239.zip file you downloaded in an earlier step and click the OK button.

Install FluvialGeomorph

The code in the FluvialGeomorph-toolbox/ repository contains all of the files needed to use this ArcGIS toolbox.

  • Open a web browser and navigate to https://github.com/FluvialGeomorph/FluvialGeomorph-toolbox/.
  • In the “Releases” section in the upper right side of the page, click the green “latest” link.
  • On the latest release page, use the “Source code (zip)” link toward the bottom of the page to download a ZIP archive of the toolbox.
  • Copy the ZIP archive file to your project working directory.
  • If you already have a previous version of the FluvialGeomorph toolbox, delete it now.
  • Unzip the archive file of the latest version to your project folder.
  • In ArcMap or ArcGIS Pro, navigate to the folder where you just unzipped the archive and you are ready to use this ArcGIS toolbox.

Install the FluvialGeomorph R packages

In this section we will use the FluvialGeomorph toolbox to install the R packages needed by the toolbox.

  • Ensure that all other R applications (e.g., RGui, RStudio) are closed.
  • In ArcGIS Pro, navigate to the FluvialGeomorph toolbox and add it to your project.
  • In the Install toolset, use the Install R packages tool to install the required R packages.
  • In the tool’s “Messages” section, follow the R console output for messages on installation progress.

Troubleshooting

This is a list of commonly experienced errors and warnings when installing FluvialGeomorph R packages and their workarounds.

Problem: cannot remove prior installation of package '<some package>'
Solution: Ensure that all other R applications (e.g., RGui, RStudio) are closed.

Install Tutorial Data

See the Tutorial Data chapter for instructions on downloading and setting-up the tutorial data.