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`.