EuroStatReader¶

This module provides functionality for reading and processing Eurostat economic data. It handles various economic indicators including financial balance sheets, GDP, debt ratios, interest rates, and sectoral growth rates across European countries.

Key Features: - Read and process multiple Eurostat datasets - Handle country code conversions (Alpha-2 to Alpha-3) - Support for financial indicators and ratios - GDP and sectoral growth calculations - Proxy mechanisms for missing data - Data pruning capabilities

Example

from pathlib import Path
from macro_data.readers.economic_data.eurostat_reader import EuroStatReader
from macro_data.configuration.countries import Country

# Initialize reader with data directory
reader = EuroStatReader(
    path=Path("path/to/eurostat/data"),
    country_code_path=Path("path/to/country_codes.csv"),
    proxy_country="GBR"
)

# Get various economic indicators
gdp = reader.get_quarterly_gdp("FRA", 2020, 1)
debt_ratio = reader.nonfin_firm_debt_ratios("DEU", 2020)
growth = reader.get_perc_sectoral_growth("ITA")

Note

Most monetary values are in millions of national currency units. Ratios and rates are typically returned as decimals (e.g., 0.05 for 5%).

`EuroStatReader` ¶

A class for reading and processing Eurostat economic data.

This class handles various economic indicators including: 1. Financial balance sheets and ratios 2. GDP and sectoral growth 3. Debt and deposit statistics 4. Interest rates and bond yields 5. Household and firm statistics

Parameters:

Name	Type	Description	Default
`path`	`Path \| str`	Path to directory containing Eurostat data files	required
`country_code_path`	`Path \| str`	Path to CSV file containing country code mappings	required
`total_output`	`Optional[dict[str, float]]`	Dictionary of total output by country for scaling	`None`
`proxy_country`	`str`	Country to use as proxy when data is missing (default: "GBR")	`'GBR'`

Attributes:

Name	Type	Description
`c_map`	`DataFrame`	Country code mapping DataFrame
`remap_2_to_3`	`dict`	Mapping from Alpha-2 to Alpha-3 country codes
`remap_3_to_2`	`dict`	Mapping from Alpha-3 to Alpha-2 country codes
`proxy_country`	`str`	Country used for proxying missing data
`total_output`	`Optional[dict[str, float]]`	Total output by country
`data`	`dict[str, DataFrame]`	Dictionary of loaded Eurostat datasets

Note

Handles special cases for Greece (GR -> EL) and UK (GB -> UK)
Most monetary values are in millions of national currency
Ratios and rates are typically returned as decimals

`c_map = pd.read_csv(country_code_path)` `instance-attribute` ¶

`remap_2_to_3 = self.c_map.set_index(['Alpha-2 code'])['Alpha-3 code'].to_dict()` `instance-attribute` ¶

`remap_3_to_2 = self.c_map.set_index(['Alpha-3 code'])['Alpha-2 code'].to_dict()` `instance-attribute` ¶

`proxy_country = proxy_country` `instance-attribute` ¶

`total_output = total_output` `instance-attribute` ¶

`files_with_codes = self.get_files_with_codes()` `instance-attribute` ¶

`data = {}` `instance-attribute` ¶

`init(path: Path | str, country_code_path: Path | str, total_output: Optional[dict[str, float]] = None, proxy_country: str = 'GBR')` ¶

`get_files_with_codes() -> dict[str, str]` `staticmethod` ¶

Get mapping of data categories to file names.

Returns:

Type	Description
`dict[str, str]`	dict[str, str]: Dictionary mapping data categories to their file names

Note

File categories include: - Financial indicators (debt ratios, equity ratios) - Economic indicators (GDP, CPI) - Input-output tables - Sectoral growth rates - Balance sheets and transactions

`country_code_switch(codes: pd.Series) -> pd.Series` ¶

Convert Alpha-2 country codes to Alpha-3 format.

Parameters:

Name	Type	Description	Default
`codes`	`Series`	Series of Alpha-2 country codes	required

Returns:

Type	Description
`Series`	pd.Series: Series of corresponding Alpha-3 country codes

Note

Uses the remap_2_to_3 dictionary for conversion

`find_value(df: pd.DataFrame, country: Country, year: str, return_last_value: bool = True) -> Optional[float]` `staticmethod` ¶

