Economy API Reference

This section documents the Economy entity in the macromodel package, which manages and tracks aggregate economic metrics, market-level interactions, and macroeconomic indicators for each country.

macromodel.economy.economy.Economy

Manages and tracks aggregate economic metrics and market-level interactions.

This class serves as the central coordinator for tracking and computing macroeconomic indicators, market conditions, and aggregate metrics across the entire economy. It integrates data from all economic agents and markets to maintain consistent economic accounting.

Key responsibilities include: 1. Price Level Management: - Computing and tracking various price indices (CPI, PPI, CFPI) - Calculating inflation rates across sectors - Managing industry-specific price levels

1. Economic Growth Tracking:
2. Computing GDP through multiple approaches
3. Tracking sectoral and total growth rates

4. Managing value-added calculations

5. Labor Market Monitoring:

6. Tracking unemployment and participation rates
7. Computing job market dynamics

8. Recording vacancy statistics

9. International Trade:

10. Managing import/export flows
11. Computing trade balances

12. Tracking exchange rate effects

13. Market Integration:

14. Recording housing market metrics
15. Tracking credit conditions
16. Managing goods market clearing

Attributes:

Name	Type	Description
country_name	str	Name identifier for the economy
all_country_names	list[str]	List of all countries in the model
n_industries	int	Number of industrial sectors
functions	dict[str, Any]	Economic function implementations
ts	TimeSeries	Time series data for economic metrics

The class maintains consistency between different measurement approaches while handling temporal evolution and cross-market interactions. It ensures proper accounting of economic flows and stocks across all sectors.

from_agents(country_name: str, all_country_names: list[str], economy_configuration: EconomyConfiguration, firms: Firms, households: Households, individuals: Individuals, government_entities: GovernmentEntities, central_government: CentralGovernment, exogenous: Exogenous, industry_vectors: pd.DataFrame) classmethod

Create an Economy instance from agent-level data and configurations.

This factory method constructs an Economy by aggregating initial conditions from various economic agents and markets. It computes starting values for: - Price levels and production - Sales and intermediate inputs - Tax revenues and capital formation - Operating surplus and wages - Activity status and inflation rates - Housing market conditions - Trade flows and growth rates

Parameters:

Name	Type	Description	Default
country_name	str	Name identifier for the economy	required
all_country_names	list[str]	List of all countries in the model	required
economy_configuration	EconomyConfiguration	Model parameters	required
firms	Firms	Collection of producing firms	required
households	Households	Collection of household units	required
individuals	Individuals	Population of individual agents	required
government_entities	GovernmentEntities	Public sector bodies	required
central_government	CentralGovernment	Fiscal authority	required
exogenous	Exogenous	External economic conditions	required
industry_vectors	DataFrame	Industry-level initial conditions	required

Returns:

Name	Type	Description
Economy		Newly constructed Economy instance with initialized metrics

reset(configuration: EconomyConfiguration) -> None

Reset the economy's state and update function configurations.

Resets all time series data and updates economic functions based on the provided configuration. This ensures a clean state for new simulations while maintaining consistent function implementations.

Parameters:

Name	Type	Description	Default
configuration	EconomyConfiguration	New model parameters	required

set_estimates(exogenous_growth: np.ndarray, exogenous_inflation: pd.DataFrame, exogenous_hpi_growth: pd.DataFrame, forecasting_window: int, exogenous_cpi_inflation_during: np.ndarray, exogenous_ppi_inflation_during: np.ndarray, exogenous_growth_during: np.ndarray, default_growth: float = 0.005, default_inflation: float = 0.0, default_hpi_growth: float = 0.0, min_inflation: float = -0.1, max_inflation: float = 0.1, min_growth: float = -0.2, max_growth: float = 0.2, assume_zero_growth: bool = False, assume_zero_noise: bool = False) -> None

Set economic forecasts and estimates for key indicators.

Computes and sets forecasts for inflation (CPI, PPI), economic growth, and house price appreciation. Uses historical data and exogenous factors to generate estimates within specified bounds.

The method handles: - CPI inflation forecasting - PPI inflation forecasting - Economic growth projection - House price index growth estimation

Parameters:

Name	Type	Description	Default
exogenous_growth	ndarray	External growth factors	required
exogenous_inflation	DataFrame	External inflation data	required
exogenous_hpi_growth	DataFrame	External house price growth	required
forecasting_window	int	Number of periods to forecast	required
exogenous_cpi_inflation_during	ndarray	CPI inflation factors	required
exogenous_ppi_inflation_during	ndarray	PPI inflation factors	required
exogenous_growth_during	ndarray	Growth factors during period	required
default_growth	float	Fallback growth rate. Defaults to 0.005.	0.005
default_inflation	float	Fallback inflation. Defaults to 0.0.	0.0
default_hpi_growth	float	Fallback HPI growth. Defaults to 0.0.	0.0
min_inflation	float	Lower inflation bound. Defaults to -0.1.	-0.1
max_inflation	float	Upper inflation bound. Defaults to 0.1.	0.1
min_growth	float	Lower growth bound. Defaults to -0.2.	-0.2
max_growth	float	Upper growth bound. Defaults to 0.2.	0.2
assume_zero_growth	bool	Force zero growth. Defaults to False.	False
assume_zero_noise	bool	Eliminate random variation. Defaults to False.	False

