addSingleQuery: Add a data by running a single on a GCAM output database to a...

In JGCRI/rgcam: Tools for importing and working with GCAM results

Add a data by running a single on 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. This function accepts just a single query to be run as apposed to a batch file with several queries. This is typically provided as the XML typically found in the Main_queries.xml. See examples for possible syntax to specify these.

Usage

addSingleQuery(
  conn,
  proj,
  qn,
  query,
  scenario = NULL,
  regions = NULL,
  clobber = FALSE,
  transformations = NULL,
  saveProj = TRUE,
  warn.empty = TRUE
)

Arguments

conn	A GCAM database to connection extract scenario from.
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.
qn	The query name to use when storing the results. We have to provide this since it might not always be obvious what this is by looking at the query.
query	A Model Interface query to run. See examples for possible syntax.
scenario	Name of scenario to extract. If NULL, use the last scenario in the GCAM database.
regions	A list of regions to query. If NULL, all regions will be 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.
warn.empty	Flag: issue warning when a query returns an empty table

Details

The date value will be clipped from the scenario name and discarded. If a newly-read scenario/query is a duplicate of one already in the file, the operation will fail unless clobber = TRUE, in which case the old data 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 transformation as a function object, the 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 updated project will also be returned from the function so that it can be used without having to reread it.

Value

The project dataset with the new scenario added.

Examples

# The query must be the same XML found in a GCAM query file:
SAMPLE.GCAMDBLOC <- system.file("extdata",package="rgcam")
db_connection <- localDBConn(SAMPLE.GCAMDBLOC, "sample_basexdb")
query_name <- "CO2 concentrations"
co2_query <- '<ClimateQuery title="CO2 concentrations">
                <axis1 name="CO2-concentration">none</axis1>
                <axis2 name="Year">CO2-concentration[@year]</axis2>
                <xPath buildList="true" dataName="CO2-concentration" group="false" sumAll="false">climate-model/CO2-concentration/text()</xPath>
                <comments/>
              </ClimateQuery>'
addSingleQuery(db_connection, "test.proj", query_name, co2_query)

# However it could also be given for instance as a query string that will result in such XML:
SAMPLE.QF <- system.file("ModelInterface", "sample-queries-interactive.xml", package="rgcam")
co2_query <- paste0("doc('", SAMPLE.QF, "')//*[@title='",
                    query_name, "']")
addSingleQuery(db_connection, "test.proj", query_name, co2_query)

# Alternatively a user may use an XML package if for instance their query file is
# stored locally but are running queries on some remote machine:
library(xml2)
queries <- read_xml(SAMPLE.QF)
co2_query <- xml_find_first(queries, paste0("//*[@title='", query_name, "']"))
addSingleQuery(db_connection, "test.proj", query_name, co2_query)

JGCRI/rgcam documentation built on July 2, 2022, 10:20 a.m.