SyntheticCountry

Overview

The SyntheticCountry class is responsible for creating and managing synthetic economic data for individual countries. It coordinates the creation and initialization of various economic agents and markets that make up a country's economic system.

Components

Economic Data

The CountryData component manages country-specific economic data.

View CountryData documentation →

Economic Agents

Firms

The SyntheticFirms component manages firm-level data and behavior:

• Firm creation and initialization
• Industry classification
• Financial data
• Production relationships

View SyntheticFirms documentation →

Banks

The SyntheticBanks component handles banking sector data and operations:

• Bank creation and initialization
• Balance sheet data
• Lending operations
• Financial relationships

View SyntheticBanks documentation →

Population

The SyntheticPopulation component manages household and individual data:

• Household creation
• Income distribution
• Wealth distribution
• Demographic data

View SyntheticPopulation documentation →

Central Bank

The SyntheticCentralBank component handles monetary policy and operations:

• Policy rate setting
• Money supply
• Banking supervision
• Financial stability

View SyntheticCentralBank documentation →

Central Government

The SyntheticCentralGovernment component manages fiscal policy and operations:

• Tax collection
• Government spending
• Public debt
• Fiscal policy

View SyntheticCentralGovernment documentation →

Government Entities

The SyntheticGovernmentEntities component handles government agencies and institutions:

• Agency creation
• Budget allocation
• Service provision
• Public administration

View SyntheticGovernmentEntities documentation →

Rest of the World

The SyntheticRestOfTheWorld component manages external economic relationships:

• Trade flows
• Capital flows
• Exchange rates
• External debt

View SyntheticRestOfTheWorld documentation →

Markets

Credit Market

The SyntheticCreditMarket component manages credit and lending operations:

• Loan creation
• Interest rates
• Credit allocation
• Risk assessment

View SyntheticCreditMarket documentation →

Housing Market

The SyntheticHousingMarket component handles housing market operations:

• Housing stock
• House prices
• Rental market
• Housing transactions

View SyntheticHousingMarket documentation →

Goods Market

The SyntheticGoodsMarket component manages goods and services market:

• Price setting
• Supply and demand
• Market clearing
• Trade flows

View SyntheticGoodsMarket documentation →

Matching

The SyntheticMatching component handles agent matching and relationships:

• Household-firm matching
• Bank-firm matching
• Labor market matching
• Service provision matching

View SyntheticMatching documentation →

Usage Example

from macro_data.processing import SyntheticCountry
from macro_data.configuration.countries import Country

# Initialize a synthetic country
country = SyntheticCountry(
    country=Country("FRA"),
    data_readers=data_readers,
    configuration=config
)

# Create the synthetic economic system
country.create()

# Access different components
firms = country.firms
banks = country.banks
population = country.population
central_bank = country.central_bank

Implementation

This module provides the SyntheticCountry class, which serves as a container for all synthetic economic data related to a single country in the macroeconomic model. It handles the creation and management of synthetic data for various economic agents and markets within a country.

The module supports: - Creation of synthetic data for EU and non-EU countries - Management of economic agents (firms, banks, households) - Market simulations (credit, housing, goods) - GDP calculations and economic indicators - Emissions and environmental factors

Key features: - Support for both EU countries and non-EU countries (via proxy mechanism) - Integration of various economic markets and agents - Handling of financial flows and relationships between agents - Calculation of key economic indicators (GDP by different methods) - Environmental impact tracking through emissions

Example

from macro_data import DataConfiguration, Country
from macro_data.processing.synthetic_country import SyntheticCountry

# Create a synthetic EU country
france = SyntheticCountry.eu_synthetic_country(
    country=Country.FRANCE,
    year=2023,
    quarter=1,
    country_configuration=country_config,
    industries=industries,
    readers=data_readers,
    exogenous_country_data=france_data,
    country_industry_data=industry_data,
    year_range=1,
    goods_criticality_matrix=criticality_matrix
)

# Access economic indicators
gdp = france.gdp_output

SyntheticCountry dataclass

A comprehensive container for all synthetic economic data and agents within a country.

This class serves as the primary interface for managing synthetic economic data, including populations, firms, markets, and financial institutions. It provides methods for creating and managing synthetic data for both EU and non-EU countries, handling economic relationships between agents, and calculating key economic indicators.

Attributes:

