addScenario: Add a scenario from a GCAM output database to a project data...
In JGCRI/rgcam: Tools for importing and working with GCAM results

addScenario

R Documentation

Add a scenario from a GCAM output database to a project data set

Description

This function will run the GCAM Model Interface to extract the query data for a scenario in a GCAM output database. The query data is added to a project data file. You can optionally specify an XML file of queries to run; otherwise, the built-in default queries will be run. The resulting data file will be suitable for loading into the dashboard's user interface. It is not necessary, or even helpful, to load a project file before adding a scenario to it.

Usage

addScenario(
  conn,
  proj,
  scenario = NULL,
  queryFile = NULL,
  clobber = FALSE,
  transformations = NULL,
  saveProj = TRUE,
  saveProjEach = FALSE,
  warn.empty = TRUE
)

Arguments

`conn`	A GCAM database to extract scenario from. This can be either a filename or a connection opened with localDBConn or remoteDBConn. If a filename is passed, it will be opened as a local connection.
`proj`	Project to add extracted results to. Can be either a project data structure or the name of a project data file. The file will be created if it doesn't already exist.
`scenario`	Name of scenario to extract. If `NULL`, use the last scenario in the GCAM database.
`queryFile`	XML query file to pass to the GCAM Model Interface. If `NULL`, use a default query file containing commonly used queries.
`clobber`	If `TRUE`, overwrite any existing scenario of the same name; otherwise, fail if `scenario` already exists in the data set.
`transformations`	Transformation functions to apply to the queries (see details).
`saveProj`	A flag to save the project to disk after data has been added. A user may want to avoid it if they are for instance calling this method several times and would prefer to save at the end. Users can always save at anytime by calling `saveProject`.
`saveProjEach`	A flag to save the project to disk after each query has completed. This would be useful if a user suspects a failure in the middle of running queries and would like to not loose progress made.
`warn.empty`	Flag: issue warning when a query returns an empty table

Details

The scenario being added to the project data set is not checked to verify that it has the same queries as previously existing scenarios. Having a mismatch in the queries available between scenarios is not a problem for looking at individual scenario results, but may cause an error when looking at difference plots between scenarios, which presume that the query being displayed exists in both data sets.

The date value will be clipped from the scenario name and discarded. If a newly-read scenario is a duplicate of one already in the file, the operation will fail unless clobber = TRUE, in which case the old scenario will be silently overwritten.

You may optionally specify transformations to apply to the tables returned by the model interface. Examples of transformations you might want to apply include aggregating values or dropping unused columns. Specify transformations as a named list of function objects, where the names in the list indicate which queries the transformations will be applied to. Each function should take a single argument, which will be the original table and should return the modified table as a data frame. Do not drop the "scenario" column as part of one of your transformations; certain types of plots need it.

If everything goes as expected, the new scenario will be added to the data set and written back into the project data file. The new data set will also be returned from the function so that it can be used without having to reread it.