Skip to content

HFCSReader

This module provides functionality for reading and processing data from the ECB's Household Finance and Consumption Survey (HFCS). The HFCS is a detailed survey that collects household-level data on households' finances and consumption patterns across European countries.

Key Features: - Read and process HFCS survey data from multiple waves - Handle both household and individual level data - Convert monetary values to local currency units - Map standardized variable names - Filter and clean survey responses

The module supports reading various types of HFCS data: 1. Individual data (P files): Personal characteristics, income, employment 2. Household data (H files): Assets, liabilities, consumption 3. Derived data (D files): Calculated variables and aggregates

Example 
from pathlib import Path
from macro_data.readers.population_data.hfcs_reader import HFCSReader
from macro_data.readers.economic_data.exchange_rates import ExchangeRatesReader

# Initialize exchange rates reader
exchange_rates = ExchangeRatesReader(...)

# Read HFCS data for Germany in 2017
hfcs = HFCSReader.from_csv(
    country_name="Germany",
    country_name_short="DE",
    year=2017,
    hfcs_data_path=Path("path/to/hfcs/data"),
    exchange_rates=exchange_rates
)

# Access household and individual data
households = hfcs.households_df
individuals = hfcs.individuals_df
Note

All monetary values are converted to local currency units using the provided exchange rates.

HFCSReader

A class for reading and processing Household Finance and Consumption Survey (HFCS) data.

This class handles the reading and initial processing of HFCS data, including: - Loading multiple survey waves - Converting monetary values to local currency - Joining household and derived data - Filtering by country - Standardizing variable names

Parameters

country_name_short : str Two-letter country code (e.g., "DE" for Germany) individuals_df : pd.DataFrame DataFrame containing individual-level survey data households_df : pd.DataFrame DataFrame containing household-level survey data

Attributes

country_name_short : str Two-letter country code individuals_df : pd.DataFrame Processed individual-level data households_df : pd.DataFrame Processed household-level data

country_name_short = country_name_short instance-attribute
individuals_df = individuals_df instance-attribute
households_df = households_df instance-attribute
__init__(country_name_short: str, individuals_df: pd.DataFrame, households_df: pd.DataFrame)
from_csv(country_name: str, country_name_short: str, year: int, hfcs_data_path: Path, exchange_rates: ExchangeRatesReader, num_surveys: int = 5) -> HFCSReader classmethod

Create a HFCSReader instance from CSV files.

This method reads and processes multiple HFCS survey files, including: - Individual (P) files: Personal characteristics and income - Household (H) files: Household assets and liabilities - Derived (D) files: Calculated variables

Parameters

country_name : str Full country name (e.g., "Germany") country_name_short : str Two-letter country code (e.g., "DE") year : int Survey year hfcs_data_path : Path Base path to HFCS data files exchange_rates : ExchangeRatesReader Exchange rate converter for monetary values num_surveys : int, optional Number of survey waves to read (default: 5)

Returns

HFCSReader Initialized reader with processed survey data

Notes
  • Files are expected to be named P1.csv, H1.csv, D1.csv, etc.
  • All monetary values are converted to local currency
  • Derived data is joined with household data
read_csv(path: Path | str, country_name: str, country_name_short: str, year: int, exchange_rates: ExchangeRatesReader) -> pd.DataFrame staticmethod

Read and process a single HFCS CSV file.

This method: 1. Reads the CSV file 2. Filters for the specified country 3. Maps variable names to standardized format 4. Converts monetary values to local currency 5. Handles missing values and data types

Parameters

path : Path | str Path to the CSV file country_name : str Full country name for exchange rate lookup country_name_short : str Two-letter country code for filtering year : int Year for exchange rate lookup exchange_rates : ExchangeRatesReader Exchange rate converter

Returns

pd.DataFrame Processed DataFrame with standardized columns and local currency values

Notes
  • Missing values ('A', 'M') are converted to NaN
  • Monetary values are converted from EUR to local currency
  • Only variables in var_mapping are kept