Name	Type	Description
population	SyntheticPopulation	Synthetic household and individual data
firms	SyntheticFirms	Synthetic firm data and behavior
credit_market	SyntheticCreditMarket	Credit market operations and state
banks	SyntheticBanks	Banking system data and operations
central_bank	SyntheticCentralBank	Central bank policy and operations
central_government	SyntheticCentralGovernment	Central government fiscal policy
government_entities	SyntheticGovernmentEntities	Government agency data
housing_market	SyntheticHousingMarket	Housing market state and operations
synthetic_goods_market	SyntheticGoodsMarket	Goods market transactions
dividend_payout_ratio	float	Ratio of profits paid as dividends
long_term_interest_rate	float	Long-term interest rate for the economy
policy_rate_markup	float	Markup over policy rate for lending
industry_data	dict[str, DataFrame]	Industry-level economic data
goods_criticality_matrix	DataFrame	Matrix of goods dependencies
tax_data	TaxData	Tax rates and revenue data
exogenous_data	ExogenousCountryData	External economic factors
scale	int	Scaling factor for synthetic agents
country_name	Country	Country identifier
country_configuration	CountryDataConfiguration	Country-specific settings
industries	list[str]	List of industry sectors
consumption_weights_by_income	DataFrame	Consumption patterns by income
emission_factors	EmissionsData	Environmental impact factors

population: SyntheticPopulation instance-attribute

firms: SyntheticFirms instance-attribute

credit_market: SyntheticCreditMarket instance-attribute

banks: SyntheticBanks instance-attribute

central_bank: SyntheticCentralBank instance-attribute

central_government: SyntheticCentralGovernment instance-attribute

government_entities: SyntheticGovernmentEntities instance-attribute

housing_market: SyntheticHousingMarket instance-attribute

synthetic_goods_market: SyntheticGoodsMarket instance-attribute

dividend_payout_ratio: float instance-attribute

long_term_interest_rate: float instance-attribute

policy_rate_markup: float instance-attribute

industry_data: dict[str, pd.DataFrame] instance-attribute

goods_criticality_matrix: pd.DataFrame instance-attribute

tax_data: TaxData instance-attribute

exogenous_data: ExogenousCountryData instance-attribute

scale: int instance-attribute

country_name: Country instance-attribute

country_configuration: CountryDataConfiguration instance-attribute

industries: list[str] instance-attribute

consumption_weights_by_income: pd.DataFrame instance-attribute

emission_factors: EmissionsData instance-attribute

n_sellers_by_industry property

Get the number of firms (sellers) in each industry.

Returns:

Type	Description
	np.ndarray: Array containing the count of firms per industry

n_buyers property

Get the total number of economic agents that can act as buyers.

This includes households, firms, and government entities.

Returns:

Name	Type	Description
int		Total number of potential buyers in the economy

gdp_output: float property

Calculate GDP using the production (output) approach.

This method computes GDP by: 1. Taking total sales value (production * price) 2. Subtracting intermediate input costs 3. Adding taxes on products 4. Subtracting taxes on production 5. Adding rent (both paid and imputed)

Returns:

Name	Type	Description
float	float	GDP value calculated using the output approach

gdp_expenditure: float property

Calculate GDP using the expenditure approach.

This method computes GDP as the sum of: 1. Capital formation (business + household investment) 2. Household consumption 3. Government consumption 4. Net exports (exports - imports) 5. Rent (both paid and imputed)

Returns:

Name	Type	Description
float	float	GDP value calculated using the expenditure approach

gdp_income: 0 property

Calculate GDP using the income approach.

This method computes GDP as the sum of: 1. Operating surplus (sales - wages - intermediate inputs - production taxes) 2. Wages 3. Taxes on products 4. Rental income taxes 5. Social housing rent 6. Imputed rent 7. Household rental income

Returns:

Name	Type	Description
float	0	GDP value calculated using the income approach

__init__(population: SyntheticPopulation, firms: SyntheticFirms, credit_market: SyntheticCreditMarket, banks: SyntheticBanks, central_bank: SyntheticCentralBank, central_government: SyntheticCentralGovernment, government_entities: SyntheticGovernmentEntities, housing_market: SyntheticHousingMarket, synthetic_goods_market: SyntheticGoodsMarket, dividend_payout_ratio: float, long_term_interest_rate: float, policy_rate_markup: float, industry_data: dict[str, pd.DataFrame], goods_criticality_matrix: pd.DataFrame, tax_data: TaxData, exogenous_data: ExogenousCountryData, scale: int, country_name: Country, country_configuration: CountryDataConfiguration, industries: list[str], consumption_weights_by_income: pd.DataFrame, emission_factors: EmissionsData) -> None

