groupRegions

Group climate scenario regions

Since R2025a

Syntax

cs = groupRegions(cs,regions,Name=Value)

Description

cs = groupRegions(cs,regions,Name=Value) groups regions in a climateScenario object, cs, into a new region and appends it to the property cs.IdentifierValues.Region. Use the NewRegion name-value argument to specify the name of the new region. You can return the data for the new region by using the query function.

Examples

Group Climate Scenario Regions

Group regions of a climateScenario object into a new region. 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");

Specify the regions you want to group. In this example, you create a new region that contains countries other than the United States.

regions = ["Africa","Canada","China","Europe","India","Japan","Rest of the world"];

Choose the name of the variable identifier you want.

primaryEnergyVariable = "Primary Energy | Oil";

Use groupRegions by specifying the NewRegion and Variable name-value arguments to create the new region.

cs = groupRegions(cs,regions,NewRegion="ExcludeUS",Variable=primaryEnergyVariable);

To see the new region, display the Region field in the IdentifierValues property.

disp(cs.IdentifierValues.Region)

     Africa 
     Canada 
     China 
     Europe 
     Global 
     India 
     Japan 
     Rest of the world 
     United States 
     ExcludeUS 

Display the data contained in the new region by using the query function.

head(query(cs,Region="ExcludeUS"))

    CL_GEOGRAPHY    CL_SECTOR        CL_VARIABLE          CL_UNIT           CL_SCENARIO           CL_YEAR    CL_VALUE
    ____________    _________    ____________________    _________    ________________________    _______    ________

     ExcludeUS      National     Primary Energy | Oil    Exajoules    Baseline (2019 policies)     2020       153.86 
     ExcludeUS      National     Primary Energy | Oil    Exajoules    Below 2°C immediate          2020       153.86 
     ExcludeUS      National     Primary Energy | Oil    Exajoules    Below 2°C delayed            2020       153.86 
     ExcludeUS      National     Primary Energy | Oil    Exajoules    Net-zero 2050 (1.5°C)        2020       153.86 
     ExcludeUS      National     Primary Energy | Oil    Exajoules    Baseline (2019 policies)     2025       168.27 
     ExcludeUS      National     Primary Energy | Oil    Exajoules    Below 2°C immediate          2025       160.68 
     ExcludeUS      National     Primary Energy | Oil    Exajoules    Below 2°C delayed            2025       168.27 
     ExcludeUS      National     Primary Energy | Oil    Exajoules    Net-zero 2050 (1.5°C)        2025       157.64 

Input Arguments

cs — Climate scenario object

climateScenario object

Climate scenario object, specified as a climateScenario object.

regions — Regions to group

string vector

Regions to group, specified as a string vector.

Example: regions = ["Africa", "Canada", "China", "Europe", "India", "Japan", "Rest of the world"]

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 = groupRegions(cs,regions,NewRegion="ExcludeUS",Variable=primaryEnergyVariable) creates a new region, ExcludeUS, that contains primary energy data for all countries except the United States.

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.

NewRegion — New region name

strjoin(regions, ", ") (default) | string scalar

New region name, specified as a string scalar. If you do not specify the new region name, NewRegion defaults to a comma-separated list of the elements of regions.

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 = groupRegions(cs,["Africa", "Canada", "China", "Europe", "India", "Japan", "Rest of the world"],NewRegion="ExcludeUS",Variable="Primary Energy | Oil",Sector="National") creates a new region, ExcludeUS, that contains all countries except the United States, and sets the custom identifier, Sector, to National.

Version History

Introduced in R2025a