/gcamreport

Package to process GCAM results and standardize the format

Primary LanguageRMIT LicenseMIT

gcamreport

Project Status: Active – The project has reached a stable, usable state and is being actively developed. docs pages-build-deployment test_coverage codecov docker build DOI paper status

Contents

Introduction

Back to Contents

gcamreport is a tool that generates a consistent dataset from any scenario run by the Global Change Analysis Model (GCAM) that meets the reporting requirements of the Integrated Assessment Modeling Consortium (IAMC). In addition, gcamreport includes an interactive user widget that allows users to generate and download plots live, as well as download reduced versions of the formatted dataset in spreadsheet format.

Installation Guide

Back to Contents

There are multiple equivalent ways to install this package:

With R

There are two ways to install the gcamreport package through R. The light mode installation requires only R as it installs the gcamreport package directly from the GitHub repository. It is suitable for general use of the package but not compatible with the user interface. The full mode installation requires R, Rstudio and cloning the GitHub repository. It is suitable for general use of the package and allows you to launch the user interface. It is also the best option if you are actively developing or modifying the gcamreport package, as it allows you to modify the mappings and functions to create suitable versions for your GCAM model.

Light mode installation

  1. Requirements

    • R (to download, click here)

  2. Open R and install the gcamreport package:

install.packages('devtools')
devtools::install_github('bc3LC/gcamreport')

Now gcamreport package is fully loaded. Enjoy! 😄

Note💥: If you want to install specific gcamreport versions, indicate the tag or branch name when running the installation command. For instance:

# to install the taged version "v6.0.1"
devtools::install_github('bc3LC/gcamreport@v6.0.1')

# to install the branch version "gcam-v6.0"
devtools::install_github('bc3LC/gcamreport@gcam-v6.0')

Full mode installation

  1. Requirements

    • R (to download, click here)

    • Rstudio (to download, click here)

    • Git (to download, click here)

  2. Open git bash in the folder where you want to clone the repository and clone it:

git clone https://github.com/bc3LC/gcamreport.git
  1. Load the gcamreport package: Open the gcamreport folder you just cloned and double-click the gcamreport.Rproj file. RStudio should open the project. Load the library:
install.packages('devtools')
devtools::load_all()

Now gcamreport package is fully loaded. Enjoy! 😄

Note💥: If you want to install specific gcamreport versions, indicate the tag or branch name when cloning the repository. For instance:

# to clone the taged version "v6.0.1":
git clone --branch v6.0.1 --single-branch https://github.com/bc3LC/gcamreport.git

# to clone the branch version "gcam-v6.0":
git clone --branch gcam-v6.0 https://github.com/bc3LC/gcamreport.git

With Docker

This installation method allows you not to worry about the R libraries and dependencies. Docker provides you with an already updated environment suitable for running the gcamreport package.

  1. Requirements

    • Docker Desktop (to download, click here)

    • Git (to download, click here)

  2. Open git bash in the folder where you want to clone the repository and clone it:

git clone https://github.com/bc3LC/gcamreport.git

  1. Open Docker Desktop (double-click the icon on your computer) and leave it running in the background.

  2. Inside a terminal (bash or cmd) pull the docker image:

docker pull claudiarodes/gcamreport_docker:gcam-v7.0-v2

Note❗: This step requires 13.5GB of free space in your computer.

  1. Run the Docker container using your full path to the gcamreport folder:
docker run -v /path/to/gcamreport:/app -p 4000:3838 -it claudiarodes/gcamreport_docker:gcam-v7.0-v2

This should prompt an R console in your terminal.

  1. Install the gcamreport package in the new R console:
remotes::install_github("bc3LC/gcamreport") #you can skip all updates in case you are asked
library(gcamreport)

Now gcamreport package is fully loaded. Enjoy! 😄

Note❗: To access local files, you should place them in the gcamreport folder, which is now considered the root of the R session. Inside the R session it is referred to as /app.

Note❗: To reuse the docker image, you can simply perform steps 3, 5, and 6, since the docker image is already on your computer.

Note❗: If you followed the Docker installation, to open the user interface (UI) once it has been launched, either go to the Docker Desktop and type the last port started, or type http://localhost:4000 in your browser.

