macrostat.core.Variables

class macrostat.core.Variables(variable_info: dict | None = None, timeseries: dict | None = None, parameters: Parameters | dict | None = None, *args, **kwargs)

Bases: object

Variables class for the MacroStat model.

This class contains the variables of a MacroStat model, specifically the output tensors from the simulation. Furthermore, it contains the methods to export the variables to different formats, and holds important information on the characteristics of each of the variables, such as their dimension, long-form name, unit, description and notation.

__init__(variable_info: dict | None = None, timeseries: dict | None = None, parameters: Parameters | dict | None = None, *args, **kwargs)

Initialize the variables for the model. If no variables are provided, the default variables will be used, and if only some variables are provided, the missing variables will be set to their default values.

Parameters:

• variable_info (dict | None) – The variable information to use for the model.

• timeseries (dict | None) – The timeseries to use for the model.

• parameters (dict | None) – The parameters to use for the model.

Methods

__init__([variable_info, timeseries, parameters])	Initialize the variables for the model.
balance_sheet_actual()	Calculate the actual balance sheet of the model.
balance_sheet_theoretical([mathfmt, ...])	Calculate the theoretical balance sheet of the model based on the information in the info dictionary.
check_health()	Check the health of the variables.
compare(other)	Compare the variables to another Variables object or DataFrame.
from_excel(file_path, *args, **kwargs)	Initialize the variables from an Excel file.
from_json(file_path, *args, **kwargs)	Read the timeseries from a JSON file.
gather_timeseries()	Gather the existing timeseries "lists" into single PyTorch tensors
get_default_variables()	Return the default variables information dictionary.
get_flow_variables()	Get all the flow variables from the info dictionary.
get_index_variables()	Get all the index variables from the info dictionary.
get_stock_variables()	Get all the stock variables from the info dictionary.
info_to_csv(file_path[, sphinx_math])	Convert the variables information to a CSV file.
initialize_tensors()	Initialize the output tensors, creating two different dictionaries.
new_state(**kwargs)	Initialize the state variables for the given period.
record_state(t, state_vars)	Record the state variables for the given period.
to_excel(file_path)	Convert the variables to an Excel file.
to_json(file_path)	Convert the parameters to a JSON file.
to_pandas()	Convert the variables to a pandas DataFrame.
transaction_matrix_actual()	Calculate the actual transaction matrix of the model.
transaction_matrix_theoretical([mathfmt, ...])	Calculate the theoretical transaction matrix of the model based on the information in the info dictionary.
update_history(state)	Update the history variables for the given period.
verify_sfc_info()	Verify that the sfc information in the info dictionary is complete.

balance_sheet_actual()

Calculate the actual balance sheet of the model.

balance_sheet_theoretical(mathfmt: str = 'sphinx', non_camel_case: bool = False)

Calculate the theoretical balance sheet of the model based on the information in the info dictionary.

Parameters:

• mathfmt (str) – The format to use for the math. Can be “sphinx”, “myst”, or “latex”.

• non_camel_case (bool) – Whether to convert variable names to non-camel case.

Returns:

A DataFrame containing the theoretical balance sheet of the model.

Return type:

pd.DataFrame

check_health()

Check the health of the variables. This is where the user may want to implement checks for consistency of the variables, e.g. whether the balance sheet is in balance, or whether the redundant equations hold.

By default, this function returns True, indicating that the variables are healthy. This is to facilitate usage of the variables object in other functions.

compare(other: Self | DataFrame)

Compare the variables to another Variables object or DataFrame.

Parameters:

other (pd.DataFrame) – The DataFrame to compare the variables to.

classmethod from_excel(file_path: PathLike, *args, **kwargs)

Initialize the variables from an Excel file.

Parameters:

file_path (os.PathLike) – The path to the Excel file to read the variables from.

classmethod from_json(file_path: PathLike, *args, **kwargs)

Read the timeseries from a JSON file.

Parameters:

file_path (os.PathLike) – The path to the JSON file to read the timeseries from.

gather_timeseries()

Gather the existing timeseries “lists” into single PyTorch tensors

get_default_variables()

Return the default variables information dictionary.

This function returns a dictionary of the variable information with their default values. Users should implement this function in their model class, and it should return a dictionary with the variable names as keys and the variable information as values. The variable information should contain at least the following keys:

• “history”: int - The number of periods that the variable requires information from.

• “sectors”: list - The sectors that the variable is associated with.

• “unit”: str - The unit of the variable.

• “notation”: str - The notation of the variable.

get_flow_variables()

Get all the flow variables from the info dictionary. Flow variables are those that are flows between sectors i.e. their “sfc” tuple starts with “inflow” or “outflow”.

get_index_variables()

Get all the index variables from the info dictionary. Index variables are those that are indices, i.e. their “sfc” tuple starts with “index”.

get_stock_variables()

Get all the stock variables from the info dictionary. Stock variables are those that are assets or liabilities, i.e. their “sfc” tuple starts with “asset” or “liability”.

info_to_csv(file_path: str, sphinx_math: bool = False)

Convert the variables information to a CSV file.

Parameters:

• file_path (str) – The path to the CSV file to save the variables information to.

• sphinx_math (bool) – Whether to add a “:math:” marker to the notation column, e.g. for usage in the documentation

initialize_tensors()

Initialize the output tensors, creating two different dictionaries. First, a dictionary for the state variables (i.e. those that require only t-1 information, but no history) and second a dictionary for the history variables (i.e. those that require information from further previous periods).

new_state(**kwargs)

Initialize the state variables for the given period.

record_state(t: int, state_vars: dict)

Record the state variables for the given period.

Parameters:

• t (int) – The period to record the state variables for.

• state_vars (dict) – The state variables to record.

to_excel(file_path: PathLike)

Convert the variables to an Excel file.

Parameters:

file_path (os.PathLike) – The path to the Excel file to save the variables to.

to_json(file_path: PathLike)

Convert the parameters to a JSON file.

Parameters:

file_path (os.PathLike) – The path to the JSON file to save the timeseries to.

to_pandas()

Convert the variables to a pandas DataFrame.

transaction_matrix_actual()

Calculate the actual transaction matrix of the model.

transaction_matrix_theoretical(mathfmt: str = 'sphinx', non_camel_case: bool = False)

Calculate the theoretical transaction matrix of the model based on the information in the info dictionary.

Parameters:

• mathfmt (str) – The format to use for the math. Can be “sphinx”, “myst”, or “latex”.

• non_camel_case (bool) – Whether to convert variable names to non-camel case.

Returns:

A DataFrame containing the theoretical balance sheet of the model.

Return type:

pd.DataFrame

update_history(state: dict)

Update the history variables for the given period.

Parameters:

• state (dict) – The state variables for the given period.

• history (dict) – The history variables for the given period.

verify_sfc_info()

Verify that the sfc information in the info dictionary is complete.

This function checks first whether there is an sfc entry in the info dictionary for each variable. If there is, it then checks whether the sfc information makes sense, i.e. if they are flows they should have and “inflow” and “outflow” tuple in the list, otherwise they should contain at least one tuple with the first element being either “index”, “asset” or “liability”.