query

Return subset of climate scenario data

Since R2025a

Syntax

result = query(cs,Name=Value)

Description

result = query(cs,Name=Value) returns a table containing a subset of data from the climateScenario object, cs. Use name-value arguments to select the data that you want to return. For example, query(cs,Region="Canada",Variable="Capital expenditure") returns the capital expenditure data for Canada.

Examples

Return Subset of Climate Scenario Data

Return a subset of data from a climateScenario object. 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 the query function to subset the data in cs by specifying name-value arguments for the Region and Variable identifiers. The output table, result, contains the rows corresponding to capital expenditure for the region of Canada.

result = query(cs,Region="Canada",Variable="Capital expenditure")

result=308×7 table
    CL_GEOGRAPHY         CL_SECTOR              CL_VARIABLE           CL_UNIT             CL_SCENARIO           CL_YEAR    CL_VALUE
    ____________    ____________________    ___________________    _____________    ________________________    _______    ________

       Canada       Crops                   Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       0.3558 
       Canada       Crops                   Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       0.3558 
       Canada       Livestock               Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       0.1442 
       Canada       Livestock               Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       0.1442 
       Canada       Forestry                Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       0.0489 
       Canada       Forestry                Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       0.0489 
       Canada       Coal                    Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       0.2698 
       Canada       Coal                    Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       0.2698 
       Canada       Oil & Gas               Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       4.7944 
       Canada       Oil & Gas               Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       4.7944 
       Canada       Oil                     Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       3.3869 
       Canada       Oil                     Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       3.3869 
       Canada       Gas                     Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       1.4075 
       Canada       Gas                     Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       1.4075 
       Canada       Refined oil products    Capital expenditure    10 BN US$2014    Baseline (2019 policies)     2020       0.7694 
       Canada       Refined oil products    Capital expenditure    10 BN US$2014    Below 2°C immediate          2020       0.7694 
      ⋮

Input Arguments

cs — Climate scenario object

climateScenario object

Climate scenario object, specified as a climateScenario object.

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: result = query(cs,Region="Canada",Variable="Capital expenditure") returns a table that contains capital expenditure data for Canada.

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 | string vector

Names of custom identifiers, specified as a string vector containing values of cs.CustomIdentifiers. CustomIdentifiers must match an identifier property contained in cs.CustomIdentifiers. For example, if “Sector” is a custom identifier for the property cs.CustomIdentifiers, then results = query(cs,Region=”Canada”,Sector=”Gas”) returns the data for the gas sector in Canada.

UnstackIdentifier — Unstack identifier

string scalar

Unstack identifier, specified as a string scalar. Use this name-value argument when you want to perform vectorized computations for a specific identifier. For example, unstackedData = query(cs,"Variable",["Primary Energy | Nuclear","Primary Energy | Total"],UnstackIdentifier="Scenario") extracts the Primary Energy Nuclear and Primary Energy Total variables, relative to the scenario identifier.

Version History

Introduced in R2025a