gcubed.sym_data

This module contains the SymData class, which loads and provides access to all of the information about the model contained in the SYM model definition.

class SymData:

Overview

The model equations are expressed in terms of various vectors of variables and a vector of parameters.

Each vector is a different type of variable. Note the naming conventions for the lefthand side (LHS) variable vectors:

a. x1l - the vector of left-hand side state variables b. j1l - the vector of left-hand side costate or jump variables c. zel - the vector of left-hand side expected endogenous variables d. z1l - the vector of left-hand side endogenous variables

These 4 vectors of variables are functions of:

  1. x1r is right-hand side state variables
  2. j1r is right-hand side costate or jump variables
  3. zer is right-hand side endogenous variables LOGY, PRCT, PRID
  4. exz is right-hand side the lead expected ze variables
  5. yxr is right-hand side state variables lagged by 1 period
  6. yjr is right-hand side costate variables lagged by 1 period
  7. exo is exogenous variables (by definition only appearing on the right-hand side)
  8. z1r is right-hand side endogenous variables.

The parameters are a vector of parameters, par.

SymData(configuration: gcubed.model_configuration.ModelConfiguration)

Constructor

Loads and provides access to all of the information about the model contained in the SYM model definition.

Arguments

configuration: The configuration details for the model.

def vector_type(self, vector_name: str) -> str:

Overview

Convert a vector name in the model to the type of variable it represents as defined by the variable summary var_type column.

Arguments

vector_name: The name of the vector (any one of the LHS or RHS vector names)

Exceptions

Raises an exception if the vector name is not recognised.

configuration

The configuration details for the model.

var_info: pandas.core.frame.DataFrame

The dataframe of information about the model variables, loaded from the var_info file produced by processing the SYM model definition with the SYM processor.

var_map: pandas.core.frame.DataFrame

The dataframe containing the map of the model variables, loaded from the var_map file produced by processing the SYM model definition with the SYM processor.

def matching_rhs_vector_name(self, lhs_vector_name: str) -> str:

Arguments

lhs_vector_name: the name of the LHS vector.

Returns

the matching RHS vector name, replacing the last character, l, with an r.

def varmap_variable_type(self, vector_name: str):

Convert a vector name in the model to the varmap file variable type to lookup for the varmap information associated with the vector.

def projection_vector_for_variable(self, variable_name: str) -> str:

Arguments

vector_name: The fully qualified name of the variable

### Returns

The string ID of the projection vector that the variable is in.

set_memberships: dict[str, list[str]]

A dictionary mapping from a set name to the list of set members, in the order in which they were defined in the SYM model definition.

def set_members(self, set_name: str) -> str:

Arguments

set_name: The name of the SYM model definition set of interest, e.g. 'region'.

Returns

The members of the named set, as a list of strings, or the empty list if the named set is not part of the SYM model definition.

set_descriptions: dict[str, str]

A dictionary mapping from set name to set description.

def set_description(self, set_name: str) -> str:

Arguments

set_name: The name of the set.

Returns

The description of the set.

set_member_descriptions: dict[str, str]

A dictionary mapping from set member name to set member description.

def set_member_description(self, set_member_name: str) -> str:

Arguments

set_member_name: The name of the set member.

Returns

The description of the set member.

goods_members: list[str]

The list of goods produced in the economy. These are the members of the goods set, that is a part of every G-Cubed model SYM definition.

goods_count: int

The number of goods produced in the economy. These are the members of the goods set, that is a part of every G-Cubed model SYM definition.

energy_goods_members: list[str]

The list of energy goods produced in the economy. These are the outputs of the energy producing sectors in the economy.

They are identified by being members of the goods_e set, that is a part of every G-Cubed model SYM definition.

energy_goods_count: int

The number of energy goods produced in the economy. These are the outputs of sectors in the economy that deal with extraction and value addition for fuel sources (e.g.coal, gas, oil, petroleum refining etc) as well as the electricity distribution sector.

They are identified by being members of the goods_e set, that is a part of every G-Cubed model SYM definition.

electricity_generation_goods_members: list[str]

The list of goods in the economy that are produced by electricity generation sectors. All of those sectors produce electricity, so their output is the same in some sense. However, the output of each industry is identified by its own 'good' identifier.

They are identified by being members of the goods_g set.

electricity_generation_goods_count: int

The number of goods in the economy that are produced by electricity generation sectors. All of those sectors produce electricity, so their output is the same in some sense. However, the output of each industry is identified by its own 'good' identifier.

They are identified by being members of the goods_g set.

non_energy_goods_members: list[str]

