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

pydeflate/core/exchange.py

@@ -0,0 +1,237 @@
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+from pydeflate.core.source import Source
+from pydeflate.sources.common import compute_exchange_deflator
+
+
+@dataclass
+class Exchange:
+    """A class to manage and process exchange rate data for currency conversions.
+
+    This class holds exchange rate data and provides methods to apply exchange rates
+    for conversions between source and target currencies.
+
+    Attributes:
+        source (Source): An instance of the Source class to fetch exchange rate data.
+        source_currency (str): The source currency code (default is 'LCU' - Local Currency Unit).
+        target_currency (str): The target currency code (default is 'USA' - US Dollar).
+        exchange_data (pd.DataFrame): DataFrame holding the exchange rate data.
+    """
+
+    source: Source
+    source_currency: str = "LCU"
+    target_currency: str = "USA"
+    exchange_data: pd.DataFrame = field(default_factory=pd.DataFrame)
+
+    def __post_init__(self):
+        """Initialize the Exchange object and process the exchange rate data."""
+        # Load and filter the relevant columns from the exchange rate data
+        self.exchange_data = self.source.lcu_usd_exchange()
+
+        if self.source_currency == self.target_currency:
+            self.exchange_data = self.exchange_rate("LCU", self.target_currency)
+            self.exchange_data["pydeflate_EXCHANGE"] = 1
+        else:
+            self.exchange_data = self.exchange_rate(
+                self.source_currency, self.target_currency
+            )
+
+    def _get_exchange_rate(self, currency):
+        """Helper function to fetch exchange rates for a given currency."""
+        exchange_rate = self.exchange_data.loc[
+            self.exchange_data["pydeflate_iso3"] == currency
+        ]
+        return exchange_rate
+
+    def _convert_exchange(self, to_: str) -> pd.DataFrame:
+        """Converts exchange rates based on the target currency.
+
+        This method retrieves exchange rates for a given target currency, merges the
+        target exchange rates with the base exchange rates, and computes the final
+        exchange rate by dividing the base exchange rate by the target exchange rate.
+
+        Args:
+            to_ (str): The target currency code.
+
+        Returns:
+            pd.DataFrame: A DataFrame with the adjusted exchange rates for the target currency.
+
+        Raises:
+            ValueError: If no exchange rate data is available for the target currency.
+        """
+
+        if to_ == "LCU":
+            return self.exchange_data.copy().assign(pydeflate_EXCHANGE=1)
+
+        usd_rate = self.exchange_data.copy()
+        target_exchange = self._get_exchange_rate(to_)
+
+        if target_exchange.empty:
+            raise ValueError(f"No currency exchange data for {to_=}")
+
+        merged = pd.merge(
+            usd_rate,
+            target_exchange,
+            how="left",
+            on=["pydeflate_year"],
+            suffixes=("", "_to"),
+        ).assign(
+            pydeflate_EXCHANGE=lambda d: d.pydeflate_EXCHANGE / d.pydeflate_EXCHANGE_to,
+        )
+
+        return merged.drop(columns=merged.filter(regex="_to$").columns, axis=1)
+
+    def exchange_rate(self, from_currency: str, to_currency: str):
+        """Calculates the exchange rates between the source and target currencies.
+
+        Args:
+            from_currency (str): The source currency code.
+            to_currency (str): The target currency code.
+
+        Returns:
+            None
+        """
+        # Get exchange data based on the source currency.
+        source = self._convert_exchange(to_=from_currency)
+
+        # Get exchange data based on the target currency.
+        target = self._convert_exchange(to_=to_currency)
+
+        # Merge the source and target exchange data and compute the final exchange rate.
+        merged = pd.merge(
+            source,
+            target,
+            how="left",
+            on=["pydeflate_year", "pydeflate_entity_code", "pydeflate_iso3"],
+            suffixes=("", "_to"),
+        ).assign(
+            pydeflate_EXCHANGE=lambda d: d.pydeflate_EXCHANGE / d.pydeflate_EXCHANGE_to
+        )
+
+        # Drop unnecessary columns
+        merged = merged.drop(columns=merged.filter(regex="_to$").columns, axis=1)
+
+        # Compute the exchange rate deflator
+        merged = compute_exchange_deflator(
+            merged,
+            exchange="pydeflate_EXCHANGE",
+            year="pydeflate_year",
+            grouper=["pydeflate_entity_code", "pydeflate_iso3"],
+        )
+
+        return merged
+
+    def exchange(
+        self,
+        data: pd.DataFrame,
+        value_column: str,
+        entity_column: str,
+        year_column: str,
+        year_format: str = "%Y",
+        use_source_codes: bool = False,
+    ) -> pd.DataFrame:
+        """Apply the exchange rate to the given data to convert it to the target currency.
+
+        Args:
+            data (pd.DataFrame): The input DataFrame containing values to be exchanged.
+            value_column (str): The column name containing the values to be converted.
+            entity_column (str): The column name containing the entity or country codes.
+            year_column (str): The column name containing the year information.
+            year_format (str, optional): The format of the year (default is '%Y').
+            use_source_codes (bool, optional): Whether to use source entity codes
+            instead of ISO3 (default is False).
+
+        Returns:
+            pd.DataFrame: DataFrame with the values converted to the target currency.
+        """
+
+        # Convert the year to an integer
+        data["pydeflate_year"] = pd.to_datetime(
+            data[year_column], format=year_format
+        ).dt.year
+
+        # exchange columns
+        exchange_cols = [
+            "pydeflate_year",
+            "pydeflate_entity_code",
+            "pydeflate_iso3",
+            "pydeflate_EXCHANGE",
+        ]
+
+        # Merge exchange rate data to the input data based on year and entity
+        merged_data = data.merge(
+            self.exchange_data.filter(exchange_cols),
+            how="left",
+            left_on=["pydeflate_year", entity_column],
+            right_on=[
+                "pydeflate_year",
+                "pydeflate_entity_code" if use_source_codes else "pydeflate_iso3",
+            ],
+        )
+
+        # Apply the exchange rate to convert the value column
+        merged_data[value_column] = (
+            merged_data[value_column] / merged_data["pydeflate_EXCHANGE"]
+        )
+
+        # Drop all columns that start with pydeflate_ merging and return the result
+        return merged_data.filter(regex="^(?!pydeflate_)")
+
+    def deflator(self) -> pd.DataFrame:
+        """Get the exchange rate deflator data.
+
+        Returns:
+            pd.DataFrame: DataFrame with the exchange rate deflator data.
+        """
+
+        return self.exchange_data.filter(
+            [
+                "pydeflate_year",
+                "pydeflate_entity_code",
+                "pydeflate_iso3",
+                "pydeflate_EXCHANGE_D",
+            ]
+        )
+
+    def merge_deflator(
+        self,
+        data: pd.DataFrame,
+        entity_column: str,
+        year_column: str,
+        year_format: str = "%Y",
+        use_source_codes: bool = False,
+    ) -> pd.DataFrame:
+        """Merge the deflator data to the input data based on year and entity.
+
+        Args:
+            data (pd.DataFrame): The input DataFrame
+            entity_column (str): The column name containing the entity or country codes.
+            year_column (str): The column name containing the year information.
+            year_format (str, optional): The format of the year (default is '%Y').
+            use_source_codes (bool, optional): Whether to use source entity codes
+            instead of ISO3 (default is False).
+
+        Returns:
+            pd.DataFrame: DataFrame with the deflator data merged to the input data.
+
+        """
+
+        # Convert the year to an integer
+        data["pydeflate_year"] = pd.to_datetime(
+            data[year_column], format=year_format
+        ).dt.year
+
+        # Merge exchange rate data to the input data based on year and entity
+        merged_data = data.merge(
+            self.deflator(),
+            how="left",
+            left_on=["pydeflate_year", entity_column],
+            right_on=[
+                "pydeflate_year",
+                "pydeflate_entity_code" if use_source_codes else "pydeflate_iso3",
+            ],
+        )
+
+        return merged_data.filter(regex="^(?!pydeflate_)")