UI error

Note💥: If you want to install previous gcamreport versions, indicate the tag or branch name when cloning the repository (step 2). For instance:

# to clone the taged version "v6.0.1":
git clone --branch v6.0.1 --single-branch https://github.com/bc3LC/gcamreport.git

# to clone the branch version "gcam-v6.0":
git clone --branch gcam-v6.0 https://github.com/bc3LC/gcamreport.git

Getting Started

Back to Contents

The gcamreport package consists of a set of functions divided into two different blocks:

  • Dataset generation: It creates or loads an existing project and automatically saves the generated dataset that meets the reporting requirements of the IAMC. Main function: generate_report(). For more information, see this tutorial or type ??generate_report in your R console. If you get any warning or error messages, you might want to look at the Warnings and Error Messages section.

  • Interactive user block: it launches an interactive widget that displays the dataset in tabular form, with the ability to filter, reorder and download live. It also displays plots and allows them to be downloaded, aggregated by variables, regions and scenarios. Main function: launch_gcamreport_ui(). For more information see this tutorial or type ??launch_gcamreport_ui in your R console. If you get any warning or error messages, it might be useful to have a look at the Warnings and Error Messages section.

The package also includes some default input files (.Rda) that are read by the different functions. These can be changed by the user as detailed in this tutorial.


Warnings and Error Messages

Back to Contents

Some typical and already-known errors that can be easily solved! 💡

💻 Error on "run("path/to/your/data/myData.dat")"

In your R console, you might see this error:

  > generate_report("path/to/your/data/myData.dat")
  [1] "Loading project..."
  [1] "Loading data, performing checks, and saving output..."
  [1] "ag_demand_clean"
  Error in rgcam::getQuery(prj, "demand balances by crop commodity") :
    getQuery: Query demand balances by crop commodity is not in any scenarios in the data set.
**Possible solution**

This problem is due to a wrong path specification. Thus, make sure that you specified correctly the path. In addition:

  • In case you are using gcamreport package following the R installation, try to copy the whole path to your data, for instance C:\Users\username\Documents\path\to\your\data\myData.dat if you are using a Windows distribution.

  • In case you are using gcamreport package following the Docker installation:

    a) make sure that your data is inside the gcamreport folder.

    b) make sure that you type correctly the path to your gcamreport folder when running the docker image (5th step in the Docker section)

    c) make sure that you are pointing correctly to your data. For example, if in the gcamreport folder you have a folder called amazingData with your dataset myData.dat, you should refer to it as

  # option 1: full path
  generate_report("/app/amazingData/myData.dat")
  
  # option 2: partial path
  generate_report("amazingData/myData.dat")

💻 Wired message when launching the UI when using the Docker installation.

After using the functions generate_report() or launch_gcamreport_ui() to launch the UI, you might get this message:

  Listening on http://0.0.0.0:3838
  /usr/bin/xdg-open: 882: www-browser: not found
  /usr/bin/xdg-open: 882: links2: not found
  /usr/bin/xdg-open: 882: elinks: not found
  /usr/bin/xdg-open: 882: links: not found
  /usr/bin/xdg-open: 882: lynx: not found
  /usr/bin/xdg-open: 882: w3m: not found
  xdg-open: no method available for opening 'http://127.0.0.1:3838'
**Possible solution**

This is not an error! You simply need to either go to your Docker Desktop program and click the last started port

UI error

or open this url http://localhost:4000 in your favourite browser.


💻 Error when using the UI through Docker installation.

When oppening your localhost, you might see this error:

UI error

**Possible solution**

Your UI is not running. Try to either use the generate_report() function or the launch_gcamreport_ui().


💻 Error related to system when using the Docker installation.

Once the R console is opened, you might see this message after introducing any command:

  System has not been booted with systemd as init system (PID 1). Can't operate.
  Failed to connect to bus: Host is down
  Warning message:
  In system("timedatectl", intern = TRUE) :
     running command 'timedatectl' had status 1
**Possible solution**

Simply type Ctrl+C and run your command again.


Note::boom: For other errors, please check the troubleshooting sections of the generate_report function or the user interface widget. If your error is not listed, please open an Issue on the GitHub page with all the information to reproduce the crash.