Getting Started with gcamdata

2022-08-17

Source: vignettes/getting-started/getting-started.Rmd

R

R must be version 3.2 or higher (however current testing is done with version 3.6.3 and above).

We suggest using RStudio.

Clone this repository

On the command line: navigate to your desired folder location and then enter git clone https://github.com/JGCRI/gcamdata.git

If using GitHub Desktop: Go to https://github.com/jgcri/gcamdata and click the green “Code” button. Then click “Open with GitHub Desktop”.

Loading the gcamdata package

Open the gcamdata folder you just cloned and double-click the gcamdata.Rproj file. RStudio should open the project.

If you have not installed devtools before, first enter the following into the R console

install.packages("devtools")

Then to load the gcamdata package, enter:

devtools::load_all()

Package dependencies

You may also need to install package dependencies, for example using:

devtools::install_deps()

However, there are known issues with some recent package dependencies (i.e. readr 2.0, tidyr 1.2)

For this reason, we suggest using renv, described below.

Optional renv – currently included in GCAM 6.0 and gcamdata release

renv is an R package for dependency management. Using it will save a private R library with the correct versions of any package dependencies.

The steps to use renv include:

  1. Install renv package (if not already installed)
install.packages( "https://cran.r-project.org/src/contrib/Archive/renv/renv_0.12.5.tar.gz", repos = NULL, type = "source" )
  1. Initialize a local library (may prompt you to restart your R session)
renv::init( bare = TRUE)
  1. Install the correct packages (this may take some time)
renv::restore()

You should now be set to run the driver without running into any package version issues. Note that if you have completed these steps once, your R session should automatically connect to this private library when you open gcamdata.Rproj. If your R session doesn’t connect to this (for example, if you changed branches), you can run the following to reconnect to this private library:

renv::activate()

See a video tutorial here:

Run the driver

You should now be ready to run the driver, which is the main processing function that generates intermediate data outputs and xml files for GCAM. There are two ways to run the driver:

driver_drake() runs the driver and stores the outputs in a hidden cache. When you run driver_drake() again it will skip steps that are up-to-date. This is useful if you will be adjusting the data inputs and code and running the data system multiple times. For this reason, we almost always recommend using driver_drake(). More details can be found in the vignette.

See the documentation for more options when running the driver, such as what outputs to generate or when to stop.