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.
There are multiple equivalent ways to install this package:
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.
Requirements
Open R and install the gcamreport
package:
install.packages('devtools')
devtools::install_github('bc3LC/gcamreport')
Now gcamreport
package is fully loaded. Enjoy! :smile:
Note:boom:: If you want to install specific gcamreport
versions, indicate the tag or branch name when running the installation command. For instance:
# to install the tagged 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')
Requirements
Open git bash in the folder where you want to clone the repository and clone it:
git clone https://github.com/bc3LC/gcamreport.git
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! :smile:
Note:boom:: If you want to install specific gcamreport
versions, indicate the tag or branch name when cloning the repository. For instance:
# to clone the tagged 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
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.
Requirements
Open git bash in the folder where you want to clone the repository and clone it:
git clone https://github.com/bc3LC/gcamreport.git
Open Docker Desktop (double-click the icon on your computer) and leave it running in the background.
Inside a terminal (bash or cmd) pull the docker image:
docker pull claudiarodes/gcamreport_docker:gcam-v7.0-v2
Note:exclamation:: This step requires 13.5GB of free space in your computer.
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.
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! :smile:
Note:exclamation:: 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:exclamation:: To reuse the docker image, you can simply perform steps 3, 5, and 6, since the docker image is already on your computer.
Note:exclamation:: 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.
Note:boom:: 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 tagged 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
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.
Some typical and already-known errors that can be easily solved! :bulb:
:computer: 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.
:computer: 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'
:computer: Error when using the UI through Docker installation.
When oppening your localhost, you might see this error:
:computer: 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
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.