pydeflate 1.4.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

pydeflate/__init__.py

@@ -1,34 +1,42 @@
 __author__ = """Jorge Rivera"""
-__version__ = "1.4.1"
+__version__ = "2.0.0"
 
-from pydeflate.deflate.deflate import deflate
-from pydeflate.tools.exchange import exchange
-from pydeflate.tools.update_data import update_all_data, warn_updates
-from pydeflate.get_data.oecd_data import update_dac1
-from pydeflate import get_data
+from pydeflate.deflate.deflators import (
+    oecd_dac_deflate,
+    wb_cpi_deflate,
+    wb_gdp_deflate,
+    wb_gdp_linked_deflate,
+    imf_cpi_deflate,
+    imf_gdp_deflate,
+    imf_cpi_e_deflate,
+)
+
+from pydeflate.deflate.legacy_deflate import deflate
+from pydeflate.exchange.exchangers import oecd_dac_exchange, wb_exchange, imf_exchange
+from pydeflate.pydeflate_config import setup_logger
 
 
 def set_pydeflate_path(path):
     from pathlib import Path
     from pydeflate.pydeflate_config import PYDEFLATE_PATHS
-    from bblocks import set_bblocks_data_path
 
     """Set the path to the data folder."""
     global PYDEFLATE_PATHS
 
     PYDEFLATE_PATHS.data = Path(path).resolve()
-    set_bblocks_data_path(PYDEFLATE_PATHS.data)
-
-
-# check that data is fresh enough
-warn_updates()
 
 
 __all__ = [
-    "deflate",
-    "exchange",
-    "update_all_data",
     "set_pydeflate_path",
-    "get_data",
-    "update_dac1",
+    "oecd_dac_deflate",
+    "oecd_dac_exchange",
+    "wb_cpi_deflate",
+    "wb_gdp_deflate",
+    "wb_gdp_linked_deflate",
+    "wb_exchange",
+    "imf_cpi_deflate",
+    "imf_gdp_deflate",
+    "imf_cpi_e_deflate",
+    "imf_exchange",
+    "deflate",
 ]

pydeflate/core/api.py