The list of goods in the economy that are not energy goods (those that are members of the goods_e set).

non_energy_goods_count: int

The number of goods in the economy that are not energy goods (those that are members of the goods_e set).

non_electricity_generation_goods_members: list[str]

The list of goods in the economy that are not electricity generation goods (those that are members of the goods_g set).

non_electricity_generation_goods_count: int

The number of goods in the economy that are not electricity generation goods (those that are members of the goods_g set).

has_electricity_distribution_good: bool

A flag indicating whether the model has an electricity distribution good.

electricity_distribution_good: str

The list of electricity distribution goods produced in the model.

Typically, this is a single good is only defined in models that break out electricity into a single distribution sector that aggregates the output from one or more electricity generation sectors.

Exceptions

Raises an exception if the electricity distribution good is not defined in the model.

standard_goods_members: list[str]

The list of sectors explicitly defined in the SYM model definition that have a standard treatment of their production functions (this typically just excludes the electricity distribution sector).

standard_goods_count: int

The number of sectors explicitly defined in the SYM model definition that are not responsible for electricity distribution.

material_goods_members: list[str]

The list of material goods in the economy (those that are not energy goods or electricity generation goods).

material_goods_count: int

The number of material goods in the economy (those that are not energy goods or electricity generation goods).

ordinary_nondurable_goods_members: list[str]

The list of non-durable goods in the economy that are not electricity generation goods.

ordinary_nondurable_goods_count: int

The number of non-durable goods in the economy that are not electricity generation goods.

has_durable_manufacturing_good: bool

A flag indicating whether the model has a durable manufacturing good.

durable_manufacturing_good: list[str]

The durable manufacturing good produced in the economy.

Typically there is a single sector producing a single durable manufacturing good.

The exception is the 2 sector model where there is no durable manufacturing good.

Exceptions

Raises an exception if the durable manufacturing good is not defined in the model.

capital_sectors_members: list[str]

The capital sectors that are part of all G-Cubed models. There are two of them:

  1. sector Y, the sector that produces capital for firms.

  2. sector Z, the sector that produces capital for households.

all_sectors_members: list[str]

The list of all sectors defined in the SYM model definition plus the two capital producing sectors that are common to all model versions.

all_sectors_count: int

The number of sectors defined in the SYM model definition plus the two capital producing sectors that are common to all model versions.

sectors_members: list[str]

The list of sectors that are explicitly defined in the SYM model definition. These are the members of the sectors set.

The list does not include the two capital producing sectors that are common to all model versions.

sectors_count: int

The number of sectors that are explicitly defined in the SYM model definition. These are the members of the sectors set.

The number does not include the two capital producing sectors that are common to all model versions.

non_energy_or_generation_sectors_members: list[str]

The list of sectors explicitly defined in the SYM model definition except for sectors that are involved in electricity generation or energy.

has_electricity_distribution_sector: bool

A flag indicating whether the model has an electricity distribution sector.

electricity_distribution_sector: str

The list of sectors explicitly defined in the SYM model definition that are responsible for electricity distribution.

This is typically just the first sector, in those models that include such a sector.

Exceptions

Raises an exception if the electricity distribution sector is not defined in the model.

has_electricity_generation_sectors: bool

A boolean flag indicating whether the model has electricity generation sectors.

electricity_generation_sectors_members: list[str]

The list of sectors explicitly defined in the SYM model definition that are responsible for electricity distribution.

electricity_generation_sectors_count: int

The number of sectors explicitly defined in the SYM model definition except for sectors that are involved in electricity generation.

non_electricity_generation_sectors_members: list[str]

The list of sectors explicitly defined in the SYM model definition except for sectors that are involved in electricity generation.

non_electricity_generation_sectors_count: int

The number of sectors explicitly defined in the SYM model definition that are not responsible for electricity generation.

standard_sectors_members: list[str]

The list of sectors explicitly defined in the SYM model definition that have a standard treatment of their production functions (this typically just excludes the electricity distribution sector).

standard_sectors_count: int

The number of sectors explicitly defined in the SYM model definition that are not responsible for electricity distribution.

non_energy_sectors_members: list[str]

The list of sectors explicitly defined in the SYM model definition that are not responsible for electricity distribution.

non_energy_sectors_count: int

The number of sectors explicitly defined in the SYM model definition that are not responsible for electricity distribution.

material_sectors_members: list[str]

The list of sectors producting material goods in the economy (those that are not energy goods or electricity generation goods).

material_sectors_count: int

The number of sectors producing material goods in the economy (those that are not energy goods or electricity generation goods).

