climateScenario

Create climate scenario object

Since R2025a

Description

Create a climateScenario object to explore climate scenario data, compute new values, and visualize the data.

After creating a climateScenario object, use the associated object functions in your workflows to:

• Unstack climate scenario data.

• Plot climate scenario data.

• Create new regions.

• Compute sums and differences of variables.

• Compute ratios of variables.

• Compute shocked variables and scenarios.

Creation

Syntax

cs = climateScenario(data)

cs = climateScenario(data,RegionVar=rVar,VariableVar=vVar,ScenarioVar=sVar,YearVar=yVar,ValueVar=valVar,CustomIdenfitifierVars=ciVar)

cs = climateScenario(data,RegionVar=rVar,VariableVar=vVar,ScenarioVar=sVar,YearVar=yVar,ValueVar=valVar,CustomIdenfitifierVars=ciVar,Name=Value)

Description

cs = climateScenario(data) creates a climateScenario object from a table data, that contains the variables Region, Variable, Scenario, Year, and Value.

cs = climateScenario(data,RegionVar=rVar,VariableVar=vVar,ScenarioVar=sVar,YearVar=yVar,ValueVar=valVar,CustomIdenfitifierVars=ciVar) specifies the columns in data that represent the Region, Variable, Scenario, Year, and Value identifiers, including an additional custom identifier column.

cs = climateScenario(data,RegionVar=rVar,VariableVar=vVar,ScenarioVar=sVar,YearVar=yVar,ValueVar=valVar,CustomIdenfitifierVars=ciVar,Name=Value) also specifies optional name-value arguments. You can use the CustomIdentifiers name-value argument to specify additional identifiers contained in data. Use the UnitVar name-value argument to specify a column that contains units in data. For example, cs = climateScenario(data,RegionVar="CL_GEOGRAPHY",VariableVar="CL_VARIABLE",ScenarioVar="CL_SCENARIO",YearVar="CL_YEAR",ValueVar="CL_VALUE",ValueVar="CL_VALUE",CustomIdentifierVars="CL_SECTOR",CustomIdentifiers="Sector",UnitVar="CL_UNIT") specifies Sector as a custom identifier represented by the CL_SECTOR variable and specifies a units column CL_UNIT.

Input Arguments

data — Climate scenario data

table

Climate scenario data, specified as a table. If data does not contain the columns Region, Variable, Scenario, Year, and Value, you can specify the column names by using name-value arguments.

rVar — Name of Region column

"Region" (default) | string scalar

Name of the Region column in data, specified as a string scalar. Use this input argument to represent the Region identifier.

vVar — Name of Variable column

"Variable" (default) | string scalar

Name of the Variable column in data, specified as a string scalar. Use this input argument to represent the Variable identifier.

sVar — Name of Scenario column

"Scenario" (default) | string scalar

Name of the Scenario column in data, specified as a string scalar. Use this input argument to represent the Scenario identifier.

yVar — Name of Year column

"Year" (default) | string scalar

Name of the Year column in data, specified as a string scalar. Use this input argument to represent the Year identifier.

valVar — Name of Value column

"Value" (default) | string scalar

Name of the Value column in data, specified as a string scalar. Use this input argument to represent the Value identifier.

ciVar — Name of custom identifier column

[] (default) | string vector

Name of custom identifier column in data, specified as a string vector. Use this input argument when the name of a custom identifier does not match the name of the corresponding variable in data.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: cs = climateScenario(data,RegionVar="CL_GEOGRAPHY",VariableVar="CL_VARIABLE",ScenarioVar="CL_SCENARIO",YearVar="CL_YEAR",ValueVar="CL_VALUE",CustomIdentifierVars="CL_SECTOR",CustomIdentifiers="Sector") uses the optional CustomIdentifiers name-value argument to specify Sector as an additional identifier.

CustomIdentifiers — Names of custom identifiers

[] (default) | string vector

Names of custom identifiers, specified as a string vector. Use this name-value argument to specify identifiers in addition to Region, Variable, Scenario, and Value. For instance, if you specify CustomIdentifiers="Sector" when you create the object cs, the cs.CustomIdentifiers property contains "Sector" as one of the property values.

