ExchangeRatesReader

This module provides functionality for reading and processing World Bank exchange rate data. It supports various currency conversions between USD, EUR, and local currency units (LCU) for different countries and time periods.

Key Features: - Read exchange rate data from CSV files - Convert between USD, EUR, and local currencies - Support for annual exchange rates - Handle special cases (e.g., ROW as USA) - Prune historical data by date

Example

from pathlib import Path
from macro_data.readers.economic_data.exchange_rates import ExchangeRatesReader

# Initialize reader with exchange rate data
reader = ExchangeRatesReader.from_csv(
    path=Path("path/to/exchange_rates.csv")
)

# Convert EUR to local currency for Japan in 2020
jpy_rate = reader.from_eur_to_lcu("JPN", 2020)

# Get all exchange rates for 2020
rates_2020 = reader.exchange_rates_dict(2020)

# Convert between USD and local currency
to_usd = reader.to_usd("GBR", 2020)
from_usd = reader.from_usd("GBR", 2020)

Note

Exchange rates are stored relative to USD (i.e., LCU per USD). ROW (Rest of World) is treated as USA for exchange rate purposes.

ExchangeRatesReader

A class for reading and manipulating World Bank exchange rate data.

Attributes:

Name	Type	Description
df	DataFrame	The DataFrame containing the exchange rate data.

Methods:

Name	Description
from_csv	Path | str) -> "ExchangeRatesReader": Creates a WorldBankRatesReader instance from a CSV file.
exchange_rates_dict	int) -> dict[str, float]: Returns a dictionary of exchange rates for a specific year.
to_usd	str, year: int) -> float: Converts a currency value from a specific country to USD.
from_usd	str, year: int) -> float: Converts a currency value from USD to a specific country.
from_eur_to_lcu	str, year: int) -> float: Converts a currency value from EUR to local currency unit (LCU).
from_usd_to_lcu	str, year: int) -> float: Converts a currency value from USD to local currency unit (LCU).
prune	date): Prunes the exchange rate data based on a specified date.

df = df instance-attribute

__init__(df: pd.DataFrame)

Initialize the ExchangeRatesReader.

Parameters:

Name	Type	Description	Default
df	DataFrame	DataFrame containing exchange rate data with countries as index and years as columns.	required

from_csv(path: Path | str) -> ExchangeRatesReader classmethod

Create an ExchangeRatesReader instance from a CSV file.

Parameters:

Name	Type	Description	Default
path	Path | str	Path to CSV file containing exchange rate data.	required

Returns:

Name	Type	Description
ExchangeRatesReader	ExchangeRatesReader	Initialized reader with loaded exchange rate data.

Note

CSV should have countries as rows and years as columns.

exchange_rates_dict(year: int) -> dict[str, float]

Get all exchange rates for a specific year.

Parameters:

Name	Type	Description	Default
year	int	Year to get exchange rates for.	required

Returns:

Type	Description
dict[str, float]	dict[str, float]: Dictionary mapping country codes to exchange rates (LCU per USD).

to_usd(country: str, year: int) -> float

Convert from local currency to USD.

Parameters:

Name	Type	Description	Default
country	str	Country code (e.g., 'GBR', 'JPN').	required
year	int	Year of exchange rate.	required

Returns:

Name	Type	Description
float	float	Exchange rate for converting from local currency to USD.

Note

ROW (Rest of World) is treated as USA.

from_usd(country: str, year: int) -> float

Convert from USD to local currency.

Parameters:

Name	Type	Description	Default
country	str	Country code (e.g., 'GBR', 'JPN').	required
year	int	Year of exchange rate.	required

Returns:

Name	Type	Description
float	float	Exchange rate for converting from USD to local currency.

Note

ROW (Rest of World) is treated as USA. The default currency is USD.

from_eur_to_lcu(country: str, year: int) -> float

Convert from EUR to local currency unit (LCU).

This method performs a two-step conversion: 1. EUR to USD (using Germany as EUR proxy) 2. USD to target currency

Parameters:

Name	Type	Description	Default
country	str	Country code (e.g., 'GBR', 'JPN').	required
year	int	Year of exchange rate.	required

Returns:

Name	Type	Description
float	float	Exchange rate for converting from EUR to local currency.

Note

Uses Germany (DEU) as proxy for EUR. ROW (Rest of World) is treated as USA.

from_usd_to_lcu(country: str, year: int) -> float

Convert from USD to local currency unit (LCU).

This is an alias for from_usd() for consistency with from_eur_to_lcu().

Parameters:

Name	Type	Description	Default
country	str	Country code (e.g., 'GBR', 'JPN').	required
year	int	Year of exchange rate.	required

Returns:

Name	Type	Description
float	float	Exchange rate for converting from USD to local currency.

Note

ROW (Rest of World) is treated as USA.

prune(prune_date: date)

Prune exchange rate data to remove entries after a specified date.

Parameters:

Name	Type	Description	Default
prune_date	date	Date after which to remove data.	required

Note

Modifies the df attribute in place. Uses the prune_index utility function.