Country API Reference

This section documents the country-level aggregation and parameter management in the macromodel package.

Country Module

macromodel.country.country.Country

A complete national economy with interacting agents and markets.

This class represents a single country's economy, integrating all economic agents (individuals, households, firms, banks, government) and markets (labor, credit, housing, goods). It manages their interactions and evolution over time.

The economy operates in discrete timesteps, with each iteration: 1. Updating exchange rates and monetary conditions 2. Running agent-level planning and decision-making 3. Clearing all markets sequentially 4. Recording economic outcomes and updating metrics

The timestep length is configurable (typically quarterly) and determined by how the input data is preprocessed (see ICIOReader's yearly_factor parameter).

Attributes:

Name	Type	Description
country_name	str	Identifier for the country
scale	int	Scaling factor for population-based calculations
individuals	Individuals	Population of individual economic agents
households	Households	Collection of household units
firms	Firms	Collection of producing firms
central_government	CentralGovernment	Fiscal authority
government_entities	GovernmentEntities	Public sector bodies
banks	Banks	Commercial banking sector
central_bank	CentralBank	Monetary authority
economy	Economy	Aggregate economic metrics and tracking
labour_market	LabourMarket	Employment matching and wage setting
credit_market	CreditMarket	Lending and borrowing
housing_market	HousingMarket	Property sales and rentals
exchange_rate_usd_to_lcu	float	Exchange rate to USD
exogenous	Exogenous	External economic conditions
forecasting_window	int	Periods ahead for forecasting
assume_zero_growth	bool	Whether to assume no growth
assume_zero_noise	bool	Whether to assume no random shocks
configuration	CountryConfiguration	Model parameters

from_pickled_country(synthetic_country: SyntheticCountry, country_configuration: CountryConfiguration, exchange_rates: ExchangeRates, country_name: str, all_country_names: list[str], industries: list[str], initial_year: int, t_max: int, running_multiple_countries: bool, emission_factors_usd: np.ndarray) -> Country classmethod

Create a Country instance from preprocessed synthetic data.

This factory method constructs a complete country economy from preprocessed data, initializing all agents and markets with calibrated starting conditions.

Parameters:

Name	Type	Description	Default
synthetic_country	SyntheticCountry	Preprocessed country data	required
country_configuration	CountryConfiguration	Model parameters	required
exchange_rates	ExchangeRates	Exchange rate dynamics	required
country_name	str	Country identifier	required
all_country_names	list[str]	All countries in simulation	required
industries	list[str]	Industry sectors	required
initial_year	int	Starting year	required
t_max	int	Maximum simulation periods	required
running_multiple_countries	bool	If True, part of multi-country sim	required
emission_factors_usd	ndarray	Emission factors in USD	required

Returns:

Name	Type	Description
Country	Country	Initialized country economy

reset(configuration: CountryConfiguration) -> None

Reset the country economy to its initial state.

Resets all agents, markets, and state variables to their initial conditions, optionally with new configuration parameters.

Parameters:

Name	Type	Description	Default
configuration	CountryConfiguration	New model parameters	required

initialisation_phase(exchange_rate_usd_to_lcu: float) -> None

Initialize the monthly economic cycle.

Sets up the initial conditions for the current timestep, including exchange rates and firm counts.

Parameters:

Name	Type	Description	Default
exchange_rate_usd_to_lcu	float	Current exchange rate to USD	required

estimation_phase() -> None

Run economic forecasting and estimation.

Updates agent expectations about growth, inflation, and other key economic variables used in decision-making.

update_planning_metrics() -> None

Update forward-looking economic indicators.

Computes expected profits, asset values, benefits, and other metrics used by agents in their planning decisions.

update_realised_metrics() -> None

Update realized economic outcomes after market clearing.

This method coordinates the comprehensive updating of all economic metrics after markets have cleared. It processes the results of market interactions and computes derived economic indicators across eight major categories:

1. Economic Indicators:
2. Price indices (PPI, CPI)
3. Economic growth rates
4. House price indices
5. Labor market metrics (employment, unemployment)

6. Rental market aggregates

7. Global Trade and Capital Formation:

8. International trade flows
9. Import/export tracking
10. Gross fixed capital formation

11. Input costs (intermediate and capital)

12. Firm Production and Costs:

13. Production volumes and nominal values
14. Wages and labor costs
15. Inventory management
16. Input utilization

17. Emissions (if enabled)

18. Firm Financial Metrics:

19. Sales and revenue
20. Profits and taxes
21. Corporate financial positions
22. Insolvency metrics

23. Debt aggregates

24. Individual and Household Income:

25. Employment income
26. Social transfers
27. Financial asset income
28. Rental income

29. Total household income

30. Household Wealth and Consumption:

31. Consumption patterns
32. Investment decisions
33. Wealth positions
34. Debt management

35. Insolvency handling

36. Government and Banking:

37. Tax collection
38. Government revenue and deficit
39. Bank profits and equity
40. Interest payments

41. Market share metrics

42. GDP and National Accounts:

43. GDP components
44. Value added
45. National income
46. Sectoral balances

The method ensures consistency between micro-level agent behaviors and macro-level economic outcomes, maintaining stock-flow consistency throughout the economy.

Note

This method should be called after all markets (goods, labor, credit, housing) have cleared and agents have executed their planned transactions.

Side Effects

Updates numerous time series variables across all economic agents and markets, reflecting the realized outcomes of the current period's economic activity.

update_population_structure() -> None

Update demographic composition.

Applies demographic changes (aging, retirement, etc.) to the population of individual agents.

get_goods_market_participants() -> list[Agent | RestOfTheWorld]

Get all participants in the goods market.

Returns:

Type	Description
list[Agent | RestOfTheWorld]	list[Agent | RestOfTheWorld]: List of agents participating in goods market transactions

save_to_h5(h5_file: h5py.File) -> None

Save complete country state to HDF5.

Saves the full state of all agents, markets, and economic variables to an HDF5 file for later analysis or continuation.

Parameters:

Name	Type	Description	Default
h5_file	File	Open HDF5 file to save to	required

shallow_output() -> pd.DataFrame

Create summary DataFrame of key economic indicators.

Returns:

Type	Description
DataFrame	pd.DataFrame: DataFrame containing main economic metrics (GDP, inflation, unemployment, etc.)