UnitVar — Name of Unit column

[] (default) | string scalar

Name of Unit column in data, specified as a string scalar. Use this name-value argument to represent a column in data that contains units.

Output Arguments

cs — Climate scenario object

climateScenario object

Climate scenario object, returned as a climateScenario object which contains the following properties:

• Identifiers — This property contains the Region, Variable, Scenario, and Year identifier values, and any custom identifier values.

• CustomIdentifiers — This property contains any custom identifier values that were specified when creating cs.

• IdentifierValues — Structure with fields for the Region, Variable, Scenario, and Year identifiers, and any custom identifiers. The values of each field are the values of the identifiers.

Properties

Identifiers — Identifiers

string vector

This property is set when you create a climateScenario object. The values are the identifiers Region, Variable, Scenario, Year, and any custom identifiers.

CustomIdentifiers — Names of custom identifiers

string vector

This property is set when you create a climateScenario object. The values contain any custom identifiers you specified when creating the object.

IdentifierValues — Identifier values

structure

This property is set when you create a climateScenario object and contains a structure with fields for the Region, Variable, Scenario, and Year identifiers and any custom identifiers you specified when creating the object.

Object Functions

plot	Plot climate scenario data
query	Return subset of climate scenario data
groupRegions	Group climate scenario regions
sumVariables	Compute weighted sum of climate scenario variables
divideVariables	Compute ratio of climate scenario variables
shockVariables	Shock climate scenario variables relative to reference scenario

Examples

Create Climate Scenario Object from Data Table

Create a climateScenario object using a sample data set from the Bank of Canada (available free of charge at https://www.bankofcanada.ca).

Load the data.

load("BankOfCanadaClimateScenarioData.mat")
data = ClimateTransitionScenarioData;
head(data)

    k    CL_GEOGRAPHY    CL_SECTOR              CL_VARIABLE                    CL_UNIT                CL_SCENARIO           CL_YEAR    CL_VALUE
    _    ____________    _________    _______________________________    ___________________    ________________________    _______    ________

    1       Canada       National     Carbon price                       US$2014/tCO2e          Baseline (2019 policies)     2020       12.106 
    2       Canada       National     Carbon price                       US$2014/tCO2e          Below 2°C immediate          2020       12.106 
    3       Canada       National     Emissions | total GHG (scope 1)    Million tonnes CO2e    Baseline (2019 policies)     2020       781.04 
    4       Canada       National     Emissions | total GHG (scope 1)    Million tonnes CO2e    Below 2°C immediate          2020       781.04 
    5       Canada       National     Input price | Coal                 Index (2014 = 1)       Baseline (2019 policies)     2020       1.2875 
    6       Canada       National     Input price | Coal                 Index (2014 = 1)       Below 2°C immediate          2020       1.2875 
    7       Canada       National     Input price | Crops                Index (2014 = 1)       Baseline (2019 policies)     2020       1.0031 
    8       Canada       National     Input price | Crops                Index (2014 = 1)       Below 2°C immediate          2020       1.0031 

Construct a climateScenario object by specifying an input data table and name-value arguments for the identifier variables.

cs = climateScenario(data, ...
                RegionVar="CL_GEOGRAPHY", ...
                VariableVar="CL_VARIABLE", ...
                ScenarioVar="CL_SCENARIO", ...
                YearVar="CL_YEAR", ...
                ValueVar="CL_VALUE", ...
                CustomIdentifiers="Sector", ...
                CustomIdentifierVars="CL_SECTOR", ...
                UnitVar="CL_UNIT")

cs = 
  climateScenario with properties:

          Identifiers: ["Region"    "Variable"    "Scenario"    "Year"    "Sector"]
    CustomIdentifiers: "Sector"
     IdentifierValues: [1×1 struct]

Retrieve the climate Scenario information by accessing the values of the IdentifierValues field.

cs.IdentifierValues.Scenario

ans = 4×1 categorical
     Baseline (2019 policies) 
     Below 2°C delayed 
     Below 2°C immediate 
     Net-zero 2050 (1.5°C) 

Version History

Introduced in R2025a