Skip to content

DataWrapper

The DataWrapper class is the main container for managing synthetic economic data across multiple countries. It coordinates the creation and initialization of synthetic countries and their components.

Core Components

Synthetic Countries

The SyntheticCountry class manages individual country data and coordinates all economic agents and markets. It provides:

  • Unified interface for creating synthetic economic data
  • Agent initialization and configuration
  • Market setup and coordination
  • Data validation and consistency checks
  • Economic relationship management

View SyntheticCountry documentation →

Economic Agents

Markets and Data Harmonization

Usage Example

from macro_data import DataWrapper
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

Best Practices

  1. Data Consistency

    • Ensure all economic relationships are properly initialized
    • Validate agent-level data against aggregate statistics
    • Maintain accounting identities

  2. Configuration Management

    • Use appropriate country-specific settings
    • Configure proxy relationships for missing data
    • Document all configuration parameters

  3. Performance Optimization

    • Use efficient data structures
    • Implement parallel processing where possible
    • Cache intermediate results

  4. Data Quality

    • Validate input data
    • Handle missing values appropriately
    • Document data transformations

A comprehensive data container and generator for synthetic economic data used in the macromodel.

This class handles the creation and management of synthetic data for multiple countries, including: - Synthetic country-level economic data - Rest of world data - Exchange rates and trade proportions - Emissions data and factors - Calibration data for model validation

The DataWrapper can be initialized either from a configuration (using from_config) or loaded from a saved pickle file (using init_from_pickle). It supports both EU and non-EU countries, with proxy mechanisms for non-EU countries.

Attributes:

Name Type Description
synthetic_countries dict[str, SyntheticCountry]

Dictionary mapping country codes to synthetic country data
synthetic_rest_of_the_world SyntheticRestOfTheWorld

Synthetic data for rest of world
exchange_rates DataFrame

Exchange rates between countries
origin_trade_proportions DataFrame

Trade proportions by origin country
destination_trade_proportions DataFrame

Trade proportions by destination country
configuration DataConfiguration

Configuration settings for data generation
calibration_data DataFrame

Data used for model calibration
industries list[str]

List of industry codes
emission_factors dict[str, float]

Emission factors by type
emissions_energy_factors Optional[EmissionsEnergyFactors]

Energy-related emission factors

all_country_names: list[str] property

Get a list of all country names, including the Rest of World (ROW).

Returns:

Type Description
list[str]

list[str]: List of all country codes including ROW

n_industries property

Get the number of industries in the model.

Returns:

Name Type Description
int

The total number of industries being modeled

calibration_before property

Get calibration data for periods before the configured year and quarter.

Returns:

Type Description

pd.DataFrame: Calibration data for earlier periods

calibration_during property

Get calibration data for the configured year and quarter. This is the data used for in-sample calibration.

Returns:

Type Description

pd.DataFrame: Calibration data for the current period

from_config(configuration: DataConfiguration, raw_data_path: Path | str, single_hfcs_survey: bool = True, single_icio_survey: bool = True) -> DataWrapper classmethod

Create a DataWrapper instance from a configuration.

This is the primary method for initializing a new DataWrapper. It processes raw data according to the provided configuration to create synthetic data for all specified countries.

Parameters:

Name Type Description Default
configuration DataConfiguration

Configuration specifying countries, industries, and other settings

 required
raw_data_path Path | str

Path to the directory containing raw data files

 required
single_hfcs_survey bool

Whether to use a single Household Finance and Consumption Survey. Defaults to True.

 True
single_icio_survey bool

Whether to use a single Inter-Country Input-Output table. Defaults to True.

 True

Returns:

Name Type Description
DataWrapper DataWrapper

Initialized DataWrapper instance with processed synthetic data

Raises:

Type Description
ValueError

If a non-EU country doesn't have a proxy EU country specified
ValueError

If attempting to disaggregate industries when aggregate_industries is True

init_from_pickle(path: str | Path) -> DataWrapper classmethod

Load a previously saved DataWrapper from a pickle file.

This method is useful for loading preprocessed data without having to regenerate it.

Parameters:

Name Type Description Default
path str | Path

Path to the pickle file containing the saved DataWrapper

 required

Returns:

Name Type Description
DataWrapper DataWrapper

The loaded DataWrapper instance

save(path: str | Path) -> None

Save the DataWrapper instance to a pickle file.

This method saves all synthetic data and configuration to a file for later use. The saved file can be loaded using init_from_pickle.

Parameters:

Name Type Description Default
path str | Path

Path where the pickle file should be saved

 required