PYield 0.24.0__tar.gz → 0.24.2__tar.gz

{pyield-0.24.0 → pyield-0.24.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: PYield
-Version: 0.24.0
+Version: 0.24.2
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Project-URL: Source, https://github.com/crdcj/PYield
 Author-email: Carlos Carvalho <cr.cj@outlook.com>

pyield-0.24.2/pyield/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.24.2"

{pyield-0.24.0 → pyield-0.24.2}/pyield/bonds/bond_tools.py

@@ -77,7 +77,7 @@ def pre_spreads(reference_date: DateScalar) -> pd.DataFrame:
     """
     # Fetch DI rates for the reference date
     converted_date = dc.convert_input_dates(reference_date)
-    di = DIFutures(trade_dates=converted_date, adj_expirations=True)
+    di = DIFutures(trade_dates=converted_date, month_start=True)
     df_di = di.data
     if "SettlementRate" not in df_di.columns:
         raise ValueError("DI rates data is missing the 'SettlementRate' column.")

{pyield-0.24.0 → pyield-0.24.2}/pyield/bonds/ntnf.py

@@ -3,7 +3,7 @@ from collections.abc import Callable
 import numpy as np
 import pandas as pd
 
-from pyield import anbima, bday, di
+from pyield import anbima, bday, data_cache, di
 from pyield import date_converter as dc
 from pyield import interpolator as ip
 from pyield.bonds import bond_tools as bt
@@ -22,6 +22,17 @@ COUPON_PMT = 48.80885
 FINAL_PMT = 1048.80885
 
 
+def reference_dates() -> pd.Series:
+    """
+    Fetch the NTN-F bond reference dates available in the Anbima database.
+
+    Returns:
+        pd.Series: A Series of NTN-F bond reference dates.
+    """
+    df = data_cache.get_anbima_dataset().query("BondType == 'NTN-F'")
+    return df["ReferenceDate"].drop_duplicates().sort_values().reset_index(drop=True)
+
+
 def rates(reference_date: DateScalar) -> pd.DataFrame:
     """
     Fetch the bond indicative rates for the given reference date.
@@ -592,14 +603,13 @@ def historical_premium(
     df["BDays"] = bday.count(reference_date, df["PaymentDate"])
     df["BYears"] = df["BDays"] / 252
     df["ReferenceDate"] = reference_date
-    # Instantiate the DI Futures class
-    dif = di.DIFutures()
+
+    dif = di.DIFutures()  # Instantiate the DI Futures class
     df["DIRate"] = dif.interpolate_rates(
         reference_dates=df["ReferenceDate"],
-        maturities=df["PaymentDate"],
-        allow_extrapolation=False,
+        maturity_dates=df["PaymentDate"],
+        extrapolate=False,
     )
-    # df["DIRate"] = df["PaymentDate"].apply(dif.rate)
 
     # Calculate the present value of the cash flows using the DI rate
     bond_price = bt.calculate_present_value(

{pyield-0.24.0 → pyield-0.24.2}/pyield/di.py

@@ -18,14 +18,15 @@ class DIFutures:
 
     Args:
         trade_date (DateScalar): The date to retrieve the contract data.
-        adj_expirations (bool): If True, adjusts the expiration dates to the start
+        month_start (bool): If True, adjusts the expiration dates to the start
             of the month.
-        prefixed_filter (bool): If True, filters the DI contracts to match only
-            expirations with existing LTN and NTN-F bond maturities.
+        prefixed (bool): If True, filters the DI contracts to match only
+            expirations with existing prefixed TN bond maturities (LTN and NTN-F).
+        all_columns (bool): If True, returns all available columns in the DI dataset.
 
     Examples:
         To create a `DIFutures` instance and retrieve data:
-        >>> di = yd.DIFutures(trade_dates="16-10-2024", adj_expirations=True)
+        >>> di = yd.DIFutures(trade_dates="16-10-2024", month_start=True)
         >>> df = di.data  # Retrieve DI contract dataframe for the specified date
         >>> df.iloc[:5, :5]  # Show the first five rows and columns
            TradeDate ExpirationDate TickerSymbol  BDaysToExp  OpenContracts
@@ -43,7 +44,6 @@ class DIFutures:
         2 2024-10-16     2025-01-01         0.11164       0.1154
         3 2024-10-16     2025-02-01         0.11362     0.118314
         4 2024-10-16     2025-03-01          0.1157      0.12343
-
     """
 
     historical_trade_dates = (
@@ -61,16 +61,16 @@ class DIFutures:
     def __init__(
         self,
         trade_dates: DateScalar | DateArray | None = None,
-        adj_expirations: bool = False,
-        prefixed_filter: bool = False,
+        month_start: bool = False,
+        prefixed: bool = False,
         all_columns: bool = True,
     ):
         """
         Initialize the DIFutures instance with a specific trade date.
         """
         self.trade_dates = trade_dates
-        self.adj_expirations = adj_expirations
-        self.prefixed_filter = prefixed_filter
+        self.month_start = month_start
+        self.prefixed = prefixed
         self.all_columns = all_columns
 
     @property
@@ -93,7 +93,7 @@ class DIFutures:
         if "DaysToExpiration" in df.columns:
             df.drop(columns=["DaysToExpiration"], inplace=True)
 
-        if self._prefixed_filter:
+        if self._prefixed:
             df_pre = (
                 get_anbima_dataset()
                 .query("BondType in ['LTN', 'NTN-F']")
@@ -113,7 +113,7 @@ class DIFutures:
 
             df = df.merge(df_pre, how="inner")
 
-        if self._adj_expirations:
+        if self._month_start:
             df["ExpirationDate"] = (
                 df["ExpirationDate"].dt.to_period("M").dt.to_timestamp()
             )
@@ -167,8 +167,8 @@ class DIFutures:
     @staticmethod
     def interpolate_rates(
         reference_dates: DateScalar | DateArray,
-        maturities: DateScalar | DateArray,
-        allow_extrapolation: bool = True,
+        maturity_dates: DateScalar | DateArray,
+        extrapolate: bool = True,
     ) -> pd.Series:
         """
         Interpolates DI rates for specified reference dates and maturities.
@@ -177,11 +177,15 @@ class DIFutures:
         dates and maturities using a flat-forward interpolation method. If no DI
         rates are available for a reference date, the interpolated rate is set to NaN.
 
+        If reference dates is provided as a scalar and maturities as an array, the
+        method assumes the scalar value is the same for all maturities. The same logic
+        applies when the maturities are scalar and the reference dates are an array.
+
         Args:
             reference_dates (DateScalar | DateArray): The reference dates for the rates.
-            maturities (DateScalar | DateArray): The maturity dates corresponding to the
+            maturity_dates (DateScalar | DateArray): The maturities corresponding to the
                 reference dates.
-            allow_extrapolation (bool): Whether to allow extrap. beyond known DI rates.
+            extrapolate (bool): Whether to allow extrapolation beyond known DI rates.
 
         Returns:
             pd.Series: A Series containing the interpolated DI rates.
@@ -190,27 +194,38 @@ class DIFutures:
             ValueError: If `reference_dates` and `maturities` have different lengths.
         """
         # Convert input dates to a consistent format
-        reference_dates = list(dc.convert_input_dates(reference_dates))
-        maturities = list(dc.convert_input_dates(maturities))
+        reference_dates = dc.convert_input_dates(reference_dates)
+        maturity_dates = dc.convert_input_dates(maturity_dates)
 
         # Ensure the lengths of input arrays are consistent
-        if len(reference_dates) != len(maturities):
-            raise ValueError("Dates and maturities must have the same length.")
+        match (reference_dates, maturity_dates):
+            case pd.Timestamp(), pd.Series():
+                dfi = pd.DataFrame({"mat": maturity_dates})
+                dfi["ref"] = reference_dates
+
+            case pd.Series(), pd.Timestamp():
+                dfi = pd.DataFrame({"ref": reference_dates})
+                dfi["mat"] = maturity_dates
+
+            case pd.Series(), pd.Series():
+                if len(reference_dates) != len(maturity_dates):
+                    raise ValueError("Args. should have the same length.")
+                dfi = pd.DataFrame({"ref": reference_dates, "mat": maturity_dates})
 
-        # Create a DataFrame with reference dates and maturities
-        dfi = pd.DataFrame({"reference_date": reference_dates, "maturity": maturities})
+            case pd.Timestamp(), pd.Timestamp():
+                dfi = pd.DataFrame({"ref": [reference_dates], "mat": [maturity_dates]})
 
         # Compute business days between reference dates and maturities
-        dfi["bdays"] = bday.count(dfi["reference_date"], dfi["maturity"])
+        dfi["bdays"] = bday.count(dfi["ref"], dfi["mat"])
 
         # Initialize the interpolated rate column with NaN
-        dfi["interpolated_rate"] = pd.NA
-        dfi["interpolated_rate"] = dfi["interpolated_rate"].astype("Float64")
+        dfi["irate"] = pd.NA
+        dfi["irate"] = dfi["irate"].astype("Float64")
 
         # Load DI rates dataset filtered by the provided reference dates
         dfr = (
             get_di_dataset()
-            .query("TradeDate in @reference_dates")
+            .query("TradeDate in @dfi['ref'].unique()")
             .reset_index(drop=True)
         )
 
@@ -219,7 +234,7 @@ class DIFutures:
             return pd.DataFrame()
 
         # Iterate over each unique reference date
-        for date in set(reference_dates):
+        for date in dfi["ref"].unique():
             # Filter DI rates for the current reference date
             dfr_subset = dfr.query("TradeDate == @date").copy()
 
@@ -232,15 +247,17 @@ class DIFutures:
                 method="flat_forward",
                 known_bdays=dfr_subset["BDaysToExp"],
                 known_rates=dfr_subset["SettlementRate"],
-                extrapolate=allow_extrapolation,
+                extrapolate=extrapolate,
             )
 
             # Apply interpolation to rows matching the current reference date
-            mask = dfi["reference_date"] == date
-            dfi.loc[mask, "interpolated_rate"] = dfi.loc[mask, "bdays"].apply(interp)
+            mask = dfi["ref"] == date
+            dfi.loc[mask, "irate"] = dfi.loc[mask, "bdays"].apply(interp)
 
-        # Return the DataFrame with interpolated rates
-        return dfi["interpolated_rate"]
+        # Return the Series with interpolated rates
+        s_irates = dfi["irate"]
+        s_irates.name = "InterpolatedRates"
+        return s_irates
 
     def rate(
         self,
@@ -251,7 +268,7 @@ class DIFutures:
         """Retrieve the DI rate for a specified expiration date."""
         expiration = dc.convert_input_dates(expiration)
 
-        if self._adj_expirations:
+        if self._month_start:
             # Force the expiration date to be the start of the month
             expiration = expiration.to_period("M").to_timestamp()
         else:
@@ -313,7 +330,7 @@ class DIFutures:
             self._trade_dates = trade_dates.drop_duplicates().sort_values().to_list()
 
     @property
-    def adj_expirations(self) -> bool:
+    def month_start(self) -> bool:
         """
         Adjusts the expiration dates to the start of the month.
 
@@ -324,29 +341,29 @@ class DIFutures:
         Returns:
             bool: Whether expiration dates are adjusted to the start of the month.
         """
-        return self._adj_expirations
+        return self._month_start
 
-    @adj_expirations.setter
-    def adj_expirations(self, value: bool):
-        self._adj_expirations = value
+    @month_start.setter
+    def month_start(self, value: bool):
+        self._month_start = value
 
     @property
-    def prefixed_filter(self) -> bool:
+    def prefixed(self) -> bool:
         """
         Filters DI Futures to match prefixed TN bond maturities.
 
-        This property can be both read and set. When set to `True`, DI Futures will be
-        filtered to match the maturities of LTN and NTN-F bonds from the Anbima dataset.
+        This property can be both read and set. When set to `True`, only contracts that
+        match the maturities of LTN and NTN-F bonds will be shown.
 
         Returns:
-            bool: Whether DI Futures are filtered to match prefixed Anbima bond
-                maturities.
+            bool: Whether the contracts are filtered to match prefixed TN bond
+                maturities from the ANBIMA dataset.
         """
-        return self._prefixed_filter
+        return self._prefixed
 
-    @prefixed_filter.setter
-    def prefixed_filter(self, value: bool):
-        self._prefixed_filter = value
+    @prefixed.setter
+    def prefixed(self, value: bool):
+        self._prefixed = value
 
     @property
     def all_columns(self) -> bool:

{pyield-0.24.0 → pyield-0.24.2}/pyield/interpolator.py

@@ -22,7 +22,9 @@ class Interpolator:
         ValueError: If the interpolation method is not recognized
 
     Note:
-        This class uses a 252 business days per year convention.
+        - This class uses a 252 business days per year convention.
+        - Instances of this class are **immutable**. To modify the interpolation
+          settings, create a new instance.
 
     Examples:
         >>> from pyield import Interpolator
@@ -43,34 +45,21 @@ class Interpolator:
     def __init__(
         self,
         method: Literal["flat_forward", "linear"],
-        known_bdays: pd.Series | list[int],
-        known_rates: pd.Series | list[float],
+        known_bdays: pd.Series | np.ndarray | tuple[int] | list[int],
+        known_rates: pd.Series | np.ndarray | tuple[float] | list[float],
         extrapolate: bool = False,
     ):
-        self.method = method
-        self.known_bdays = known_bdays
-        self.known_rates = known_rates
-        self.extrapolate = extrapolate
-        self._validate_and_process_inputs()
-
-    def _validate_and_process_inputs(self) -> None:
-        """Validate and process the inputs of the Interpolator."""
-        known_bdays = self.known_bdays
-        known_rates = self.known_rates
-        # Series may have different index, so we convert to list
-        if isinstance(known_bdays, pd.Series):
-            known_bdays = known_bdays.to_list()
-        if isinstance(known_rates, pd.Series):
-            known_rates = known_rates.to_list()
-
-        if len(known_bdays) != len(known_rates):
-            raise ValueError("known_bdays and known_rates must have the same length.")
-
-        df = pd.DataFrame({"bday": known_bdays, "rate": known_rates})
-        df = df.dropna().drop_duplicates(subset="bday").sort_values("bday")
-
-        self._known_bdays = df["bday"].to_list()
-        self._known_rates = df["rate"].to_list()
+        df = (
+            pd.DataFrame({"bday": known_bdays, "rate": known_rates})
+            .dropna()
+            .drop_duplicates(subset="bday")
+            .sort_values("bday", ignore_index=True)
+        )
+        self._df = df
+        self._method = method
+        self._known_bdays = tuple(df["bday"])
+        self._known_rates = tuple(df["rate"])
+        self._extrapolate = bool(extrapolate)
 
     def _flat_forward(self, bday: int) -> float:
         """Performs the interest rate interpolation using the flat forward method."""
@@ -90,11 +79,6 @@ class Interpolator:
         c = (bday - prev_bday) / (next_bday - prev_bday)
         return (a * (b / a) ** c) ** (252 / bday) - 1
 
-    def _linear(self, bday: int) -> float:
-        """Performs linear interpolation."""
-        np_float = np.interp(bday, self._known_bdays, self._known_rates)
-        return float(np_float)
-
     def interpolate(self, bday: int) -> float:
         """
         Finds the appropriate interpolation point and returns the interest rate
@@ -114,17 +98,14 @@ class Interpolator:
         elif bday in self._known_bdays:
             return self._known_rates[self._known_bdays.index(bday)]
         elif bday > self._known_bdays[-1]:
-            if self.extrapolate:
-                return self._known_rates[-1]
-            else:
-                return float("NaN")  # Return NaN if extrapolation is not allowed
+            return self._known_rates[-1] if self._extrapolate else float("NaN")
 
-        if self.method == "flat_forward":
+        if self._method == "flat_forward":
             return self._flat_forward(bday)
-        elif self.method == "linear":
-            return self._linear(bday)
+        elif self._method == "linear":
+            return float(np.interp(bday, self._known_bdays, self._known_rates))
         else:
-            raise ValueError(f"Unknown interpolation method: {self.method}.")
+            raise ValueError(f"Unknown interpolation method: {self._method}.")
 
     def __call__(self, bday: int) -> float:
         """
@@ -139,3 +120,10 @@ class Interpolator:
                 number of business days.
         """
         return self.interpolate(bday)
+
+    def __repr__(self) -> str:
+        """
+        Textual representation, used in terminal or scripts.
+        """
+
+        return repr(self._df)

{pyield-0.24.0 → pyield-0.24.2}/pyield/tools.py

@@ -1,8 +1,5 @@
 import pandas as pd
 
-# Expose pre_spreads function from pyield.bonds.bond_tools
-# from pyield.bonds.bond_tools import pre_spreads  # noqa
-
 
 def forward_rates(
     business_days: pd.Series,

pyield-0.24.0/pyield/__about__.py

@@ -1 +0,0 @@
-__version__ = "0.24.0"