shockVariables

Shock climate scenario variables relative to reference scenario

Since R2025a

Syntax

cs = shockVariables(cs,referenceScenario,Name=Value)

Description

cs = shockVariables(cs,referenceScenario,Name=Value) applies a shock to a variable in the climateScenario object, cs, against a reference scenario and appends the new variable to the property cs.IndentifierValues.Variable. The function computes the shock by taking the difference of a specified variable relative to a reference scenario. For example, cs = shockVariables(cs,referenceScenario,Variable="Carbon price") shocks the carbon price variable against the reference scenario contained in referenceScenario.

.

Examples

Shock Climate Scenario Variable

Shock the values of a climateScenario object variable, relative to a reference scenario. The climate transition scenario data that this example uses is available from the Bank of Canada and is free of charge at http://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 

Create a climateScenario object.

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");

Use shockVariables to shock the Carbon price variable against a reference scenario, Baseline (2019 policies), by using the Variable name-value argument.

referenceScenario = "Baseline (2019 policies)";
cs = shockVariables(cs,referenceScenario,Variable="Carbon price");

To display the new variable, first query the output climateScenario object, cs, for the variable Carbon price Shocked Against Baseline (2019 policies) by using the query function. Then display the last few rows.

 shockedCarbonPrices = query(cs,Variable="Carbon price Shocked Against Baseline (2019 policies)");
 tail(shockedCarbonPrices)

      CL_GEOGRAPHY       CL_SECTOR                         CL_VARIABLE                             CL_UNIT             CL_SCENARIO         CL_YEAR    CL_VALUE
    _________________    _________    _____________________________________________________    _______________    _____________________    _______    ________

    Rest of the world    National     Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2050        30.65 
    Global               Global       Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2020            0 
    Global               Global       Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2025       23.442 
    Global               Global       Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2030       24.195 
    Global               Global       Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2035        20.19 
    Global               Global       Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2040        19.26 
    Global               Global       Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2045       26.098 
    Global               Global       Carbon price Shocked Against Baseline (2019 policies)    Relative Change    Net-zero 2050 (1.5°C)     2050       39.005 

Input Arguments

cs — Climate scenario object

climateScenario object

Climate scenario object, specified as a climateScenario object.

referenceScenario — Reference scenario

string scalar

Reference scenario, specified as a string scalar. The function uses the reference scenario as a baseline to compute relative differences for a given variable. You select the reference scenario by choosing a value from the property cs.IdentifierValues.Scenario.

Example: referenceScenario = "Baseline (2019 policies)"

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 = shockVariables(cs,referenceScenario,Variable="Carbon price") shocks the carbon price against the reference scenario contained in referenceScenario.

Region — Region identifier values

all unique values of Region (default) | string vector

Region identifier values, specified as a string vector. By default, all the regions are returned if you do not specify a string vector for Region.

Variable — Variable identifier values

all unique values of Variable (default) | string vector

Variable identifier values, specified as a string vector. By default, all the variables are returned if you do not specify a string vector for Variable.

Scenario — Scenario identifier values

all unique values of Scenario (default) | string vector

Scenario identifier values, specified as a string vector. By default, all the scenarios are returned if you do not specify a string vector for Scenario.

Year — Year identifier values

all unique values of Year (default) | numeric vector

Year identifier values, specified as a numeric vector. By default, all the years are returned if you do not specify a numeric vector for Year.

CustomIdentifiers — Names of custom identifiers

cs.CustomIdentifiers (default) | string vector

Names of custom identifiers, specified as a string vector containing values of cs.CustomerIndentifiers. CustomIdentifers must match an identifier property contained in cs.CustomIdentifiers. For example, if "Sector" is a custom identifier for the property cs.CustomIdentifier, then cs = shockVariables(cs,"Baseline (2019 policies)",Region="Canada",Variable="Capital expenditure",Sector="Coal") shocks capital expenditure in Canada for the coal sector against a reference scenario, Baseline (2019 policies).

Version History

Introduced in R2025a