gas_sector: str

The string identifier of the gas sector.

Model versions with more than 2 sectors typically include a gas sector.

oil_sector: str

The string identifier of the oil refining sector. This is currently the sector associated with oil-related carbon emissions.

coal_sector: str

The string identifier of the coal sector

coal_generation_sector: str

The string identifier of the coal generation sector

gas_generation_sector: str

The string identifier of the gas generation sector

oil_generation_sector: str

The string identifier of the oil generation sector

nuclear_generation_sector: str

The string identifier of the nuclear generation sector

wind_generation_sector: str

The string identifier of the wind generation sector

solar_generation_sector: str

The string identifier of the solar generation sector

hydro_generation_sector: str

The string identifier of the hydro generation sector

other_generation_sector: str

The string identifier of the other generation sector

services_sector: str

The string identifier of the services sector

has_durable_manufacturing_sector: bool

A flag indicating whether the model has a durable manufacturing sector.

durable_manufacturing_sector: list[str]

The durable manufacturing sector in the economy.

Typically there is a single sector producing a single durable manufacturing good.

The exception is the 2 sector model where there is no durable manufacturing good.

Exceptions

Raises an exception if the durable manufacturing sector is not defined in the model.

regions_members: list[str]

The list of regions explicitly defined in the SYM model definition as part of the regions set.

regions_count: int

The number of regions explicitly defined in the SYM model definition as part of the regions set.

us_region: str

The string identifier of the USA region. This must always be the first region defined in the SYM regions set and it will be the first region in the list of region members.

gas_sector_good: str

The string identifier of the good produced by the sector that includes gas extraction and gas utilities.

oil_sector_good: str

The string identifier of the good produced by the oil refining sector.

coal_sector_good: str

The string identifier of the good produced by the coal sector.

services_sector_good: str

The string identifier of the 'good' produced by the services sector.

fossil_fuel_goods_members: list[str]

The list of sectors explicitly defined in the SYM model definition that are responsible for fossil fuel extraction and production in alphabetical order of the sector identifiers.

  • gas
  • oil
  • coal
fossil_fuel_goods_count: int

The number of goods that are fossil fuels

sector_prefix: str

The first letter of the first sector identifier. This is typically a.

good_prefix: str

The first letter of the first good identifier. This is typically g.

def sector_producing(self, good: str) -> str:

Arguments

good: The identifier of the good produced by the sector of interest.

Returns

the sector identifier for the sector that produces the specified good.

def sectors_producing(self, goods: list[str]) -> str:

Arguments

goods: The list of identifiers of the goods produced by the sectors of interest.

Returns

the list of sector identifiers for the sectors that produces the goods in the supplied list.

def good_produced_by(self, sector: str) -> str:

Arguments

sector: The identifier of the sector that produces the good of interest.

Returns

the good identifier produced by the specified sector.

def goods_produced_by(self, sectors: list[str]) -> str:

Arguments

sectors: The list of identifiers of the sectors that produce the goods of interest.

Returns

the list of good identifiers for the goods produced by the specified sectors.

gases_members: list[str]

The list of greenhouse gases that are part of the ghg set in the SYM model definition.

gases_count: int

The number of greenhouse gases that are part of the ghg set in the SYM model definition.

exogenous_variable_count

The number of exogenous variables in the model (The length of the EXO vector).

endogenous_variable_count

The number of endogenous variables in the model (The length of the Z1L, Z1R vectors).

expected_endogenous_variable_count

The number of expected endogenous variables in the model (The length of the ZEL, ZER and EXZ vectors).

jump_variable_count

The number of costate or jump variables in the model (The length of the J1L, J1R and YJR vectors).

state_variable_count

The number of state variables in the model (The length of the X1L, X1R and XJR vectors).

parameter_count

The number of parameters in the model.

resources_members: list[str]

The list of resources other than energy or material goods that are used in production.

resources_count: int

The number of resources other than energy or material goods that are used in production.

factors_of_production_members: list[str]

The four string identifiers of the factors of production:

  1. K for capital
  2. L for labour
  3. E for energy
  4. M for material
factors_of_production_count: int

The number of factors of production (4).

lhs_vector_names: list[str]

A list of the model's LHS vector names.

Note the lowercase naming conventions for the lefthand side (LHS) variable vectors:

  1. x1l (the vector of state variables) X=S=State
  2. j1l (the vector of costate or jump variables) J=C=Costate
  3. zel (the endogenous variables LOGY, PRCT, PRID)
  4. z1l (the other endogenous variables)