eu_synthetic_country(country: Country, year: int, quarter: int, country_configuration: CountryDataConfiguration, industries: list[str], readers: DataReaders, exogenous_country_data: ExogenousCountryData, country_industry_data: dict[str, pd.DataFrame], year_range: int, goods_criticality_matrix: pd.DataFrame, emission_factors: Optional[EmissionsData] = None) -> SyntheticCountry classmethod

Create a synthetic country object for a European Union member country.

This method initializes all economic agents and markets for an EU country using actual EU data sources. It sets up the complete economic structure including: - Government institutions (central bank, government entities) - Financial system (banks, credit markets) - Real economy (firms, households, goods market) - Environmental factors (if emission data provided)

Parameters:

Name	Type	Description	Default
country	Country	The EU country to create synthetic data for	required
year	int	Base year for data generation	required
quarter	int	Base quarter for data generation	required
country_configuration	CountryDataConfiguration	Country-specific settings	required
industries	list[str]	List of industry sectors to model	required
readers	DataReaders	Data source readers	required
exogenous_country_data	ExogenousCountryData	External economic factors	required
country_industry_data	dict[str, DataFrame]	Industry-level data	required
year_range	int	Number of years of historical data to consider	required
goods_criticality_matrix	DataFrame	Matrix of goods dependencies	required
emission_factors	Optional[EmissionsData]	Environmental impact factors	None

Returns:

Name	Type	Description
SyntheticCountry	SyntheticCountry	Initialized synthetic country instance

Note

This method should only be used for EU member countries. For non-EU countries, use proxied_synthetic_country instead.

proxied_synthetic_country(country: Country | Region, proxy_country: Country, year: int, quarter: int, country_configuration: CountryDataConfiguration, industries: list[str], readers: DataReaders, exogenous_country_data: ExogenousCountryData, country_industry_data: dict[str, pd.DataFrame], year_range: int, goods_criticality_matrix: pd.DataFrame, proxy_inflation_data: pd.DataFrame, emission_factors: Optional[EmissionsData] = None) -> SyntheticCountry classmethod

Create a synthetic country object for a non-EU country using an EU country as proxy.

This method creates synthetic data for non-EU countries by using an EU country's data structure as a template, while maintaining the non-EU country's actual: - Population ratios - Exchange rates - Economic scale - Industry structure - Trade patterns

Parameters:

Name	Type	Description	Default
country	Country	The non-EU country to create synthetic data for	required
proxy_country	Country	The EU country to use as a template	required
year	int	Base year for data generation	required
quarter	int	Base quarter for data generation	required
country_configuration	CountryDataConfiguration	Country-specific settings	required
industries	list[str]	List of industry sectors to model	required
readers	DataReaders	Data source readers	required
exogenous_country_data	ExogenousCountryData	External economic factors	required
country_industry_data	dict[str, DataFrame]	Industry-level data	required
year_range	int	Number of years of historical data to consider	required
goods_criticality_matrix	DataFrame	Matrix of goods dependencies	required
proxy_inflation_data	DataFrame	Inflation data from proxy country	required
emission_factors	Optional[EmissionsData]	Environmental impact factors	None

Returns:

Name	Type	Description
SyntheticCountry	SyntheticCountry	Initialized synthetic country instance

set_wealth_and_credit(banks: SyntheticBanks, central_government: SyntheticCentralGovernment, country_configuration: CountryDataConfiguration, country_industry_data: dict[str, pd.DataFrame], firms: SyntheticFirms, population: SyntheticPopulation, tax_data: TaxData, central_bank: SyntheticCentralBank, weights_by_income: pd.DataFrame, emission_factors_array: Optional[np.ndarray] = None, emitting_indices: Optional[np.ndarray] = None) -> SyntheticCreditMarket classmethod

This function takes care of matching the different agents together and initialising the Credit and Housing markets. This function is separated because we may want to change the initialisation of firm parameters in particular those which depend on function parameters), in which case we need to redo the matching and initialisation of the markets.

Parameters:

Name	Type	Description	Default
banks	SyntheticBanks	The synthetic banks.	required
central_government	SyntheticCentralGovernment	The synthetic central government.	required
country_configuration	CountryDataConfiguration	The configuration data for the country.	required
country_industry_data	dict[str, DataFrame]	The industry data for the country.	required
firms	SyntheticFirms	The synthetic firms.	required
population	SyntheticPopulation	The synthetic population.	required
tax_data	TaxData	The tax data for the country.	required
central_bank	SyntheticCentralBank	The synthetic central bank.	required
weights_by_income	DataFrame	The weights by income for the country.	required
emission_factors_array	ndarray	The emission factors for the country (tCO2 per LCU).	None
emitting_indices	ndarray	The indices of emitting industries.	None