@@ -0,0 +1,404 @@
+import pandas as pd
+
+from pydeflate.core.deflator import ExchangeDeflator, PriceDeflator
+from pydeflate.core.exchange import Exchange
+from pydeflate.core.source import Source
+from pydeflate.sources.common import AvailableDeflators
+from pydeflate.utils import (
+    create_pydeflate_year,
+    merge_user_and_pydeflate_data,
+    get_unmatched_pydeflate_data,
+    get_matched_pydeflate_data,
+    flag_missing_pydeflate_data,
+)
+
+
+def resolve_common_currencies(currency: str, source: str) -> str:
+    mapping = {
+        "USD": "USA",
+        "EUR": "EMU",
+        "GBP": "GBR",
+        "JPY": "JPN",
+        "CAD": "CAN",
+    }
+
+    if source == "DAC":
+        mapping["EUR"] = "EUI"
+
+    return mapping.get(currency, currency)
+
+
+def _base_operation(
+    base_obj,
+    data: pd.DataFrame,
+    entity_column: str,
+    year_column: str,
+    value_column: str,
+    target_value_column: str | None = None,
+    year_format: str | None = None,
+    exchange: bool = False,
+    reversed_: bool = False,
+):
+    """Perform deflation or exchange rate adjustment on input data using pydeflate data.
+
+    Args:
+        base_obj (BaseExchange | BaseDeflate): The base object containing pydeflate data.
+        data (pd.DataFrame): Data to be adjusted.
+        entity_column (str): Column with entity or country identifiers.
+        year_column (str): Column with year information.
+        value_column (str): Column with values to be adjusted.
+        target_value_column (str | None, optional): Column to store adjusted values. Defaults to `value_column`.
+        year_format (str, optional): Format of the year. Defaults to "%Y".
+        exchange (bool, optional): Whether to perform an exchange rate adjustment (True)
+        or deflation (False).
+        reversed_ (bool, optional): If True, perform the operation in reverse.
+
+    Returns:
+        pd.DataFrame: DataFrame with adjusted values and original columns preserved.
+    """
+    # Make a copy of the input data to avoid modifying the original data
+    data = data.copy(deep=True)
+
+    target_value_column = target_value_column or value_column
+
+    # Keep track of original columns to return data in the same order.
+    cols = (
+        [*data.columns, target_value_column]
+        if target_value_column not in data.columns
+        else data.columns
+    )
+
+    # Merge pydeflate data to the input data
+    base_obj._merge_pydeflate_data(
+        data=data,
+        entity_column=entity_column,
+        year_column=year_column,
+        year_format=year_format,
+    )
+
+    # Flag missing data
+    flag_missing_pydeflate_data(base_obj._unmatched_data)
+    x = base_obj._merged_data[value_column]
+    y = base_obj._merged_data[
+        "pydeflate_EXCHANGE" if exchange else "pydeflate_deflator"
+    ]
+
+    # Apply the correct operation based on `exchange` and `reversed`
+    if (exchange and not reversed_) or (not exchange and reversed_):
+        base_obj._merged_data[target_value_column] = (x * y).round(6)
+    else:
+        base_obj._merged_data[target_value_column] = (x / y).round(6)
+
+    return base_obj._merged_data[cols]
+
+
+class BaseExchange:
+    """Performs currency exchange rate conversions within data, using pydeflate.
+
+    Provides methods to merge pydeflate exchange rate data with user data and apply
+    exchange rate adjustments, allowing for straightforward currency conversions
+    within a dataset.
+    """
+
+    def __init__(
+        self,
+        exchange_source: Source,
+        source_currency: str,
+        target_currency: str,
+        use_source_codes: bool = False,
+    ):
+        """Initialize a BaseExchange instance with exchange rate data and identifiers.
+
+        Args:
+            exchange_source (Source): Data source for exchange rates.
+            source_currency (str): Original currency for conversion.
+            target_currency (str): Target currency for conversion.
+            use_source_codes (bool, optional): Use source-specific entity codes.
+             Defaults to False.
+        """
+
+        # Try to accept common currencies by their country codes
+        source_currency = resolve_common_currencies(
+            source_currency, exchange_source.name
+        )
+
+        target_currency = resolve_common_currencies(
+            target_currency, exchange_source.name
+        )
+
+        self.exchange_rates = Exchange(
+            source=exchange_source,
+            source_currency=source_currency,
+            target_currency=target_currency,
+        )
+
+        self._idx = [
+            "pydeflate_year",
+            "pydeflate_entity_code" if use_source_codes else "pydeflate_iso3",
+        ]
+
+        self._load_pydeflate_data()
+
+    def _load_pydeflate_data(self) -> None:
+        """Load and prepare pydeflate exchange rate data."""
+        self.pydeflate_data = (
+            self.exchange_rates.exchange_data.set_index(self._idx)
+            .dropna(how="any")
+            .reset_index()
+        )
+
+    def _merge_pydeflate_data(
+        self,
+        data: pd.DataFrame,
+        entity_column: str,
+        year_column: str,
+        year_format: str | None = None,
+    ) -> None:
+        """Merge pydeflate exchange rate data into input data by year and entity.
+
+        Args:
+            data (pd.DataFrame): Input DataFrame to merge with pydeflate data.
+            entity_column (str): Column name for entity or country codes.
+            year_column (str): Column name for year information.
+            year_format (str, optional): Year format. Defaults to '%Y'.
+        """
+
+        # Convert the year to an integer
+        data = create_pydeflate_year(
+            data=data, year_column=year_column, year_format=year_format
+        )
+
+        # Merge data to the input data based on year and entity
+        merged_data = merge_user_and_pydeflate_data(
+            data=data,
+            pydeflate_data=self.pydeflate_data,
+            entity_column=entity_column,
+            ix=self._idx,
+        )
+
+        # store unmatched data
+        self._unmatched_data = get_unmatched_pydeflate_data(merged_data=merged_data)
+
+        # store matched data
+        self._merged_data = get_matched_pydeflate_data(merged_data=merged_data)
+
+    def exchange(
+        self,
+        data: pd.DataFrame,
+        entity_column: str,
+        year_column: str,
+        value_column: str,
+        target_value_column: str | None = None,
+        year_format: str | None = None,
+        reversed_: bool = False,
+    ):
+        """Apply exchange rate conversion to input data.
+
+        Args:
+            data (pd.DataFrame): Data to apply exchange rate adjustment.
+            entity_column (str): Column with entity identifiers.
+            year_column (str): Column with year information.
+            value_column (str): Column with values to adjust.
+            target_value_column (str | None, optional): Column for adjusted values. Defaults to `value_column`.
+            year_format (str, optional): Format of the year. Defaults to "%Y".
+            reversed_ (bool, optional): If True, perform the operation in reverse. defaults to False.
+
+        Returns:
+            pd.DataFrame: DataFrame with exchange rate-adjusted values.
+        """
+        return _base_operation(
+            base_obj=self,
+            exchange=True,
+            data=data,
+            entity_column=entity_column,
+            year_column=year_column,
+            value_column=value_column,
+            target_value_column=target_value_column,
+            year_format=year_format,
+            reversed_=reversed_,
+        )
+
+
+class BaseDeflate:
+    """Deflating monetary values over time with exchange rates and price indices.
+
+    Combines price deflators, exchange rate deflators, and pydeflate data to allow
+    for adjustments of monetary values across different time periods, enabling accurate
+    economic comparisons over time.
+    """
+
+    def __init__(
+        self,
+        deflator_source: Source,
+        exchange_source: Source,
+        base_year: int,
+        price_kind: AvailableDeflators,
+        source_currency: str,
+        target_currency: str,
+        use_source_codes: bool = False,
+        to_current: bool = False,
+    ):
+        """Initialize a BaseDeflate instance with deflator and exchange rate sources.
+
+        Args:
+            deflator_source (Source): Data source for price deflators.
+            exchange_source (Source): Data source for exchange rates.
+            base_year (int): Reference year for base value adjustments.
+            price_kind (AvailableDeflators): Type of deflator (e.g., CPI).
+            source_currency (str): Currency of the input data.
+            target_currency (str): Currency for conversion.
+            use_source_codes (bool, optional): Use source-specific entity codes. Defaults to False.
+            to_current (bool, optional): If True, adjust to current year values. Defaults to False.
+        """
+
+        # Try to accept common currencies by their country codes
+        source_currency = resolve_common_currencies(
+            source_currency, deflator_source.name
+        )
+
+        target_currency = resolve_common_currencies(
+            target_currency, deflator_source.name
+        )
+        self.exchange_rates = Exchange(
+            source=exchange_source,
+            source_currency=source_currency,
+            target_currency=target_currency,
+        )
+
+        self.exchange_deflator = ExchangeDeflator(
+            source=self.exchange_rates, base_year=base_year
+        )
+
+        self.price_deflator = PriceDeflator(
+            source=deflator_source, kind=price_kind, base_year=base_year
+        )
+
+        self._idx = [
+            "pydeflate_year",
+            "pydeflate_entity_code" if use_source_codes else "pydeflate_iso3",
+        ]
+
+        self.use_source_codes = use_source_codes
+        self.to_current = to_current
+
+        self.__post_init__()
+
+    def __post_init__(self):
+        """Post-initialization process to merge deflator, exchange, and pydeflate data."""
+
+        # Merge deflator and exchange rate data
+        data = self._merge_components(
+            df=self.price_deflator.deflator_data,
+            other=self.exchange_deflator.deflator_data,
+        ).pipe(self._merge_components, other=self.exchange_rates.exchange_data)
+
+        # drop where necessary data is missing
+        data = data.set_index(self._idx).dropna(how="any").reset_index()
+
+        # Calculate price-exchange deflator
+        data["pydeflate_deflator"] = self._calculate_deflator_value(
+            data[f"pydeflate_{self.price_deflator.price_kind}"],
+            data["pydeflate_EXCHANGE_D"],
+            data[f"pydeflate_EXCHANGE"],
+        )
+
+        self.pydeflate_data = data
+
+    def _calculate_deflator_value(
+        self, price_def: pd.Series, exchange_def: pd.Series, exchange_rate: pd.Series
+    ):
+        """Compute the combined deflator value using price deflator, exchange deflator, and rates.
+
+        Args:
+            price_def (pd.Series): Series of price deflator values.
+            exchange_def (pd.Series): Series of exchange deflator values.
+            exchange_rate (pd.Series): Series of exchange rates.
+
+        Returns:
+            pd.Series: Series with combined deflator values.
+        """
+        return (
+            (10_000 * exchange_rate) / (price_def * exchange_def)
+            if self.to_current
+            else (price_def * exchange_def) / (10_000 * exchange_rate)
+        )
+
+    def _merge_components(self, df: pd.DataFrame, other: pd.DataFrame):
+        """Combine data components, merging deflator and exchange rate information.
+
+        Args:
+            df (pd.DataFrame): Main DataFrame for merging.
+            other (pd.DataFrame): Additional data to merge into `df`.
+
+        Returns:
+            pd.DataFrame: Merged DataFrame without duplicate columns.
+        """
+        merged = df.merge(other, how="outer", on=self._idx, suffixes=("", "_ex"))
+        return merged.drop(columns=merged.filter(regex=f"_ex$").columns, axis=1)
+
+    def _merge_pydeflate_data(
+        self,
+        data: pd.DataFrame,
+        entity_column: str,
+        year_column: str,
+        year_format: str | None = None,
+    ) -> None:
+        """Merge pydeflate deflator data into the input data by year and entity.
+
+        Args:
+            data (pd.DataFrame): Input DataFrame to merge with pydeflate data.
+            entity_column (str): Column for entity or country identifiers.
+            year_column (str): Column for year information.
+            year_format (str, optional): Format of the year. Defaults to '%Y'.
+        """
+
+        # Convert the year to an integer
+        data = create_pydeflate_year(
+            data=data, year_column=year_column, year_format=year_format
+        )
+
+        # Merge data to the input data based on year and entity
+        merged_data = merge_user_and_pydeflate_data(
+            data=data,
+            pydeflate_data=self.pydeflate_data,
+            entity_column=entity_column,
+            ix=self._idx,
+        )
+
+        # store unmatched data
+        self._unmatched_data = get_unmatched_pydeflate_data(merged_data=merged_data)
+
+        # store matched data
+        self._merged_data = get_matched_pydeflate_data(merged_data=merged_data)
+
+    def deflate(
+        self,
+        data: pd.DataFrame,
+        entity_column: str,
+        year_column: str,
+        value_column: str,
+        target_value_column: str | None = None,
+        year_format: str | None = None,
+    ):
+        """Apply deflation adjustment to input data using pydeflate deflator rates.
+
+        Args:
+            data (pd.DataFrame): Data for deflation adjustment.
+            entity_column (str): Column with entity identifiers.
+            year_column (str): Column with year information.
+            value_column (str): Column with values to deflate.
+            target_value_column (str | None, optional): Column to store deflated values. Defaults to `value_column`.
+            year_format (str, optional): Format of the year. Defaults to "%Y".
+
+        Returns:
+            pd.DataFrame: DataFrame with deflated values.
+        """
+        return _base_operation(
+            base_obj=self,
+            data=data,
+            entity_column=entity_column,
+            year_column=year_column,
+            value_column=value_column,
+            target_value_column=target_value_column,
+            year_format=year_format,
+        )