rhs_vector_names: list[str]
  1. S - state - x1r is right hand side (RHS) state variables
  2. J - jump - j1r is RHS costate or jump variables
  3. R - ? - zer is special RHS endogenous variables LOGY, PRCT, PRID that also appear as expected next-period values on the RHS of the equations.
  4. exz is RHS the lead expected R (Expected value in next period of R)
  5. S_{t-1} yxr is RHS state variables lagged by 1 period
  6. yjr is RHS costate variables lagged by 1 period
  7. exo is exogenous variables (by definition only appearing on RHS)
  8. z1r is RHS other endogenous variables.
ssf_rhs_vector_names: list[str]
  1. exz is RHS the lead expected endogenous variables (Expected value in next period of a subset of the endogenous variables)
  2. yxr is RHS state variables lagged by 1 period
  3. yjr is RHS costate variables lagged by 1 period
  4. exo is exogenous variables (by definition only appearing on RHS)
projection_vector_names: list[str]
def vector_length(self, vector_name: str) -> int:

Argument:

vector_name: The 3 character acronym identifying the LHS or RHS vector in the model.

Returns the integer length of the specified vector.

def vector_variable_names(self, vector_name: str) -> list[str]:

Arguments

vector_name: the name of the vector

Returns the SYM ordered fully articulated variable names for the variables in the given model vector.

This is useful for labelling the rows/columns of dataframes containing linear model partial derivatives, and SSF matrices.

no_exogenous_variables: bool

Used in place of the swtch variable in the Ox implementation.

no_jump_variables: bool

Used in place of the swtch variable in the Ox implementation.

no_expected_exogenous_variables: bool

Used in place of the swtch variable in the Ox implementation.

parameter_name_prefixes: list[str]
def has_variables(self, variable_name_prefix: str) -> bool:

Overview

Used to check whether the model includes variables with names that start with the supplied prefix. The prefix is matched as a string rather than a regular expression.

Arguments

variable_name_prefix: The variable name prefix string.

Returns

True iff the SYM model definition includes a variable with the given root name.

def has_variable(self, variable_name: str) -> bool:

Overview

Used to check whether the model includes the named variable.

Arguments

variable_name: The complete variable name including the set qualifier in round brackets (e.g. INFL(USA)).

Returns

True if the SYM model definition includes a variable with the given complete name.

def variable_index(self, vector_name: str, variable_name: str) -> int:

Overview

Used to get the integer index of a variable in the specified vector.

Arguments

variable_name: The complete variable name including the set qualifier in round brackets (e.g. INFL(USA)).

Returns

The integer indicating the row index of the variable in the given vector. Indexing starts from 0.

Throws

An exception is thrown if the named variable is not unique within the SYM model though that should not be possible once the SYM processor has run without problems.

def units_for_variables_with_given_name_prefix(self, vector_name: str, variable_name_prefix: str) -> str:

Arguments

vector_name: The name of the vector that contains the variable.

variable_name_prefix: The prefix is the set of characters up to but not including the round bracket that starts the full qualification of the variable based on the sets it is defined over.

e.g. use SHL for SHL(region,sector)

Returns

The units of measurement for the variables that match the given name prefix and that are of the variable type associated with the given vector name.

intertemporal_constant_variables: pandas.core.frame.DataFrame

Overview

Provides access to the information about the variables that are associated with intertemporal constants.

The intertemporal constants are used to ensure that jump variables equal to their observed values in the year where there is available data (typically the base projection year, one year before the start of projections).

An intertemporal constant is also used in each WAGE equation to ensure that real interest rates align with nominal interest rates less expected inflation in the next year.

Returns

A dataframe containing a row per variable that has an intertemporal constant in its equation. The dataframe has the following columns:

  • name variable name (complete with set identifiers for region/sector etc.)
  • var_type variable type (the associated LHS vector name)
  • sequence the index of the variable in the associated vector
variables_adjusted_by_intertemporal_constants: pandas.core.frame.DataFrame

Overview

Provides access to the information about the variables that have their values adjusted by the intertemporal constants. Note that this list is slightly different from the list of variables that have intertemporal constants added to their equations in the model to match up model projections with observed values at the start of the projections because a constant is added to the WAGE equation but it is used to adjust the WAGE equation in a way that leads to the required expected price inflation rate.

Returns

A dataframe containing a row per variable that has an intertemporal constant in its equation. The dataframe has the following columns:

  • name variable name (complete with set identifiers for region/sector etc.)
  • var_type variable type (the associated LHS vector name)
  • sequence the index of the variable in the associated vector