Returns:

Type	Description
SyntheticCreditMarket	tuple[SyntheticCreditMarket, SyntheticHousingMarket]: A tuple containing the synthetic credit market,
SyntheticCreditMarket	exogenous data, and synthetic housing market.

match_households_firms_banks(banks: SyntheticBanks, firms: SyntheticFirms, industries: list[str], population: SyntheticPopulation, tax_data: TaxData, independents: Optional[list[str]] = None) classmethod

Match economic agents (households, firms, banks) to establish relationships.

This method: 1. Matches individuals with firms (employment relationships) 2. Matches firms with banks (banking relationships) 3. Computes household wealth 4. Matches households with banks (banking relationships)

Parameters:

Name	Type	Description	Default
banks	SyntheticBanks	Banking system data	required
firms	SyntheticFirms	Firm data	required
industries	list[str]	List of industries	required
population	SyntheticPopulation	Population data	required
tax_data	TaxData	Tax rates and data	required
independents	Optional[list[str]]	List of independent variables for wealth computation	None

init_credit_market(banks: SyntheticBanks, central_government: SyntheticCentralGovernment, country_configuration: CountryDataConfiguration, country_industry_data: dict[str, pd.DataFrame], firms: SyntheticFirms, population: SyntheticPopulation, tax_data: TaxData, risk_premium: float, policy_rate: float) -> SyntheticCreditMarket classmethod

Initialize the credit market for the synthetic country.

This method sets up the credit market by: 1. Initializing bank interest rates and profits 2. Creating credit market relationships between agents 3. Setting up loan installments for households 4. Initializing firm financial conditions 5. Updating government financial relationships

Parameters:

Name	Type	Description	Default
banks	SyntheticBanks	Banking system data	required
central_government	SyntheticCentralGovernment	Government data	required
country_configuration	CountryDataConfiguration	Country settings	required
country_industry_data	dict[str, DataFrame]	Industry data	required
firms	SyntheticFirms	Firm data	required
population	SyntheticPopulation	Population data	required
tax_data	TaxData	Tax rates and data	required
risk_premium	float	Risk premium for interest rates	required
policy_rate	float	Central bank policy rate	required

Returns:

Name	Type	Description
SyntheticCreditMarket	SyntheticCreditMarket	Initialized credit market

initialise_pop_wealth_income(banks: SyntheticBanks, central_government: SyntheticCentralGovernment, country_industry_data: dict[str, pd.DataFrame], firms: SyntheticFirms, population: SyntheticPopulation, tax_data: TaxData, weights_by_income: pd.DataFrame, independents: Optional[list[str]] = None, emission_factors_array: Optional[np.ndarray] = None, emitting_industry_indices: Optional[np.ndarray] = None) classmethod

Initialize population wealth, income, and consumption patterns.

This method sets up: 1. Wealth distribution functions 2. Household income including social transfers 3. Saving and investment rates 4. Consumption normalization and patterns 5. Emissions data (if applicable) 6. Bank deposits and loans

Parameters:

Name	Type	Description	Default
banks	SyntheticBanks	Banking system data	required
central_government	SyntheticCentralGovernment	Government data	required
country_industry_data	dict[str, DataFrame]	Industry-level data	required
firms	SyntheticFirms	Firm data	required
population	SyntheticPopulation	Population data	required
tax_data	TaxData	Tax rates and data	required
weights_by_income	DataFrame	Consumption weights by income level	required
independents	Optional[list[str]]	Independent variables for wealth computation	None
emission_factors_array	Optional[ndarray]	Emission factors by industry	None
emitting_industry_indices	Optional[ndarray]	Indices of emitting industries	None

reset_firm_function_dependent(capital_inputs_utilisation_rate: float, initial_inventory_to_input_fraction: float, intermediate_inputs_utilisation_rate: float, zero_initial_debt: bool, zero_initial_deposits: bool)

Reset firm parameters and reinitialize dependent markets.

This method updates firm operational parameters and reinitializes all markets and relationships that depend on firm behavior, including: 1. Firm operational parameters 2. Housing market relationships 3. Credit market relationships 4. Financial flows between agents

Parameters:

Name	Type	Description	Default
capital_inputs_utilisation_rate	float	Rate of capital input usage	required
initial_inventory_to_input_fraction	float	Initial inventory ratio	required
intermediate_inputs_utilisation_rate	float	Rate of intermediate input usage	required
zero_initial_debt	bool	Whether to reset firm debt to zero	required
zero_initial_deposits	bool	Whether to reset firm deposits to zero	required