Skip to contents

Main function for generating a GCAM project report. This function handles: - Creating or loading a GCAM project. - Standardizing the data and saving it in RData, CSV, and XLSX formats. - Running vetting verifications. - Launching the User Interface (UI).

Usage

generate_report(
  db_path = NULL,
  db_name = NULL,
  prj_name,
  scenarios = NULL,
  final_year = 2100,
  desired_variables = "All",
  inverse_desired_variables = FALSE,
  ignore = NULL,
  desired_regions = "All",
  desired_continents = "All",
  save_output = TRUE,
  output_file = NULL,
  launch_ui = TRUE,
  interactive = F,
  GCAM_version = "v8.2",
  GWP_version = "AR6",
  scenariocompass_evaluation = FALSE,
  scenariocompass_regions = NULL,
  scenariocompass_scenarios = NULL,
  queries_general_file = NULL,
  queries_nonCO2_file = NULL,
  all_tier1 = F
)

Arguments

db_path

A character string specifying the full path to the GCAM database. Required if creating a new project.

db_name

A character string specifying the name of the GCAM database. Required if creating a new project.

prj_name

A character string specifying the name of the GCAM project. Can be an existing project name (loads the project) or a new project name (creates a new project). Accepts `.dat` extensions.

scenarios

A character vector of specific scenarios to consider. If `NULL` (default), all scenarios present in the project or database are evaluated.

final_year

A numeric value specifying the final reporting year. Defaults to `2100`. Note: `final_year` must be at least `2025` and must align with available 5-year intervals (e.g., 2025, 2030, 2035).

desired_variables

A character vector of variables to include in the report. Defaults to `'All'`. Run `available_variables()` to view all possibilities. Note 1: You can use the `*` notation (as detailed in the [Dataset Generation Tutorial](https://bc3lc.github.io/gcamreport/articles/Dataset_Generation_Tutorial.html#example-5-specify-the-variables)) to select multiple variables from the same family. Note 2: Global variables like `"Emissions"` will only aggregate the selected sub-variables. For example, if you select `"Emissions"` and `"Emissions|CO2"`, `"Emissions"` will only account for CO2 and will ignore missing variables like `"Emissions|CH4"`. Note 3: Specify `'SCI'` to automatically include all variables required for the Scenario Compass evaluation (see the `scenariocompass_evaluation` parameter).

inverse_desired_variables

Logical (`TRUE`/`FALSE`). If `TRUE`, the report will include all available variables *except* those explicitly listed in `desired_variables`. Defaults to `FALSE`.

ignore

A character vector of user-introduced policy names to ignore during processing of physical quantities. Otherwise, unmapped policies will trigger an error. Note: This mimics the behavior of adding the policy names or residual outputs to mapping files as `NoReported`.

desired_regions

A character vector of specific regions to include in the report. Defaults to `'All'`. Run `available_regions()` to view all possibilities. Note: The generated dataset will restrict `"World"` totals to only include these specified regions.

desired_continents

A character vector of continent/region groups to include in the report. Defaults to `'All'`. Run `available_continents()` to view all possibilities. Note: The generated dataset will restrict `"World"` totals to only include these specified regional groups.

save_output

Logical (`TRUE`/`FALSE`) or a character string (`'csv'`, `'xlsx'`). Determines whether the resulting dataset should be saved to disk. If `'csv'` or `'xlsx'`, the data is saved exclusively in that format. Defaults to `TRUE` (saves both).

output_file

A character string specifying the full file path and name for the saved data. If `NULL`, it defaults to the directory of the database or project file, appending `'standardized'` to the filename. Extension will be automatically added.

launch_ui

Logical (`TRUE`/`FALSE`). Determines whether to automatically launch the User Interface upon completion. Defaults to `TRUE`.

interactive

Logical (`TRUE`/`FALSE`). If `TRUE`, the console will pause and ask for user input when warnings appear. If `FALSE`, warnings are collected and displayed silently at the end of the script execution. Defaults to `FALSE`.

GCAM_version

A character string specifying the GCAM version used for regional mappings and queries (e.g., `'v8.2'`). Run `available_GCAM_versions()` to see supported options. Defaults to `'v8.2'`.

GWP_version

A character string specifying the Global Warming Potential (GWP) version. Supported options are `'AR4'`, `'AR5'`, or `'AR6'`. Defaults to `'AR6'`.

scenariocompass_evaluation

Logical (`TRUE`/`FALSE`). Determines whether to evaluate the standardized output against the Scenario Compass criteria. Defaults to `FALSE`.

scenariocompass_regions

A character vector of specific regions to assess during the Scenario Compass evaluation. Only used if `scenariocompass_evaluation` is `TRUE`. If `NULL` (the default), it evaluates all regions present in the standardized dataset. You can provide `'World'`, `'Regional'`, or specific GCAM region names.

scenariocompass_scenarios

A character vector of specific scenarios to assess during the Scenario Compass evaluation. Only used if `scenariocompass_evaluation` is `TRUE`. If `NULL` (the default), all scenarios present in the standardized dataset are evaluated.

queries_general_file

A character string specifying the full path to a general XML query file (including name and extension). If `NULL` (the default), it uses a default query file compatible with the specified `GCAM_version` to report all standardized variables.

queries_nonCO2_file

A character string specifying the full path to an XML query file (including name and extension) for non-CO2 long queries. If `NULL` (the default), it uses a default non-CO2 query file compatible with the specified `GCAM_version`.

all_tier1

Logical (`TRUE`/`FALSE`). If `TRUE`, forces all Tier 1 Variables to be introduced into the standardized report with a value of `0`. Defaults to `FALSE`.

Value

A data frame containing the standardized GCAM reporting dataset, filtered and processed according to the specified variables, regions, and scenarios. If `scenariocompass_evaluation` is `TRUE`, another dataset will be produced to include the evaluation criteria outcomes. Notice the function may save the dataset to disk (if `save_output` is enabled) and launch the interactive User Interface (if `launch_ui` is `TRUE`).

Details

You can specify the regions and/or variables to be reported and provide: - Either `db_path`, `db_name`, `prj_name`, and `scenarios` to create a new project and generate the report. - Or `prj_name` and `scenarios` to produce a report from an existing project.

The resulting RData output can be used to manually call `launch_gcamreport_ui`.