pydeflate/core/source.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field
+
+import pandas as pd
+
+from pydeflate.sources.common import AvailableDeflators
+from pydeflate.sources.dac import read_dac
+from pydeflate.sources.imf import read_weo
+from pydeflate.sources.world_bank import read_wb
+
+
+@dataclass
+class Source:
+    name: str
+    reader: callable
+    update: bool = False
+    data: pd.DataFrame = field(default_factory=pd.DataFrame)
+    _idx = ["pydeflate_year", "pydeflate_entity_code", "pydeflate_iso3"]
+
+    def __post_init__(self):
+        self.data = self.reader(self.update)
+        self.validate()
+
+    def validate(self):
+        if self.data.empty:
+            raise ValueError(f"No data found for {self.name}")
+
+        # check all columns start with pydeflate_
+        if not all(col.startswith("pydeflate_") for col in self.data.columns):
+            raise ValueError(f"Invalid data format for {self.name}")
+
+    def lcu_usd_exchange(self) -> pd.DataFrame:
+        return self.data.filter(self._idx + ["pydeflate_EXCHANGE"])
+
+    def price_deflator(self, kind: AvailableDeflators = "NGDP_D") -> pd.DataFrame:
+
+        if f"pydeflate_{kind}" not in self.data.columns:
+            raise ValueError(f"No deflator data found for {kind} in {self.name} data.")
+
+        return self.data.filter(self._idx + [f"pydeflate_{kind}"])
+
+
+class IMF(Source):
+    def __init__(self, update: bool = False):
+        super().__init__(name="IMF", reader=read_weo, update=update)
+
+
+class WorldBank(Source):
+    def __init__(self, update: bool = False):
+        super().__init__(name="World Bank", reader=read_wb, update=update)
+
+
+class DAC(Source):
+    def __init__(self, update: bool = False):
+        super().__init__(name="DAC", reader=read_dac, update=update)