pydeflate/core/deflator.py

@@ -0,0 +1,171 @@
+from dataclasses import dataclass, field
+from typing import Literal
+
+import pandas as pd
+
+from pydeflate.core.exchange import Exchange
+from pydeflate.core.source import Source
+from pydeflate.sources.common import AvailableDeflators
+
+
+@dataclass
+class Deflator:
+    """A class to manage and process deflator data.
+
+    This class holds deflators and provides methods to apply exchange rates
+    for conversions between source and target currencies.
+
+    """
+
+    source: Source | Exchange
+    deflator_type: Literal["price", "exchange"]
+    price_kind: AvailableDeflators | None
+    base_year: int
+    deflator_data: pd.DataFrame = field(default_factory=pd.DataFrame)
+
+    def __post_init__(self):
+        """Processes the deflator data based on the deflator type.
+
+        Initializes the `deflator_data` attribute by fetching and processing
+        the appropriate deflator data from the source.
+
+        Raises:
+            ValueError: If the combination of `deflator_type` and `price_kind` is invalid.
+        """
+
+        # If price deflator, fetch the price deflator data
+        if self.deflator_type == "price":
+            if self.price_kind is None:
+                raise ValueError(
+                    "`price_kind` must be specified when `deflator_type` is 'price'."
+                )
+            self.deflator_data = self.source.price_deflator(kind=self.price_kind)
+
+        # If exchange deflator, fetch the exchange deflator data
+        elif self.deflator_type == "exchange":
+            if self.price_kind is not None:
+                raise ValueError(
+                    "`price_kind` should be None when `deflator_type` is 'exchange'."
+                )
+            self.deflator_data = self.source.deflator()
+            self.source = self.source.source
+
+        else:
+            raise ValueError(f"Invalid deflator type: {self.deflator_type}")
+
+        # Rebase the deflator data to the specified base year
+        self.rebase_deflator()
+
+    def _extract_base_year_values(self, value_column: str) -> pd.DataFrame:
+        """Extracts the base year values from the deflator data."""
+
+        # Extract base year values
+        base_year_values = (
+            self.deflator_data[self.deflator_data["pydeflate_year"] == self.base_year]
+            .rename(columns={value_column: "base_year_value"})
+            .drop(columns=["pydeflate_year"])
+        )
+
+        if base_year_values.empty:
+            raise ValueError(f"No data found for base year {self.base_year}.")
+        return base_year_values
+
+    @staticmethod
+    def _ensure_deflator_suffix(value_column: str) -> str:
+        """Ensures that the value column ends with the '_D' suffix."""
+        return value_column if value_column.endswith("_D") else value_column + "_D"
+
+    def _get_deflator_value_column(self) -> str:
+        """Identifies the value column in the deflator data."""
+        # Identify the value column
+        value_column = self.deflator_data.columns.difference(self.source._idx).tolist()
+
+        if len(value_column) != 1:
+            raise ValueError("Invalid deflator data format.")
+
+        return value_column[0]
+
+    def rebase_deflator(self) -> None:
+        """Rebases the deflator data to the specified base year.
+
+        Adjusts the deflator values so that the base year values are set to 100.
+
+        Raises:
+            ValueError: If `deflator_data` is empty, has an invalid format, or lacks data for the base year.
+        """
+
+        # Check if deflator data is empty
+        if self.deflator_data.empty:
+            raise ValueError("No deflator data found.")
+
+        # Identify the value column
+        value_column = self._get_deflator_value_column()
+
+        # Extract base year values
+        base_year_values = self._extract_base_year_values(value_column)
+
+        # Merge base year values back into the main DataFrame
+        rebased = self.deflator_data.merge(
+            base_year_values,
+            on=[c for c in self.source._idx if c != "pydeflate_year"],
+            how="left",
+        )
+
+        # if value column doesn't end in _D, add it
+        original_value_column = value_column
+        value_column = self._ensure_deflator_suffix(value_column)
+
+        # Rebase the deflator values
+        rebased[value_column] = (
+            100 * rebased[original_value_column] / rebased["base_year_value"]
+        ).round(6)
+
+        # Update the deflator data
+        self.deflator_data = rebased.drop(columns=["base_year_value"])
+
+
+class ExchangeDeflator(Deflator):
+    """Manages and processes exchange rate deflators.
+
+    Using exchange rate data (local currency to USD) provided by the source.
+    It normalizes exchange rate deflators to a specified base year, allowing
+    consistent comparisons over time.
+
+    Args:
+        source (Source): The source from which to fetch exchange rate data.
+        base_year (int): The base year to rebase the deflator data.
+    """
+
+    def __init__(self, source: Exchange, base_year: int):
+        super().__init__(
+            source=source,
+            deflator_type="exchange",
+            price_kind=None,
+            base_year=base_year,
+        )
+
+
+class PriceDeflator(Deflator):
+    """Manages and processes price deflators data.
+
+    It fetches price deflator data from the provided source and normalizes it to a specified
+    base year, allowing for inflation-adjusted comparisons over time.
+
+    Args:
+        source (Source): The source from which to fetch price deflator data.
+        kind (AvailableDeflators): The type of price deflator to apply (e.g., GDP deflator or CPI).
+        base_year (int): The base year to rebase the deflator data.
+    """
+
+    def __init__(
+        self,
+        source: Source,
+        kind: AvailableDeflators,
+        base_year: int,
+    ):
+        super().__init__(
+            source=source,
+            deflator_type="price",
+            price_kind=kind,
+            base_year=base_year,
+        )