Skip to contents

README for gcamreport v6.0*

Source: vignettes/README_v6-0.Rmd
README_v6-0.Rmd

gcamreport

docs pages-build-deployment test_coverage codecov docker buildDOI

ATTENTION: this README is compatible with gcamreport v6.0*, i.e, with gcamreport v6.0.0, gcamreport v6.0.1, and gcamreport v6.0.0-gas releases. For other releases, please check in the Tutorials drop-down menu or the home icon in the main bar.

newline

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), which meets the reporting requirements of the Integrated Assessment Modeling Consortium (IAMC). Additionally, gcamreport includes an interactive user widget that allows users to create and download plots, as well as to download reduced versions of the formated dataset in table format.

Installation Guide

Back to Contents

There are two equivalent possibilities to make use of this package:

With R

  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 specifying the branch or the tag.

To specify the branch (gcam-v6.0 or gcam-v6.0-gas):

git clone -b <branch name> https://github.com/bc3LC/gcamreport.git

To specify the tag (v6.0.0, v6.0.1 or v6.0.0-gas):

git clone https://github.com/bc3LC/gcamreport.git
git checkout tags/<tag name>

  1. Load gcamreport package. There are two options:

    1. 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()
    1. Open Rstudio (it does not matter the Rproject) and load the library spcifying the branch or the tag:
    install.packages('remotes')
remotes::install_github("bc3LC/gcamreport@<branch or tag name>") #you can skip all updates in case you are asked
library(gcamreport)


Now gcamreport package is fully loaded. Enjoy! :smile:


With Docker

  1. Requirements

    • Docker (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 specifying the branch or the tag.

To specify the branch (gcam-v6.0 or gcam-v6.0-gas):

git clone -b <branch name> https://github.com/bc3LC/gcamreport.git

To specify the tag (v6.0.0, v6.0.1 or v6.0.0-gas):

git clone https://github.com/bc3LC/gcamreport.git
git checkout tags/<tag name>

  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:v3

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:v3

This should prompt an R terminal in your console.

  1. Install the gcamreport package spcifying the branch or the tag in the new R console:
remotes::install_github("bc3LC/gcamreport@<branch or tag name>") #you can skip all updates in case you are asked
library(gcamreport)

Note: the local files to be accessed must be inside the gcamreport folder, which is considered now as the root directory of the R session. Inside the R session, it is referred to as /app.

Note: to use again the docker image, you can simply run steps 3, 5 and 6, since the docker image is already on your computer.

Now gcamreport package is fully loaded. Enjoy! :smile:


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 IAMC. Main function: run(). For more information look at this tutorial or type ?run in your R console. If you obtain some warning or error messages, it might be useful to look at the Warning and Error Messages section.

  • Interactive user block: it launches an interactive widget to display in table format the dataset, with the possibility to filter, reorder, and download live. Moreover, it displays plots and allows them to be downloaded, aggregated by variables, regions, and scenarios. Main function: launch_gcamreport_ui(). For more information look at this tutorial or type ?launch_gcamreport_ui in your R console. If you obtain some warning or error messages, it might be useful to look at the Warning and Error Messages section.

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

UI error

In addition, the package includes some default input files (.Rda), that are read by the different functions. These can be changed by the user. Some of these constants include energy shares, land shares, and others.


Warning and Error Messages

Back to Contents

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

A) Error on “run(”path/to/your/data/myData.dat”)”

In your R console, you might see this error:

  > run("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:

    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
  run("/app/amazingData/myData.dat")
  
  # option 2: partial path
  run("amazingData/myData.dat")


B) Wired message when launching the UI when using the Docker installation.

After using the functions run() 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.


C) 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 run() function or the launch_gcamreport_ui().


D) 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.