pydeflate/deflate/deflators.py

@@ -0,0 +1,228 @@
+from functools import wraps
+
+import pandas as pd
+
+from pydeflate.core.api import BaseDeflate
+from pydeflate.core.source import DAC, WorldBank, IMF
+
+
+def _generate_docstring(source_name: str, price_kind: str) -> str:
+    """Generate docstring for each decorated deflation function."""
+    return (
+        f"Deflate a DataFrame using the {source_name} deflator source ({price_kind}).\n\n"
+        f"This function applies deflation adjustments to a DataFrame using the {source_name} {price_kind} deflator.\n\n"
+        "Args:\n"
+        "    data (pd.DataFrame): The input DataFrame containing data to deflate.\n"
+        "    base_year (int): The base year for calculating deflation adjustments.\n"
+        "    source_currency (str, optional): The source currency code. Defaults to 'USA'.\n"
+        "    target_currency (str, optional): The target currency code. Defaults to 'USA'.\n"
+        "    id_column (str, optional): Column with entity identifiers. Defaults to 'iso_code'.\n"
+        "    year_column (str, optional): Column with year information. Defaults to 'year'.\n"
+        "    use_source_codes (bool, optional): Use source-specific entity codes. Defaults to False.\n"
+        "    value_column (str, optional): Column with values to deflate. Defaults to 'value'.\n"
+        "    target_value_column (str, optional): Column to store deflated values. Defaults to 'value'.\n"
+        "    to_current (bool, optional): Adjust values to current-year values if True. Defaults to False.\n"
+        "    year_format (str | None, optional): Format of the year in `year_column`. Defaults to None.\n"
+        "    update_deflators (bool, optional): Update the deflator data before deflation. Defaults to False.\n\n"
+        "Returns:\n"
+        "    pd.DataFrame: DataFrame with deflated values in the `target_value_column`.\n"
+    )
+
+
+def _deflator(deflator_source_cls, price_kind):
+    """Decorator to create deflate wrappers with specific deflator source and price kind."""
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(
+            data: pd.DataFrame,
+            *,
+            base_year: int,
+            source_currency: str = "USA",
+            target_currency: str = "USA",
+            id_column: str = "iso_code",
+            year_column: str = "year",
+            use_source_codes: bool = False,
+            value_column: str = "value",
+            target_value_column: str = "value",
+            to_current: bool = False,
+            year_format: str | None = None,
+            update_deflators: bool = False,
+        ):
+            # Validate input parameters
+            if not isinstance(data, pd.DataFrame):
+                raise ValueError("The 'data' parameter must be a pandas DataFrame.")
+            if not isinstance(base_year, int):
+                raise ValueError("The 'base_year' parameter must be an integer.")
+            if id_column not in data.columns:
+                raise ValueError(
+                    f"The id_column '{id_column}' is not in the DataFrame."
+                )
+            if year_column not in data.columns:
+                raise ValueError(
+                    f"The year_column '{year_column}' is not in the DataFrame."
+                )
+            if value_column not in data.columns:
+                raise ValueError(
+                    f"The value_column '{value_column}' is not in the DataFrame."
+                )
+
+            # Copy the data to avoid modifying the original
+            to_deflate = data.copy()
+
+            # Initialize the deflator source
+            source = deflator_source_cls(update=update_deflators)
+
+            # Create a deflator object
+            deflator = BaseDeflate(
+                base_year=base_year,
+                deflator_source=source,
+                exchange_source=source,
+                source_currency=source_currency,
+                target_currency=target_currency,
+                price_kind=price_kind,
+                use_source_codes=use_source_codes,
+                to_current=to_current,
+            )
+
+            # Deflate the data
+            return deflator.deflate(
+                data=to_deflate,
+                entity_column=id_column,
+                year_column=year_column,
+                value_column=value_column,
+                target_value_column=target_value_column,
+                year_format=year_format,
+            )
+
+        # Add the deflator source and price kind to the function
+        wrapper.__doc__ = _generate_docstring(deflator_source_cls.__name__, price_kind)
+        return wrapper
+
+    return decorator
+
+
+@_deflator(DAC, "NGDP_D")
+def oecd_dac_deflate(
+    data: pd.DataFrame,
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    year_column: str = "year",
+    use_source_codes: bool = False,
+    value_column: str = "value",
+    target_value_column: str = "value",
+    to_current: bool = False,
+    year_format: str | None = None,
+    update_deflators: bool = False,
+) -> pd.DataFrame: ...
+
+
+@_deflator(WorldBank, "NGDP_D")
+def wb_gdp_deflate(
+    data: pd.DataFrame,
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    year_column: str = "year",
+    use_source_codes: bool = False,
+    value_column: str = "value",
+    target_value_column: str = "value",
+    to_current: bool = False,
+    year_format: str | None = None,
+    update_deflators: bool = False,
+): ...
+
+
+@_deflator(WorldBank, "NGDP_D")
+def wb_gdp_linked_deflate(
+    data: pd.DataFrame,
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    year_column: str = "year",
+    use_source_codes: bool = False,
+    value_column: str = "value",
+    target_value_column: str = "value",
+    to_current: bool = False,
+    year_format: str | None = None,
+    update_deflators: bool = False,
+): ...
+
+
+@_deflator(WorldBank, "CPI")
+def wb_cpi_deflate(
+    data: pd.DataFrame,
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    year_column: str = "year",
+    use_source_codes: bool = False,
+    value_column: str = "value",
+    target_value_column: str = "value",
+    to_current: bool = False,
+    year_format: str | None = None,
+    update_deflators: bool = False,
+): ...
+
+
+@_deflator(IMF, "NGDP_D")
+def imf_gdp_deflate(
+    data: pd.DataFrame,
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    year_column: str = "year",
+    use_source_codes: bool = False,
+    value_column: str = "value",
+    target_value_column: str = "value",
+    to_current: bool = False,
+    year_format: str | None = None,
+    update_deflators: bool = False,
+): ...
+
+
+@_deflator(IMF, "PCPI")
+def imf_cpi_deflate(
+    data: pd.DataFrame,
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    year_column: str = "year",
+    use_source_codes: bool = False,
+    value_column: str = "value",
+    target_value_column: str = "value",
+    to_current: bool = False,
+    year_format: str | None = None,
+    update_deflators: bool = False,
+): ...
+
+
+@_deflator(IMF, "PCPIE")
+def imf_cpi_e_deflate(
+    data: pd.DataFrame,
+    *,
+    base_year: int,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    year_column: str = "year",
+    use_source_codes: bool = False,
+    value_column: str = "value",
+    target_value_column: str = "value",
+    to_current: bool = False,
+    year_format: str | None = None,
+    update_deflators: bool = False,
+): ...