Find value in DataFrame for specific country and year.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame`	DataFrame containing the data	required
`country`	`Country`	Country to find data for	required
`year`	`str`	Year to find data for	required
`return_last_value`	`bool`	Whether to return last available value if year not found (default: True)	`True`

Returns:

Type	Description
`Optional[float]`	Optional[float]: Found value, or None if not found and return_last_value is False

Note

If country not found, returns mean value for the year
If year not found and return_last_value True, returns last available value

`nonfin_firm_debt_ratios(country: Country, year: int) -> float` ¶

Get non-financial firm debt ratios for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get debt ratios for	required
`year`	`int`	Year to get debt ratios for	required

Returns:

Name	Type	Description
`float`	`float`	Non-financial firm debt ratio as a decimal

Note

Returns ratio of total non-financial firm debt to GDP

`get_total_nonfin_firm_debt(country: Country | str, year: int) -> float` ¶

Get total non-financial firm debt for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country \| str`	Country to get debt for	required
`year`	`int`	Year to get debt for	required

Returns:

Name	Type	Description
`float`	`float`	Total non-financial firm debt in millions of national currency

`get_total_fin_firm_debt(country: Country | str, year: int) -> float` ¶

Get total financial firm debt for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country \| str`	Country to get debt for	required
`year`	`int`	Year to get debt for	required

Returns:

Name	Type	Description
`float`	`float`	Total financial firm debt in millions of national currency

`get_total_household_deposits(country: str, year: int, proxy_country: str = 'FRA', ratio: float = 1.0) -> float` ¶

Get total household deposits for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`str`	Country to get deposits for	required
`year`	`int`	Year to get deposits for	required
`proxy_country`	`str`	Country to use as proxy if data not available (default: "FRA")	`'FRA'`

Returns:

Name	Type	Description
`float`	`float`	Total household deposits in millions of national currency

Note

If data not available for specified country, uses proxy country scaled by total output ratio

`get_total_household_fixed_assets(country: str, year: int, proxy_country: str = 'GBR', ratio: float = 1.0) -> float` ¶

Get total household fixed assets for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`str`	Country to get fixed assets for	required
`year`	`int`	Year to get fixed assets for	required
`proxy_country`	`str`	Country to use as proxy if data not available (default: "GBR")	`'GBR'`

Returns:

Name	Type	Description
`float`	`float`	Total household fixed assets in millions of national currency

Note

If data not available for specified country, uses proxy country scaled by total output ratio

`nonfin_firm_deposit_ratios(country: Country, year: int) -> float` ¶

Get non-financial firm deposit ratios for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get deposit ratios for	required
`year`	`int`	Year to get deposit ratios for	required

Returns:

Name	Type	Description
`float`	`float`	Non-financial firm deposit ratio as a decimal

Note

Returns ratio of total non-financial firm deposits to GDP

`get_quarterly_gdp(country: Country, year: int, quarter: int, ratio: float = 1.0) -> float` ¶

Get quarterly GDP for a specific country, year, and quarter.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get GDP for	required
`year`	`int`	Year to get GDP for	required
`quarter`	`int`	Quarter to get GDP for (1-4)	required

Returns:

Name	Type	Description
`float`	`float`	Quarterly GDP in millions of national currency

`get_monthly_gdp(country: Country, year: int, month: int) -> float` ¶

Get monthly GDP for a specific country, year, and month.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get GDP for	required
`year`	`int`	Year to get GDP for	required
`month`	`int`	Month to get GDP for (1-12)	required

Returns:

Name	Type	Description
`float`	`float`	Monthly GDP in millions of national currency

Note

Interpolates quarterly GDP to monthly values using linear interpolation

`get_total_nonfin_firm_deposits(country: Country | str, year: int, ratio: float = 1.0) -> float` ¶

Get total non-financial firm deposits for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country \| str`	Country to get deposits for	required
`year`	`int`	Year to get deposits for	required

Returns:

Name	Type	Description
`float`	`float`	Total non-financial firm deposits in millions of national currency

`get_total_bank_equity(country: str, year: int, proxy_country: str = 'FRA', ratio: float = 1.0) -> float` ¶

Get total bank equity for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`str`	Country to get bank equity for	required
`year`	`int`	Year to get bank equity for	required
`proxy_country`	`str`	Country to use as proxy if data not available (default: "FRA")	`'FRA'`

Returns:

Name	Type	Description
`float`	`float`	Total bank equity in millions of national currency

Note

If data not available for specified country, uses proxy country scaled by total output ratio

`cb_debt_ratios(country: Country, year: int) -> float` ¶

Get central bank debt ratios for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get debt ratios for	required
`year`	`int`	Year to get debt ratios for	required