variable_summary: pandas.core.frame.DataFrame

Overview

This summary dataframe of the SYM information about variables should be used to drive a lot of the variable filtering during model processing.

The rows of the dataframe are the variable names.

The columns of the dataframe are:

  • name - the full name of the variable
  • prefix - the name prefix - up to the open bracket.
  • units - the units code.
  • publication_units - the units code to use when publishing variable projections.
  • description - the description
  • var_type - one of:
    • par = parameter
    • ets = expected next-period value of an endogenous variable
    • end = endogenous
    • sta = state
    • stl = lead state variable
    • exo = exogenous
    • cos = costate or jump
  • vector - the vector name e.g. z1l, yxr, exo etc.
  • vector_code - the vector name and index combination - e.g. exo[3].
  • sequence - the index in the vector that corresponds to the variable - e.g 3.
  • is_intertemp - the index of the variable in the vector of intertemporal constants (or NaN)
  • is_adjusted - the index of the variable in the vector of variables being adjusted by intertemporal constants (or NaN)

Returns

The variable summary dataframe.

def variable_units(self, variable_name: str) -> str:

Arguments

variable_name: The full name of the variable including details of set membership: e.g. WAGE(AA).

Returns

The units of measurement for the variable with the given name.

Exceptions

Raises an exception if the named variable is not in the model.

def variable_publication_units(self, variable_name: str) -> str:

Arguments

variable_name: The full name of the variable including details of set membership: e.g. WAGE(AA).

Returns

The publication units of measurement for the variable with the given name.

Exceptions

Raises an exception if the named variable is not in the model.

def variable_var_type(self, variable_name: str) -> str:

Arguments

variable_name: The full name of the variable including details of set membership: e.g. WAGE(AA).

Returns

The variable type of the vector that the variable is in. One of:

  • par = parameter
  • ets = expected next-period value of an endogenous variable
  • end = endogenous
  • sta = state
  • stl = lead state variable
  • exo = exogenous
  • cos = costate or jump

Exceptions

Raises an exception if the named variable is not in the model.

def variable_region(self, variable_name: str) -> str:

Arguments

variable_name: The full name of the variable including details of set membership: e.g. WAGE(AA).

Returns

The region code for the named variable or None if the variable has no region.

Exceptions

Raises an exception if the named variable is not in the model.

def is_exogenous(self, variable_name: str) -> bool:

Arguments

variable_name: The full name of the variable.

Returns

True if the variable is exogenous and False otherwise.

Throws

Exception if the named variable is not in the model.

def is_state(self, variable_name: str) -> int:

Arguments

variable_name: The full name of the variable.

Returns

True if the variable is a state or lead state variable and False otherwise.

Throws

Exception if the named variable is not in the model.

def is_adjustable_in_simulations(self, variable_name: str) -> int:

Arguments

variable_name: The full name of the variable.

Returns

True if the variable can be adjusted in a simulation layer and False otherwise.

Throws

Exception if the named variable is not in the model.

zero_variables_selector: pandas.core.series.Series

Overview

Some variables have equations defined for them by SYM but should instead be set to zero in the model. This method enables those variables to be selected.

Returns

The series contains True iff the variable is to have its equation modified to ensure the variable always evaluates to zero.

zero_variables_summary: pandas.core.frame.DataFrame

Overview

Some variables have equations defined for them by SYM but should instead be set to zero in the model. This method enables those variables to be selected.

This is used to change the python class that contains the equations in the model, replacing specific functions for the selected variables and changing the map from LHS to RHS variables to have empty RHS lists for the selected variables as LHS variables.

Returns

The extract of the variable summary dataframe for those variables that are to have their equations replaced with an equals zero.

def equation_function_name(self, variable_name: str) -> str:

Arguments

variable_name: The full name of the variable.

Returns

The name of the function that is to be used to calculate the value of the variable in the model.

Throws

  • AssertionError if the named variable is not in the model.
  • AssertionError if the named variable is exogenous.
  • AssertionError if the named variable is a parameter.
def variable_name(self, vector_name: str, sequence: int) -> str:

Enables determation of the variable name from the vector name and sequence details provided in the SYM generated equation map.

Arguments

vector_name: the name of the vector in which the variable is stored.

sequence: the position of the variable in the vector.

Returns

The name of the variable in the model.

def variables_with_prefix(self, variable_name_prefix: str) -> list[str]:

Overview

Used to get the list of variable names in the model that have the given prefix (the letters before the first '(').

Arguments

variable_name_prefix: The variable name prefix string.

Returns

A series of variable names that have the given prefix.