pydeflate/deflate/legacy_deflate.py

@@ -0,0 +1,109 @@
+import warnings
+
+import pandas as pd
+from pandas.util._decorators import deprecate_kwarg
+
+from pydeflate.core.api import BaseDeflate
+from pydeflate.core.source import DAC, WorldBank, IMF
+
+
+@deprecate_kwarg(old_arg_name="method", new_arg_name="deflator_method")
+@deprecate_kwarg(old_arg_name="source", new_arg_name="deflator_source")
+@deprecate_kwarg(old_arg_name="iso_column", new_arg_name="id_column")
+@deprecate_kwarg(old_arg_name="source_col", new_arg_name="source_column")
+@deprecate_kwarg(old_arg_name="target_col", new_arg_name="target_column")
+def deflate(
+    df: pd.DataFrame,
+    base_year: int,
+    deflator_source: str,
+    deflator_method: str,
+    exchange_source: str,
+    exchange_method: str,
+    source_currency: str = "USA",
+    target_currency: str = "USA",
+    id_column: str = "iso_code",
+    id_type: str = "ISO3",
+    date_column: str = "date",
+    source_column: str = "value",
+    target_column: str = "value",
+    to_current: bool = False,
+) -> pd.DataFrame:
+    """DEPRECATED: Use pydeflate's updated API for deflation adjustments.
+
+    This legacy function is provided for backwards compatibility only.
+    Please refer to the latest documentation for using pydeflate's updated API.
+
+    Args:
+        df (pd.DataFrame): DataFrame with flow data to be deflated.
+        base_year (int): Target year for base value adjustments.
+        deflator_source (str): Source of deflator data, e.g., 'oecd_dac', 'wb', 'imf'.
+        deflator_method (str): Method for deflator calculation, e.g., 'gdp', 'cpi'.
+        exchange_source (str): Source for exchange rates.
+        exchange_method (str): Method for exchange rate calculation.
+        source_currency (str): ISO3 code for the source currency.
+        target_currency (str): ISO3 code for the target currency.
+        id_column (str): Column for entity identifiers, e.g., 'iso_code'.
+        id_type (str): Type of ID classification; default is 'ISO3'.
+        date_column (str): Column for date information.
+        source_column (str): Column with original monetary values.
+        target_column (str): Column to store deflated values.
+        to_current (bool): If True, convert to current prices.
+
+    Returns:
+        pd.DataFrame: DataFrame with deflated values.
+    """
+    warnings.warn(
+        "The `deflate` function is deprecated and will be removed in future versions. "
+        "Please check the latest documentation for updated methods.",
+        DeprecationWarning,
+    )
+
+    if id_type != "ISO3":
+        raise ValueError(
+            "Only ISO3 ID classification is supported in this version.\n"
+            "You can use bblocks to convert to ISO3."
+        )
+
+    price_kind = {
+        "oecd_dac": "NGDP_D",
+        "dac_deflator": "NGDP_D",
+        "gdp": "NGDP_D",
+        "cpi": "CPI",
+    }
+
+    # Mapping of string identifiers to classes and price kinds
+    deflator_source_map = {
+        "oecd_dac": DAC,
+        "dac": DAC,
+        "wb": WorldBank,
+        "world_bank": WorldBank,
+        "imf": IMF,
+    }
+
+    deflator_source = deflator_source_map[deflator_source.lower()]()
+    exchange_source = deflator_source_map[exchange_source.lower()]()
+    deflator_method = price_kind.get(deflator_method.lower(), deflator_method).upper()
+
+    # Copy the data to avoid modifying the original
+    to_deflate = df.copy()
+
+    # Create a deflator object
+    deflator = BaseDeflate(
+        base_year=base_year,
+        deflator_source=deflator_source,
+        exchange_source=exchange_source,
+        source_currency=source_currency,
+        target_currency=target_currency,
+        price_kind=deflator_method,
+        to_current=to_current,
+    )
+
+    # Deflate the data
+    return deflator.deflate(
+        data=to_deflate,
+        entity_column=id_column,
+        year_column=date_column,
+        value_column=source_column,
+        target_value_column=target_column,
+        year_format=None,
+    )