compute_inflation() -> None

Calculate and record various inflation measures.

Computes period-over-period inflation rates for: - Consumer Price Index (CPI) - Producer Price Index (PPI) - Capital Formation Price Index (CFPI) - Industry-specific price levels

All rates are calculated as percentage changes from previous period.

record_global_trade(firms: Firms, households: Households, government_entities: GovernmentEntities, tau_export: float) -> None

Record international trade flows and balances.

Tracks bilateral trade flows between countries, computing: - Exports before and after taxes by destination - Imports by source country and sector - Total trade volumes and balances

Parameters:

Name	Type	Description	Default
firms	Firms	Collection of producing firms	required
households	Households	Collection of household units	required
government_entities	GovernmentEntities	Public sector bodies	required
tau_export	float	Export tax rate	required

compute_rental_market_aggregates(real_rent_paid: np.ndarray, imp_rent_paid: np.ndarray, rental_income: np.ndarray) -> None

Calculate and record rental market totals.

Updates aggregate measures for: - Total real rent payments - Total imputed rent - Total rental income received

Parameters:

Name	Type	Description	Default
real_rent_paid	ndarray	Actual rent payments	required
imp_rent_paid	ndarray	Imputed rent values	required
rental_income	ndarray	Income from rental properties	required

compute_gdp(total_output: float, sectoral_sales: np.ndarray, sectoral_intermediate_consumption: np.ndarray, taxes_on_products: float, taxes_on_production: float, rent_paid: float, rent_imputed: float, hh_consumption: float, gov_consumption: float, change_in_inventories: float, gross_fixed_capital_formation: float, exports: float, imports: float, operating_surplus: float, wages: float, rent_received: float, central_government_rent_received: float, running_multiple_countries: bool, always_adjust: bool = True) -> None

Calculate GDP through multiple approaches and record components.

Computes GDP using three approaches: 1. Output approach: Production less intermediate consumption 2. Expenditure approach: Final spending components 3. Income approach: Factor payments and operating surplus

Also calculates and records: - Sectoral value added and growth rates - GDP components and their growth rates - Trade balance adjustments - Consistency checks between approaches

The method maintains National Accounts identities and handles adjustments for multi-country scenarios.

Parameters:

Name	Type	Description	Default
total_output	float	Total production value	required
sectoral_sales	ndarray	Sales by industry	required
sectoral_intermediate_consumption	ndarray	Intermediate inputs	required
taxes_on_products	float	Product taxes net of subsidies	required
taxes_on_production	float	Production taxes	required
rent_paid	float	Actual rent payments	required
rent_imputed	float	Imputed rent values	required
hh_consumption	float	Household consumption	required
gov_consumption	float	Government consumption	required
change_in_inventories	float	Inventory changes	required
gross_fixed_capital_formation	float	Fixed investment	required
exports	float	Export value	required
imports	float	Import value	required
operating_surplus	float	Operating surplus and mixed income	required
wages	float	Compensation of employees	required
rent_received	float	Rental income received	required
central_government_rent_received	float	Central government rental income received	required
running_multiple_countries	bool	Multi-country simulation flag	required
always_adjust	bool	Force trade adjustments. Defaults to True.	True

total_exports()

Get aggregate exports time series.

Returns:

Name	Type	Description
float		Total exports value

total_cpi_inflation()

Get aggregate CPI inflation time series.

Returns:

Name	Type	Description
float		CPI inflation rate

total_ppi_inflation()

Get aggregate PPI inflation time series.

Returns:

Name	Type	Description
float		PPI inflation rate

total_cfpi_inflation()

Get aggregate CFPI inflation time series.

Returns:

Name	Type	Description
float		CFPI inflation rate

unemployment_rate()

Get unemployment rate time series.

Returns:

Name	Type	Description
float		Unemployment rate

gdp_expenditure()

Get GDP expenditure approach time series.

Returns:

Name	Type	Description
float		GDP value from expenditure approach

gdp_output()

Get GDP output approach time series.

Returns:

Name	Type	Description
float		GDP value from output approach

Functions

Sentiment

macromodel.economy.func.sentiment.SentimentSetter

Abstract base class for economic sentiment computation.

Provides interface for computing sentiment values across industries. Implementations can vary from constant values to complex dynamic calculations.

Inflation Forecasting

macromodel.economy.func.inflation.InflationForecasting

Abstract base class for inflation forecasting methods.

Provides a common interface for different inflation forecasting approaches. Supports bounded forecasts and noise control in predictions.

Attributes:

Name	Type	Description
forecaster		Underlying forecasting model implementation

Growth Forecasting

macromodel.economy.func.growth.GrowthForecasting

Abstract base class for economic growth forecasting.

Provides a common interface for different growth forecasting approaches. Supports various forecast horizons and noise control in predictions.

Attributes:

Name	Type	Description
forecaster		Underlying forecasting model implementation