1 Getting started

1.1 Prerequisites

Minimum system requirements:

Windows 10, macOS 10.13 High Sierra, or Ubuntu 20.04 LTS;
20 GB of storage space, plus additional storage for model outputs;
128 GB RAM to run the model over the full area (less for sub-areas);
High-speed internet connection.

The following section provides details on installing prerequisite software for running LandWeb.

1.1.1 Docker

If you prefer to not use Docker, skip this subsection.

Due to idiosyncratic difficulties of installing multiple pieces of software and ensuring the correct versions are used throughout, we provide prebuilt Docker (https://www.docker.com/) images, which better provides a consistent and reproducible software environment for running the model.

Thus, using these images are preferred over ‘bare-metal’ installation.

Install Docker for your system following https://docs.docker.com/get-docker/.

Next, pull the image from Docker Hub:

## get the image
docker pull achubaty/landweb-standalone:latest

## launch a new container based on thi image
docker run -d -it \
  -e GITHUB_PAT=$(cat ${HOME}/.Renviron | grep GITHUB_PAT | cut -d '=' -f 2) \
  -e PASSWORD='<mySecretPassword>' \
  --memory=128g \
  --cpus=32 \
  -p 127.0.0.1:8080:8787 \
  --name LandWeb \
  achubaty/landweb-standalone:latest

Once the container is running, open your web browser and go to localhost:8080.

Login to the Rstudio session as user rstudio and password <mySecretPassword> (change this password when launching container above).

Once finished, you can stop and destroy the container:

docker stop LandWeb
docker rm LandWeb

1.1.2 Development tools

1.1.2.1 Windows

Download Rtools version 4.2 from https://cran.r-project.org/bin/windows/Rtools/rtools42/rtools.html and install it as administrator. Rtools provides the necessary compilers etc. to build and install R packages from source on Windows.
1. During installation, be sure to check the option to add Rtools to your PATH.
Download and install a proper text editor, e.g. Notepad++ (https://notepad-plus-plus.org/downloads/).

1.1.2.2 macOS

1.1.2.2.1 Xcode command line tools

To build software, you will need the Xcode command line tools¹, which include various compilers and git version control software.

xcode-select --install

1.1.2.2.2 `homebrew` package manager

Next, install homebrew which provides a package manager for macOS. This will facilitate software updates and will handle various package dependency issues automatically.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1.1.2.3 Ubuntu Linux

sudo apt-get update

sudo apt-get -y install \
    build-essential \
    biber \
    ccache \
    cmake \
    curl \
    libarchive-dev \
    libcairo2-dev \
    libcurl4-openssl-dev \
    libgit2-dev \
    libglpk-dev \
    libgmp3-dev \
    libicu-dev \
    libjq-dev \
    libmagick++-dev \
    libnode-dev \
    libpng-dev \
    libprotobuf-dev \
    libprotoc-dev \
    libssh2-1-dev \
    libssl-dev \
    libxml2-dev \
    libxt-dev \
    make \
    p7zip-full p7zip-rar \
    pandoc pandoc-citeproc \
    protobuf-compiler \
    qpdf \
    screen \
    sysstat \
    texinfo texlive-base texlive-bibtex-extra \
    texlive-fonts-extra texlive-latex-extra texlive-xetex \
    wget \
    xauth \
    xfonts-base \
    xvfb \
    zlib1g-dev

1.1.3 Geospatial libraries

In order to work with geospatial data, recent versions of GDAL, PROJ, and GEOS geospatial libraries need to be available on your system.

1.1.3.1 Windows

No additional should be needed, as recent versions of R geospatial packages include pre-bundled versions of GDAL, PROJ, and GEOS.

1.1.3.2 macOS

Use homebrew to install the required geospatial software libraries:

brew install pkg-config
brew install gdal
# brew install geos
# brew install proj
brew install udunits

1.1.3.3 Ubuntu Linux

The default Ubuntu 20.04 LTS package repositories ship older versions of the geospatial libraries we will be using, so we will need to to add some additional repositories to get the latest versions.

## add GIS repository
sudo add-apt-repository ppa:ubuntugis-unstable/ppa
sudo apt-get update

Install additional system dependencies that serve as prerequisites for running the LandWeb model in R.

sudo apt-get -y install \
    gdal-bin \
    libgdal-dev \
    libgeos-dev \
    libproj-dev \
    libudunits2-dev \
    python3-gdal

Optionally, we install mapshaper geospatial library which is used to speed up polygon simplification.

## mapshaper installation
sudo apt-get remove -y libnode-dev

curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -

sudo apt install nodejs
sudo npm install npm@latest -g
sudo npm install -g mapshaper

1.1.4 `git`, Git Kraken, and GitHub

git is the version control software used throughout this project, and is required to ‘checkout’ specific versions of the code as well as to make changes and ‘push’ these changes to the model code repository.

Install the latest version of git from https://git-scm.com/downloads or via your package manager.

Windows users should install as administrator. Use nano (instead of vi/vim) as the default text editor. For all other choices, use the recommended settings.

For macOS users, git is included with the Xcode command line tools.

Create a GitHub (https://github.com) account if you don’t already have one, and configure a Personal Access Token (PAT).

A GitHub (https://github.com) account is required to assist with package installation and accessing model code.

Several packages used by LandWeb are only available on GitHub. Because we will be installing several of these, we want to ensure we can do so without GitHub rate-limiting our requests. Without a PAT, some packages may temporarily fail to install, but can be retried a little later (usually 1 hour).

Create a GitHub PAT following the instructions²;
Be sure to uncheck all scopes.
Copy this token and save it in a text file in your home directory called .Renviron:

Run the following in an R session to edit ~/.Renviron:
```
install.packages("usethis")
usethis::edit_r_environ()
```
Paste the following into the .Renviron file, using your copied token:
```
GITHUB_PAT=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

If creating ~/.Renviron using a text editor, be sure to save it without a .txt extension. Windows users in particular should ensure they edit this file via Rstudio per above, or use a proper text editor, e.g., Notepad++ (https://notepad-plus-plus.org/downloads/).

Optional. Install the latest version of GitKraken from https://www.gitkraken.com/download/.

The free version is sufficient to access the public repositories used in this project. However, the paid pro version is required to access private repositories.

1.1.5 R and Rstudio

Download and install R version 4.2.3.

Windows

Download R from https://cran.r-project.org/bin/windows/base/R-4.2.3-win.exe;
Install R as administrator.

macOS

Install rig (https://github.com/r-lib/rig) to manage multiple R installations.

brew tap r-lib/rig
brew install --cask rig

## e.g., M1/M2 mac users, install the arm version
rig install 4.2-arm64

## start Rstudio using a specific R version:
rig rstudio 4.2-arm64

Ubuntu Linux

Add the CRAN apt repository to get the required version of R.

## add R repository
sudo sh -c 'echo "deb https://cran.rstudio.com/bin/linux/ubuntu focal-cran40/" > \
    /etc/apt/sources.list.d/cran.list'
sudo apt-key adv --keyserver keyserver.ubuntu.com \
    --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9

sudo apt-get update

Install R version 4.2.3

To install previous versions of R see https://github.com/achubaty/r-config/blob/master/using-multiple-R-versions-on-linux.Rmd or use rig (https://github.com/r-lib/rig).

Download and install the latest version of Rstudio from https://www.rstudio.com/products/rstudio/download/.

Windows users should install Rstudio as administrator.

(optional) On Linux, configure ccache to speed up R package re-installation and updates³.

## configure ccache for R package installation
mkdir -p ~/.ccache
mkdir -p ~/.R
{ echo 'VER='; \
  echo 'CCACHE=ccache'; \
  echo 'CC=$(CCACHE) gcc$(VER)'; \
  echo 'CXX=$(CCACHE) g++$(VER)'; \
  echo 'CXX11=$(CCACHE) g++$(VER)'; \
  echo 'CXX14=$(CCACHE) g++$(VER)'; \
  echo 'FC=$(CCACHE) gfortran$(VER)'; \
  echo 'F77=$(CCACHE) gfortran$(VER)'; } >> ~/.R/Makevars
{ echo 'max_size = 5.0G'; \
  echo 'sloppiness = include_file_ctime'; \
  echo 'hash_dir = false'; } >> ~/.ccache/ccache.conf

1.2 Getting the code

All modules are written in R and all model code was developed collaboratively using GitHub (https://github.com), with each module contained in its own repository. Code that is shared among modules was bundled into R packages, and hosted in on GitHub repositories. All package code is automatically and regularly tested using cross-platform continuous integration frameworks to ensure the code is reliable and free of errors.

mkdir -p ~/GitHub
cd ~/GitHub

## get development branch (app and deploy are private submodules)
git clone --recurse-submodules \
  -j8  https://github.com/PredictiveEcology/LandWeb

Windows users should ensure the GitHub/ directory is accessible at both ~/GitHub and ~/Documents/GitHub by creating a directory junction:

mklink /J C:\\Users\\username\\Documents\\GitHub C:\\Users\\username\\GitHub

1.3 Project directory structure

Model code is organized by the following directories and summarized in the table below.

NOTE: it may be useful to store data in a different location, but to map this location back to the e.g., cache/, inputs/, and/or outputs/ directories using symbolic links. See R’s ?file.link to set these up on your machine.

Table 1.1: LandWeb project directory structure
directory	description
R/	additional R helper scripts
cache/	all per-run and per-study area cache files stored here
docker/	Dockerfiles, scripts, and documentation
docs/	rendered model and app documentation
inputs/	all model data inputs stored here
m/	module code (git submodules)
manual/	raw files for generating documentation manual
outputs/	all per-run model outputs stored here
renv/	project package management directory

1.4 Updating the code

After having cloned the LandWeb code repository, users can keep up-to-date using their preferred graphical git tools (e.g., GitKraken) or from the command line.

1.4.1 Using GitKraken

Figure 1.1: Screenshot showing showing code commits in Git Kraken. The submodules pane is highlighted on the bottom left.

Open the LandWeb repo, and after a few moments you will see the commit history update to reflect the latest changes on the server.
‘Pull’ in the latest changes to this repo, noting that the status of the git submodules (left hand side) may change.
If any submodules have changed status, for each one, right-click and select ‘Update ’.

1.4.2 Using the command line

WARNING: experienced git users only!

git pull
git submodule update

1.5 Data requirements

In order to access and use the proprietary data in LandWeb simulations, you will need to be granted access to the shared Google Drive directory. During first-run of the model, all required data will be downloaded to the inputs/ directory.

To request access, please contact Alex Chubaty (achubaty@for-cast.ca).

1.6 Getting help

https://github.com/PredictiveEcology/LandWeb/issues

Overview

2 Running LandWeb