Since globiomvis is an R package, R is required. R can be downloaded here. On Linux, you can instead install R with the package manager of your distribution.
We highly recommend to also install the RStudio integrated development environment. It can be downloaded here. It will allow you to easily try the examples and debug your code. Some of the discussion that follows assumes that you have RStudio installed.
Packages are bundles that contain R scripts and sometimes code written in other languages (e.g. C or C++) for speedings up calculations or interfacing with other software (e.g. GAMS). Packages can easily be installed by typing install.packages("_<package name>_") or by clicking on the ‘package’ tab in RStudio. Most packages can be downloaded from CRAN, the official R package repository.
The globiomvis package depends on other R packages. A large subset of these are jointly referred to as the tidyverse, a curated package collection that includes dplyr, purrr, tidyr and ggplot2.
Installing packages sometimes results in conflicts when an older version of these packages is already installed on your system and has been loaded into memory. To prevent this, install packages immediately after (re)starting R. If you get the message These package have more recent versions available. It is recommended to update all of them. Which would you like to update?, the conservative choice is to select 3: None: you can always update later after further deliberation.
From an R or RStudio console, installing the globiomvis package can be as simple as:
# Install the devtools package, if you have not done so already install.packages("devtools") # Install globiomvis development version from GitHub, it is not available on CRAN devtools::install_github("iiasa/globiomvis")
This should also install all further required packages. Beware, on Windows, during the installation, you might be shown a dialog asking you to install RTools. Close that dialog for now, you can decide on that later as explained below.
On Windows, the gdxrrw source-only package listed in the globiomvis dependencies will fail to install if your system lacks a compiler. If you already have gdxxrw installed, you’re fine. Just ignore the error and use your installed version if it is reasonably recent.
If you do not have gdxxrw installed yet and the source-only gdxrrw failed to install, you can either install the compiler tools required for building the source files, which will add a lot of stuff to your system, or you can install a binary version of the gdxrrw package as documented in the next section.
To read/write GDX files from R, the gdxrrw package is required. This package is not available on CRAN and therefore cannot be installed using the standard approach (see next section). The package can be found here
To install gdxrrw without compiling, download the latest binary package built for your operating system and R version (if you have R version 3.5.X install the gdxrrw version that is built with R 3.5.x) and save the package archive file to a tempory directory. Then:
Linux should already have a compiler installed. On Windows, compiling code in source-only packages requires an Rtools installation. On MacOS, the development tools and libraries are required for compilaton.
After having installed these tools, performing the globiomvis installation as explained above should succeed in installing gdxrrw as well.
For gdxrrw to work, the package needs to load GDX libraries from the GAMS system directory. Use the igdx() function to tell gdxrrw where it can find GAMS. There are multiple ways to do so as explained in the igdx help page:
You can specify the GAMS system directory explicitely. For example:
igdx("C:/GAMS/win64/29.1")
However, we recommended to set the R_GAMS_SYSDIR environment variable. For details see here. After setting R_GAMS_SYSDIR, you should be able to load the GDX libraries by passing an empty string as first argument to igdx():
igdx("")
In the examples that follow, it is assumed that you have set R_GAMS_SYSDIR.
Although not strictly necessary to use globiomvis (for now), we recommend installing the following additional software:
GDAL. (When not on Windows). GDAL is a very powerful translator library for raster and vector geospatial data formats. It is used by several R packages that process raster and vector data and is normally much faster than processing this data within R. GDAL can be downloaded here. Alternatively, on Linux, the packages libgdal-dev and libudunits2-dev can be installed.
OSGeo4W. (Windows) This is a collection of open source geospatial software for Windows that provides GDAL and much more. It can be downloaded here.
MiKTeX is one of the distributions of TeX/LaTeX and related programs. RStudio leverages LaTeX through R Markdown by, for example, rendering PDF documents from R Markdown files via LaTeX. To learn more about this see here.
Unfortunately, the basic MikTeX installer does not install everything that is required. Instead, from the ‘All downloads’ tab on the MiKTeX download page, download the Net Installer and use it to perform a complete installation. This will require roughly 7GB of disk space.
TinyTeX. If you prefer a smaller TeX/LaTeX installation, you can try TinyTeX instead. It has been designed to work well with R. Beware though that TinyTeX is still maturing.
Git version control software. It can be downloaded here. RStudio and Git can be easily linked to version your code. Git repositories can be hosted on GitHub, a cloud platform that facilitates collaborative code development. More information about how to set this up can be found here and here.