Package 'piamValidation'

Validation Tools for PIK-PIAM

Description

The piamValidation package provides validation tools for the Potsdam Integrated Assessment Modelling environment.

Author(s)

Maintainer: Pascal Weigmann [email protected] (ORCID) (affiliation: Potsdam Institute for Climate Impact Research)

Authors:

• Pascal Weigmann [email protected] (ORCID) (affiliation: Potsdam Institute for Climate Impact Research)

• Oliver Richters (ORCID) (affiliation: Potsdam Institute for Climate Impact Research)

• Fabrice Lécuyer (ORCID) (affiliation: Potsdam Institute for Climate Impact Research)

• Johannes Koch (ORCID) (affiliation: Potsdam Institute for Climate Impact Research)

See Also

Useful links:

• https://github.com/pik-piam/piamValidation

• https://pik-piam.github.io/piamValidation

---

construct tooltips for interactive plots

Description

construct tooltips for interactive plots

Usage

appendTooltips(df)

Arguments

df	data.frame as returned from 'validateScenarios()'

---

Average 2020 to smoothen Covid shock in historical data

Description

Adds a new model for each model in reference data with smoothed 2020 period and name "<model>_smoothed".

Usage

average_2020(hist)

Arguments

hist	reference data as used in “validateScenarios()“

---

Warn if reference data required by the config is missing from input data

Description

Compares the reference models of all historical checks in the config against the models found in the reference data provided by the user (scenario "historical") and warns about missing ones. If reference data files shipped with the package contain the missing models, they are suggested.

Usage

checkRefData(cfg, hist)

Arguments

cfg	processed config as used in “validateScenarios()“
hist	historical/reference data as used in “validateScenarios()“

---

Check variable consistency

Description

Test whether unit of on row of config and data for this variable match.

Usage

checkUnits(data, cfgRow)

Arguments

data	scenario or reference data for one variable
cfgRow	one row of a config file containing the same variable as the data object

---

Combine scenario and reference data with thresholds

Description

for one row of cfg: filter and merge relevant scenario data with cfg results in one df that contains scenario data, reference data and thresholds

Usage

combineData(scenData, cfgRow, histData = NULL)

Arguments

scenData	scenario data for one variable
cfgRow	one row of a config file
histData	reference data

---

Import SCI criteria and convert to config

Description

Use installed "scenario-evaluation-criteria" package to convert threshold criteria from Scenario Compass release to a piamValidation config and a reference data .rds file

Usage

convertSCIcriteria(version = "2026.8.3")

Arguments

version

criteria version that should be converted to config

---

import a config shipped with the package

Description

get a validation config file either from "inst/config" (.csv) or by providing a full path (.csv or .xlsx) or a tibble with the necessary columns see README or vignette for rules on how to fill the config

Usage

getConfig(config)

Arguments

config

name of validation config from "inst/config"

---

takes the output of "validateScenarios()" and computes threshold bands

Description

converts the thresholds attached to each data point by “validateScenarios()“ into absolute values per variable, unit, region and period. The resulting bands can be plotted as colored background areas behind scenario data, see “linePlotThresholds()“ or the “thresholds“ argument of “mip::createLinePlots()“.

Usage

getThresholdBands(valiData, warnMultiple = TRUE)

Arguments

valiData	data.frame as returned by “validateScenarios()“
warnMultiple	if TRUE, warn in case multiple sets of thresholds are found for the same variable, unit, region and period, e.g. from checks using multiple metrics or reference scenarios; plotting such bands can lead to overlaps

Details

For checks using the metrics "relative" and "difference", thresholds are converted into absolute values using the reference values of the respective check. Thresholds which are not defined in the config appear as -Inf/Inf.

Value

data.frame with columns variable, unit, region, period, min_red, min_yel, max_yel and max_red

---

import IAM data for validation

Description

import IAM data for validation

Usage

importScenarioData(scenarioPath, variables = NULL)

Arguments

scenarioPath	one or multiple paths to .mif, .csv, .rds or .xlsx file(s) or a data.frame containing scenario data in IAM format
variables	optional character vector of variable names (may contain "*" wildcards as in the config); if given, all other variables are dropped while reading so that only the data needed for the validation is held in memory

---

takes the output of "validateScenarios()" creates a line plot

Description

takes the output of "validateScenarios()" creates a line plot

Usage

linePlotThresholds(
  valiData,
  scenData = NULL,
  refData = NULL,
  xlim = c(2010, 2030),
  interactive = TRUE
)

Arguments