Returns:

Name	Type	Description
`float`	`float`	Central bank debt ratio as a decimal

Note

Returns ratio of central bank debt to GDP

`cb_equity_ratios(country: Country, year: int) -> float` ¶

Get central bank equity ratios for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get equity ratios for	required
`year`	`int`	Year to get equity ratios for	required

Returns:

Name	Type	Description
`float`	`float`	Central bank equity ratio as a decimal

Note

Returns ratio of central bank equity to GDP

`general_gov_debt_ratios(country: Country, year: int) -> float` ¶

Get general government debt ratios for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get debt ratios for	required
`year`	`int`	Year to get debt ratios for	required

Returns:

Name	Type	Description
`float`	`float`	General government debt ratio as a decimal

Note

Returns ratio of general government debt to GDP

`central_gov_debt_ratios(country: Country, year: int) -> float` ¶

Get central government debt ratios for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get debt ratios for	required
`year`	`int`	Year to get debt ratios for	required

Returns:

Name	Type	Description
`float`	`float`	Central government debt ratio as a decimal

Note

Returns ratio of central government debt to GDP

`shortterm_interest_rates(country: Country | str, year: int, months: int) -> float` ¶

Get short-term interest rates for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country \| str`	Country to get interest rates for	required
`year`	`int`	Year to get interest rates for	required
`months`	`int`	Number of months for interest rate term (0, 1, 3, 6, or 12)	required

Returns:

Name	Type	Description
`float`	`float`	Short-term interest rate as a decimal

Note

Returns money market interest rates for specified term length

`longterm_central_gov_bond_rates(country: Country, year: int) -> float` ¶

Get long-term central government bond rates for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get bond rates for	required
`year`	`int`	Year to get bond rates for	required

Returns:

Name	Type	Description
`float`	`float`	Long-term government bond rate as a decimal

Note

Returns yield on long-term (typically 10-year) government bonds

`dividend_payout_ratio(country: str | Country, year: int, proxy_country: Country = Country('FRA')) -> float` ¶

Calculate the dividend payout ratio for a given country and year.

Parameters:

Name	Type	Description	Default
`country`	`str \| Country`	Country to get payout ratio for	required
`year`	`int`	Year to get payout ratio for (defaults to 2011 if not 2010/2011)	required
`proxy_country`	`Country`	Country to use as proxy if data not available (default: "FRA")	`Country('FRA')`

Returns:

Name	Type	Description
`float`	`float`	Dividend payout ratio as a decimal

Note

Returns ratio of (household property income + household surplus) to firm surplus
Only 2010 and 2011 data available, defaults to 2011 for other years

`firm_risk_premium(country: Country, year: int) -> float` ¶

Calculate the firm risk premium for a given country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get risk premium for	required
`year`	`int`	Year to get risk premium for	required

Returns:

Name	Type	Description
`float`	`float`	Monthly firm risk premium as a decimal

Note

Returns spread between firm borrowing rate and Euribor rate, converted to monthly rate

`number_of_households(country: Country, year: int) -> float` ¶

Get number of households for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get household count for	required
`year`	`int`	Year to get household count for	required

Returns:

Name	Type	Description
`float`	`float`	Number of households (in thousands)

`taxrate_on_capital_formation(country: Country, year: int) -> float` ¶

Get tax rate on capital formation for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get tax rate for	required
`year`	`int`	Year to get tax rate for	required

Returns:

Name	Type	Description
`float`	`float`	Tax rate on capital formation as a decimal

Note

Returns ratio of taxes on capital formation to total capital formation

`get_perc_sectoral_growth(country: Country) -> pd.DataFrame` ¶

Retrieves the percentage sectoral growth data for a specific country.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get sectoral growth for	required

Returns:

Type	Description
`DataFrame`	pd.DataFrame: DataFrame containing growth rates by sector over time, with sectors as columns and time as index

Note

Growth rates are in decimal form (divided by 100)
Includes sectors B, C, D, F and services
Service sector growth rate is applied to sectors A, E, G-S

`get_total_industry_debt_and_deposits(country: Country, proxy_country: Optional[Country] = None, ratio: float = 1.0) -> pd.DataFrame` ¶

Get total industry debt and deposits time series for a specific country.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get data for	required
`proxy_country`	`Optional[Country]`	Country to use as proxy if data not available	`None`

Returns:

Type	Description
`DataFrame`	pd.DataFrame: DataFrame with monthly time series of total debt and deposits

Raises:

Type	Description
`ValueError`	If no data available and no proxy country provided

Note

Returns monthly data from 1970 to 2024, using annual values repeated monthly

`get_imputed_rent_fraction_of_country(country: Country, year: int) -> float` ¶

Get imputed rent fraction for a specific country and year.

Parameters:

Name	Type	Description	Default
`country`	`Country`	Country to get rent fraction for	required
`year`	`int`	Year to get rent fraction for	required

Returns:

Name	Type	Description
`float`	`float`	Imputed rent fraction as a decimal

Note

Returns ratio of imputed rent (CPA_L68A) to total real estate services (CPA_L68A + CPA_L68B)

`get_investment_fractions_of_country(country_name: str, year: int) -> dict[str, float]` ¶

Get investment fractions by sector for a specific country and year.

Parameters:

Name	Type	Description	Default
`country_name`	`str`	Country to get investment fractions for	required
`year`	`int`	Year to get investment fractions for	required

Returns:

Type	Description
`dict[str, float]`	dict[str, float]: Dictionary with investment fractions by sector (keys: "Firm", "Household", "Government")

Note

Returns normalized fractions (sum to 1)
Falls back to proxy country if data not available
Uses previous year's data if year > 2011

`get_imputed_rent_fraction(country_names: list[Country], year: int) -> dict[str, float]` ¶

Get imputed rent fractions for multiple countries and a specific year.

Parameters:

Name	Type	Description	Default
`country_names`	`list[Country]`	List of countries to get rent fractions for	required
`year`	`int`	Year to get rent fractions for	required

Returns:

Type	Description
`dict[str, float]`	dict[str, float]: Dictionary mapping country codes to their imputed rent fractions

Note

Includes "ROW" (rest of world) entry with mean of all countries' fractions

`prune(prune_date: date)` ¶

Prune data to only include entries after specified date.

Parameters:

Name	Type	Description	Default
`prune_date`	`date`	Date to prune data from	required

Returns:

Name	Type	Description
`EuroStatReader`		Self for method chaining

Note

Modifies data in place
Handles both time period columns and date-based columns
Warns if no data remains after pruning

EuroStatReader¶

EuroStatReader ¶

c_map = pd.read_csv(country_code_path) instance-attribute ¶

remap_2_to_3 = self.c_map.set_index(['Alpha-2 code'])['Alpha-3 code'].to_dict() instance-attribute ¶

remap_3_to_2 = self.c_map.set_index(['Alpha-3 code'])['Alpha-2 code'].to_dict() instance-attribute ¶

proxy_country = proxy_country instance-attribute ¶

total_output = total_output instance-attribute ¶

files_with_codes = self.get_files_with_codes() instance-attribute ¶

data = {} instance-attribute ¶

__init__(path: Path | str, country_code_path: Path | str, total_output: Optional[dict[str, float]] = None, proxy_country: str = 'GBR') ¶

get_files_with_codes() -> dict[str, str] staticmethod ¶

country_code_switch(codes: pd.Series) -> pd.Series ¶

find_value(df: pd.DataFrame, country: Country, year: str, return_last_value: bool = True) -> Optional[float] staticmethod ¶

nonfin_firm_debt_ratios(country: Country, year: int) -> float ¶

get_total_nonfin_firm_debt(country: Country | str, year: int) -> float ¶

get_total_fin_firm_debt(country: Country | str, year: int) -> float ¶

get_total_household_deposits(country: str, year: int, proxy_country: str = 'FRA', ratio: float = 1.0) -> float ¶

get_total_household_fixed_assets(country: str, year: int, proxy_country: str = 'GBR', ratio: float = 1.0) -> float ¶

nonfin_firm_deposit_ratios(country: Country, year: int) -> float ¶

get_quarterly_gdp(country: Country, year: int, quarter: int, ratio: float = 1.0) -> float ¶

get_monthly_gdp(country: Country, year: int, month: int) -> float ¶

get_total_nonfin_firm_deposits(country: Country | str, year: int, ratio: float = 1.0) -> float ¶

get_total_bank_equity(country: str, year: int, proxy_country: str = 'FRA', ratio: float = 1.0) -> float ¶

cb_debt_ratios(country: Country, year: int) -> float ¶

cb_equity_ratios(country: Country, year: int) -> float ¶

general_gov_debt_ratios(country: Country, year: int) -> float ¶

central_gov_debt_ratios(country: Country, year: int) -> float ¶

shortterm_interest_rates(country: Country | str, year: int, months: int) -> float ¶

longterm_central_gov_bond_rates(country: Country, year: int) -> float ¶

dividend_payout_ratio(country: str | Country, year: int, proxy_country: Country = Country('FRA')) -> float ¶

firm_risk_premium(country: Country, year: int) -> float ¶

number_of_households(country: Country, year: int) -> float ¶

taxrate_on_capital_formation(country: Country, year: int) -> float ¶

get_perc_sectoral_growth(country: Country) -> pd.DataFrame ¶

get_total_industry_debt_and_deposits(country: Country, proxy_country: Optional[Country] = None, ratio: float = 1.0) -> pd.DataFrame ¶

get_imputed_rent_fraction_of_country(country: Country, year: int) -> float ¶

get_investment_fractions_of_country(country_name: str, year: int) -> dict[str, float] ¶

get_imputed_rent_fraction(country_names: list[Country], year: int) -> dict[str, float] ¶

prune(prune_date: date) ¶

`EuroStatReader` ¶

`c_map = pd.read_csv(country_code_path)` `instance-attribute` ¶

`remap_2_to_3 = self.c_map.set_index(['Alpha-2 code'])['Alpha-3 code'].to_dict()` `instance-attribute` ¶

`remap_3_to_2 = self.c_map.set_index(['Alpha-3 code'])['Alpha-2 code'].to_dict()` `instance-attribute` ¶

`proxy_country = proxy_country` `instance-attribute` ¶

`total_output = total_output` `instance-attribute` ¶

`files_with_codes = self.get_files_with_codes()` `instance-attribute` ¶

`data = {}` `instance-attribute` ¶

`init(path: Path | str, country_code_path: Path | str, total_output: Optional[dict[str, float]] = None, proxy_country: str = 'GBR')` ¶

`get_files_with_codes() -> dict[str, str]` `staticmethod` ¶

`country_code_switch(codes: pd.Series) -> pd.Series` ¶

`find_value(df: pd.DataFrame, country: Country, year: str, return_last_value: bool = True) -> Optional[float]` `staticmethod` ¶

`nonfin_firm_debt_ratios(country: Country, year: int) -> float` ¶

`get_total_nonfin_firm_debt(country: Country | str, year: int) -> float` ¶

`get_total_fin_firm_debt(country: Country | str, year: int) -> float` ¶

`get_total_household_deposits(country: str, year: int, proxy_country: str = 'FRA', ratio: float = 1.0) -> float` ¶

`get_total_household_fixed_assets(country: str, year: int, proxy_country: str = 'GBR', ratio: float = 1.0) -> float` ¶

`nonfin_firm_deposit_ratios(country: Country, year: int) -> float` ¶

`get_quarterly_gdp(country: Country, year: int, quarter: int, ratio: float = 1.0) -> float` ¶

`get_monthly_gdp(country: Country, year: int, month: int) -> float` ¶

`get_total_nonfin_firm_deposits(country: Country | str, year: int, ratio: float = 1.0) -> float` ¶

`get_total_bank_equity(country: str, year: int, proxy_country: str = 'FRA', ratio: float = 1.0) -> float` ¶

`cb_debt_ratios(country: Country, year: int) -> float` ¶

`cb_equity_ratios(country: Country, year: int) -> float` ¶

`general_gov_debt_ratios(country: Country, year: int) -> float` ¶

`central_gov_debt_ratios(country: Country, year: int) -> float` ¶

`shortterm_interest_rates(country: Country | str, year: int, months: int) -> float` ¶

`longterm_central_gov_bond_rates(country: Country, year: int) -> float` ¶

`dividend_payout_ratio(country: str | Country, year: int, proxy_country: Country = Country('FRA')) -> float` ¶

`firm_risk_premium(country: Country, year: int) -> float` ¶

`number_of_households(country: Country, year: int) -> float` ¶

`taxrate_on_capital_formation(country: Country, year: int) -> float` ¶

`get_perc_sectoral_growth(country: Country) -> pd.DataFrame` ¶

`get_total_industry_debt_and_deposits(country: Country, proxy_country: Optional[Country] = None, ratio: float = 1.0) -> pd.DataFrame` ¶

`get_imputed_rent_fraction_of_country(country: Country, year: int) -> float` ¶

`get_investment_fractions_of_country(country_name: str, year: int) -> dict[str, float]` ¶

`get_imputed_rent_fraction(country_names: list[Country], year: int) -> dict[str, float]` ¶

`prune(prune_date: date)` ¶