Skip to contents

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 designed to generate consistent datasets from any scenario run by the Global Change Analysis Model (GCAM), ensuring they meet the reporting standards of the Integrated Assessment Modeling Consortium (IAMC). In addition, gcamreport features an interactive user interface that allows users to create and download plots in real time and export reduced, formatted datasets in spreadsheet format. The tool is currently compatible with GCAM-core versions 6.0, 7.0, and 7.1, as outlined in the version guide.


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! 😄


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! 😄


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


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 Top common 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.


Top common Warnings and Error Messages

Back to Contents

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

💻 Error on “generate_report(prj_name =”path/to/your/data/myData.dat”)”

In your R console, you might see this error:

  > generate_report("path/to/your/data/myData.dat")
  Loading project...
  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:

    1. make sure that your data is inside the gcamreport folder.

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

    3. 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")


💻 Error on “generate_report(…)”

In your R console, you might see this error:

  > generate_report(...)
  Loading project...
  Loading data, performing checks, and saving output...
  [1] "ag_demand_clean"

  Error in left_join_strict(., filter_variables(get(paste("ag_demand_map", :
    Error: Some rows in the left dataset do not have matching keys in the right dataset.
Possible solution

This problem is due to a mismatch in the ag_demand_map map. Thus, make sure that you specified correctly the GCAM_verions parameter in the generate_report function. If the error persists, have a look at this tutorial.


💻 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:💥 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.