valiData	data to be plotted, as returned by “validateScenarios()“ and after filtering for one variable and one region.
scenData	hand over additional scenario data to be plotted alongside the validation data. Will use the same variable and region, otherwise all available data.
refData	hand over additional reference data to be plotted alongside the validation data. Will use the same variable and region, otherwise all available data.
xlim	set limits for the x axis
interactive	decide if an interactive ggploty object should be returned

---

List available configs

Description

List all validation configuration files that are delivered with the package and can be directly imported with “getConfig()“ or used in “validateScenarios()“ and “validationReport()“.

Usage

listConfigs()

Value

character vector of config names

---

List available reports

Description

List all validation report templates (.Rmd) that are delivered with the package and can be used as “report“ in “validationReport()“.

Usage

listReports()

Value

character vector of report names

---

evaluate the content of the "ref_<type>" column and filter reference data accordingly. cases: - mode chosen - range - mean - no mode chosen - use mean if multiple references

Description

returns df without variable, unit and <type> columns (see below) returns df with ref_value_min/max, ref_model, ref_scenario, ref_period

Usage

refineRefData(ref_data, cfgRow, ref_type = "ref_model")

Arguments

ref_data	pre-filtered reference data
cfgRow	row of validation config used for this data slice
ref_type	historical, model, scenario, period

---

Print a summary of the input data

Description

Print multiple metrics of all data objects given to “validateScenarios()“ which might be helpful to spot and fix data inconsistencies.

Usage

showInputSummary(scen, hist, config)

Arguments

scen	scenario data as used in “validateScenarios()“
hist	historical/reference data as used in “validateScenarios()“
config	config as used in “validateScenarios()“

---

performs the validation checks from a config on a scenario data set

Description

performs the validation checks from a config on a scenario data set

Usage

validateScenarios(
  dataPath,
  config,
  outputFile = NULL,
  extraColors = TRUE,
  giveSummary = FALSE
)

Arguments

dataPath	one or multiple path(s) to scenario data in .mif or .csv format, in case of historic comparison, also path to reference data
config	select config from inst/config or give a full path to a config file on your computer
outputFile	give name of output file in case results should be exported; include file extension
extraColors	if TRUE, use cyan and blue for violation of min thresholds instead of using the same colors as for max thresholds (yel and red)
giveSummary	print a summary of input data via “showInputSummary()“ which allows spotting data inconsistencies

---

takes the output of "validateScenarios()" and plots heat maps per variable

Description

takes the output of "validateScenarios()" and plots heat maps per variable

Usage

validationHeatmap(
  valiData,
  main_dim = "variable",
  x_plot = NULL,
  y_plot = NULL,
  x_facet = NULL,
  y_facet = NULL,
  interactive = TRUE
)

Arguments

valiData	data to be plotted, as returned by “validateScenarios()“ (and “appendTooltips()“ if interactive), plus optional filtering. Needs to have at least one dimension with only one unique element.
main_dim	out of the 5-dim df, 1 dim has to contain only on element, this is the main dimension of the plot, default: variable
x_plot	choose dimension to display on x-axis of plot, if any is NULL, arrangement is chosen automatically based on data dimensions
y_plot	choose dimension to display on y-axis of plot
x_facet	choose dimension to display on x-dim of facets
y_facet	choose dimension to display on x-dim of facets
interactive	return plots as interactive plotly plots by default

---

returns information on whether scenarios passed critical validation checks

Description

returns information on whether scenarios passed critical validation checks

Usage

validationPass(data, yellowFail = FALSE)

Arguments

data	data.frame as returned from “validateScenarios()“
yellowFail	if set to TRUE a yellow check result of a critical variable will lead to the scenario not passing as validated

---

perform validateScenarios and create an .html report using .Rmd templates

Description

perform validateScenarios and create an .html report using .Rmd templates

Usage

validationReport(
  dataPath,
  config,
  report = "default",
  outputDir = "output",
  extraColors = TRUE,
  giveSummary = FALSE
)

Arguments

dataPath	one or multiple path(s) to scenario data in .mif or .csv format
config	name a config from inst/config ("validationConfig_<name>.csv") or give a full path to a separate configuration file
report	name a .Rmd from inst/markdown ("validationReport_<name>.Rmd") to be rendered or give a full path to a separate .Rmd file
outputDir	choose a directory to save validation reports to
extraColors	if TRUE, use cyan and blue for violation of min thresholds instead of using the same colors as for max thresholds (yel and red)
giveSummary	print a summary of input data via “showInputSummary()“ which allows spotting data inconsistencies

---