WaterGAP3 Setup

1 Overview

This guide explains how to set up a new computer for the HydroGallery / WaterGAP3 R packages.

Quick check first: if you already have R, RStudio, and Git installed and configured, you can try running the three install commands directly:

remotes::install_github("Hydrology-RUB/HydroGalleryCpp")
remotes::install_github("Hydrology-RUB/WaterGAP3Cpp")
remotes::install_github("Hydrology-RUB/WG3Tools", build_vignettes = TRUE)

If all three packages install successfully, your setup is already working and you do not need to go through the rest of this guide. Only continue with the steps below if one or more of these commands fail (for example, with an authentication error or a “Repository not found” error).

The setup consists of:

  1. Installing R
  2. Installing Rtools
  3. Installing RStudio
  4. Installing Git
  5. Accepting the GitHub organization invitation
  6. Creating/getting a GitHub Personal Access Token (PAT)
  7. Connecting GitHub to R
  8. Installing the required R packages
  9. Installing the internal GitHub packages
  10. Testing the installation

The GitHub repositories are private, so each user needs access to the repositories and must authenticate with their own GitHub account.

2 Install R

Download and install the latest version of R from CRAN:

https://cran.r-project.org/

After installation, verify that R works by opening R or RStudio and running:

R.version.string

You should see the installed R version.

3 Install Rtools

Rtools is required on Windows to build R packages from source (for example, when installing packages directly from GitHub via remotes). It is not needed on macOS or Linux.

Rtools versions are tied to specific R versions, so you must install the Rtools version that matches your installed R version:

R version Rtools version
R 4.4.x Rtools44
R 4.3.x Rtools43
R 4.2.x Rtools42
R 4.0.x – 4.1.x Rtools40

Check your R version first with R.version.string (see previous step), then download the matching Rtools installer from CRAN:

https://cran.r-project.org/bin/windows/Rtools/

After installation, verify that R can find Rtools by running:

Sys.which("make")

or, for newer R versions:

pkgbuild::find_rtools(debug = TRUE)

(you may need to run install.packages("pkgbuild") first). If Rtools is set up correctly, this should return a valid path rather than an empty result.

Note: if you install a new major version of R later, you will need to install the matching new version of Rtools as well.

4 Install RStudio

Download and install the latest version of RStudio Desktop from Posit:

https://posit.co/download/rstudio-desktop/

RStudio is the recommended development environment for working with the HydroGallery / WaterGAP3 packages.

5 Install Git

Git is required because the R packages are installed directly from GitHub.

Download and install the latest version of Git:

https://git-scm.com/downloads

After installation, restart RStudio.

You can check whether Git is available with:

Sys.which("git")

If Git is installed correctly, R should return the path to the Git executable.

6 Get access to the GitHub organization

You must first be invited to the Hydrology-RUB GitHub organization.

You should receive an invitation from the organization administrator. Accept the invitation using your GitHub account.

You also need permission to access the required private repositories:

  • Hydrology-RUB/HydroGalleryCpp
  • Hydrology-RUB/WaterGAP3Cpp
  • Hydrology-RUB/WG3Tools

Make sure that you can open these repositories in your browser while logged into GitHub.

7 GitHub Personal Access Token

Because the repositories are private, R needs to authenticate with GitHub.

You should use your own GitHub account and your own Personal Access Token (PAT). Do not use another person’s token.

7.1 Create a GitHub token

If you do not already have a token, you can use:

install.packages("usethis")
usethis::create_github_token()

This will open GitHub in your browser and guide you through creating a token.

If your organization requires approval for fine-grained tokens, make sure the token is authorized to access the required repositories.

For a fine-grained token, the repository should have at least:

  • Repository access: the required private repositories
  • Contents: Read-only

Copy the token after creating it.

Important: GitHub normally shows the token only once. Store it securely.

8 Connect GitHub to R

Install the gitcreds package:

install.packages("gitcreds")

Then run:

gitcreds::gitcreds_set()

R will ask you to enter your GitHub Personal Access Token. Paste your token and press Enter.

When you paste the token, nothing may appear on the screen. This is normal and is done for security reasons.

Do not put the token directly into an R script. For example, do not do this:

token <- "github_pat_xxxxxxxxxxxxxxxxx"

The token should be stored securely by gitcreds, not hard-coded anywhere.

8.1 Check the credentials

You can check whether credentials have been stored with:

gitcreds::gitcreds_get()

If credentials are returned, GitHub authentication is configured correctly.

9 Install required R packages

Install the required packages:

install.packages(c(
  "remotes",
  "usethis",
  "gitcreds",
  "tidyverse",
  "terra"
))

These packages provide the tools required for the HydroGallery / WaterGAP3 environment.

10 Install HydroGalleryCpp

Install HydroGalleryCpp directly from GitHub:

remotes::install_github(
  "Hydrology-RUB/HydroGalleryCpp"
)

Because the repository is private, your GitHub authentication from the previous steps must be configured correctly.

11 Install WaterGAP3Cpp

Install WaterGAP3Cpp:

remotes::install_github(
  "Hydrology-RUB/WaterGAP3Cpp"
)

12 Install WG3Tools

Install WG3Tools:

remotes::install_github(
  "Hydrology-RUB/WG3Tools",
  build_vignettes = TRUE
)

After installation, you can view the available vignettes with:

vignette(package = "WG3Tools")

13 Test the installation

Load the packages:

library(tidyverse)
library(terra)
library(HydroGalleryCpp)
library(WaterGAP3Cpp)
library(WG3Tools)

If all packages load without errors, the installation was successful.

14 Troubleshooting

14.1 GitHub authentication error

If you receive an error such as:

Authentication failed

run:

gitcreds::gitcreds_set()

and enter a valid GitHub Personal Access Token.

Make sure that:

  1. You are logged into the correct GitHub account.
  2. Your GitHub account has access to the repository.
  3. Your token has permission to access the repository.
  4. The token has not expired.

14.2 Repository not found

If you receive:

Repository not found

check that you have access to the private repository. For example, open the repository in your browser:

Hydrology-RUB/HydroGalleryCpp

If you cannot see the repository while logged into GitHub, ask the organization administrator to give you repository access.

14.3 Git not found

If:

Sys.which("git")

returns an empty value, Git is probably not installed, or RStudio cannot find it. Install Git and restart RStudio.

14.4 Package fails to build from source / Rtools not found

If installing a package from GitHub fails with an error mentioning missing build tools (Windows only), check that Rtools is installed and matches your R version (see the Install Rtools section), then verify it with:

pkgbuild::find_rtools(debug = TRUE)

15 Security reminder

Never share your GitHub Personal Access Token.

Each person should:

  • use their own GitHub account;
  • use their own token;
  • store the token using gitcreds;
  • never put the token into an .R, .Rmd, .qmd, or .Rproj file;
  • never commit the token to GitHub.

Once the token is stored with gitcreds, you normally do not need to enter it again when installing packages from GitHub.