PYield 0.9.4__tar.gz → 0.9.6__tar.gz

{pyield-0.9.4 → pyield-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.9.4
+Version: 0.9.6
 Summary: A Python library for analysis of fixed income instruments in Brazil
 Keywords: fixed-income, brazil, finance, analysis, bonds
 Author-Email: Carlos Carvalho <cr.cj@outlook.com>
@@ -85,7 +85,7 @@ Timestamp('2024-01-02 00:00:00')
 >>> yd.bday.offset(dates="30-12-2023", offset=0)
 Timestamp('2024-01-02 00:00:00')
 
-# Since 2023-12-29 is a business day, it returns the same date (offset=0)
+# Since 29-12-2023 is a business day, it returns the same date (offset=0)
 >>> yd.bday.offset(dates="29-12-2023", offset=0)
 Timestamp('2023-12-29 00:00:00')
 
@@ -127,7 +127,7 @@ TradeDate  TickerSymbol ExpirationDate BDaysToExp ... LastRate LastAskRate LastB
 # Fetch a DataFrame with the NTN-B data from ANBIMA
 # Anbima data is available for the last 5 working days
 # Obs: Anbima members have access to the full history
->>> yd.anbima(reference_date='12-04-2024', bond_type='NTN-B')
+>>> yd.anbima(bond_type='NTN-B', reference_date='12-04-2024')
 
 BondType ReferenceDate MaturityDate BidRate AskRate IndicativeRate       Price
    NTN-B    2024-04-12   2024-08-15 0.07540 0.07504        0.07523 4,271.43565
@@ -184,3 +184,22 @@ IndicatorProjection(
 0.0035  # 0.35%
 ```
 
+### Interpolation Tools
+```python
+
+# Interpolate interest rates for specific business days using the Interpolator class.
+
+# Initialize the Interpolator with known business days and interest rates.
+>>> known_bdays = [30, 60, 90]
+>>> known_rates = [0.045, 0.05, 0.055]
+>>> linear_itp = yd.Interpolator("linear", known_bdays, known_rates)
+
+# Interpolate the interest rate for a given number of business days.
+>>> linear_itp.interpolate(45)
+0.0475
+
+# Use the flat forward method for interpolation.
+>>> ff_itp = yd.Interpolator("flat_forward", known_bdays, known_rates)
+>>> ff_itp.interpolate(45)
+0.04833068080970859
+```

{pyield-0.9.4 → pyield-0.9.6}/README.md

@@ -42,7 +42,7 @@ Timestamp('2024-01-02 00:00:00')
 >>> yd.bday.offset(dates="30-12-2023", offset=0)
 Timestamp('2024-01-02 00:00:00')
 
-# Since 2023-12-29 is a business day, it returns the same date (offset=0)
+# Since 29-12-2023 is a business day, it returns the same date (offset=0)
 >>> yd.bday.offset(dates="29-12-2023", offset=0)
 Timestamp('2023-12-29 00:00:00')
 
@@ -84,7 +84,7 @@ TradeDate  TickerSymbol ExpirationDate BDaysToExp ... LastRate LastAskRate LastB
 # Fetch a DataFrame with the NTN-B data from ANBIMA
 # Anbima data is available for the last 5 working days
 # Obs: Anbima members have access to the full history
->>> yd.anbima(reference_date='12-04-2024', bond_type='NTN-B')
+>>> yd.anbima(bond_type='NTN-B', reference_date='12-04-2024')
 
 BondType ReferenceDate MaturityDate BidRate AskRate IndicativeRate       Price
    NTN-B    2024-04-12   2024-08-15 0.07540 0.07504        0.07523 4,271.43565
@@ -141,3 +141,22 @@ IndicatorProjection(
 0.0035  # 0.35%
 ```
 
+### Interpolation Tools
+```python
+
+# Interpolate interest rates for specific business days using the Interpolator class.
+
+# Initialize the Interpolator with known business days and interest rates.
+>>> known_bdays = [30, 60, 90]
+>>> known_rates = [0.045, 0.05, 0.055]
+>>> linear_itp = yd.Interpolator("linear", known_bdays, known_rates)
+
+# Interpolate the interest rate for a given number of business days.
+>>> linear_itp.interpolate(45)
+0.0475
+
+# Use the flat forward method for interpolation.
+>>> ff_itp = yd.Interpolator("flat_forward", known_bdays, known_rates)
+>>> ff_itp.interpolate(45)
+0.04833068080970859
+```

pyield-0.9.6/pyield/__about__.py

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

{pyield-0.9.4 → pyield-0.9.6}/pyield/__init__.py

@@ -1,4 +1,4 @@
-from . import bday, interpolators, ntnb
+from . import bday, interpolator, ntnb
 from .__about__ import __version__
 from .fetchers.anbima import anbima
 from .fetchers.futures import futures
@@ -15,6 +15,6 @@ __all__ = [
     "projection",
     "spread",
     "futures",
-    "interpolators",
+    "interpolator",
     "spread",
 ]

{pyield-0.9.4 → pyield-0.9.6}/pyield/fetchers/anbima.py

@@ -90,8 +90,8 @@ def _process_raw_df(df_raw: pd.DataFrame) -> pd.DataFrame:
 
 
 def anbima(
-    reference_date: str | pd.Timestamp | None = None,
     bond_type: str | list[str] | None = None,
+    reference_date: str | pd.Timestamp | None = None,
 ) -> pd.DataFrame:
     """
     Fetches indicative treasury rates from ANBIMA for a specified reference date.
@@ -100,10 +100,10 @@ def anbima(
     ANBIMA, processing them into a structured pandas DataFrame.
 
     Args:
+        bond_type (str, optional): The type of bond to filter by. Defaults to None.
         reference_date (str | pd.Timestamp | None, optional): The date for which to
             fetch the indicative rates. If a string is provided, it should be in the
             format 'dd-mm-yyyy'. Defaults last business day if None.
-        bond_type (str, optional): The type of bond to filter by. Defaults to None.
 
     Returns:
         pd.DataFrame: A DataFrame containing the processed indicative rates for the
@@ -117,7 +117,7 @@ def anbima(
         # Fetch ANBIMA data for all bonds using the last business day available
         >>> yd.anbima("18-06-2024")
         # Fetch ANBIMA data for NTN-B bonds using a specific reference date
-        >>> yd.anbima("18-06-2024", "NTN-B")
+        >>> yd.anbima("NTN-B", "18-06-2024")
     """
     # Normalize the reference date
     normalized_date = dv.normalize_date(reference_date)

{pyield-0.9.4 → pyield-0.9.6}/pyield/fetchers/futures/intraday.py

@@ -167,8 +167,9 @@ def fetch_intraday_df(future_code: str) -> pd.DataFrame:
         pd.DataFrame: A Pandas pd.DataFrame containing the latest DI futures data.
     """
     raw_df = _fetch_b3_df(future_code)
-    if raw_df.empty:
-        return raw_df
+    if "buyOffer" not in raw_df.columns:
+        # Return an empty DataFrame if the data is not available
+        return pd.DataFrame()
     df = _process_df(raw_df)
     df = _select_and_reorder_columns(df)
     return df

pyield-0.9.6/pyield/interpolator.py

@@ -0,0 +1,138 @@
+import bisect
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+
+class Interpolator:
+    def __init__(
+        self,
+        method: Literal["flat_forward", "linear"],
+        known_bdays: pd.Series | list,
+        known_rates: pd.Series | list,
+    ):
+        """
+        Initialize the Interpolator with given atributes.
+
+        Args:
+            method (Literal["flat_forward", "linear"]): Interpolation method.
+            known_bdays (pd.Series): Series of known business days.
+            known_rates (pd.Series): Series of known interest rates.
+
+        Raises:
+            ValueError: If known_bdays and known_rates do not have the same length.
+            ValueError: If the interpolation method is not recognized
+
+        Returns:
+            Interpolator: An instance of the Interpolator
+
+        Examples:
+            >>> known_bdays = [30, 60, 90]
+            >>> known_rates = [0.045, 0.05, 0.055]
+            >>> interpolator = Interpolator("linear", known_bdays, known_rates)
+        """
+        self.known_bdays, self.known_rates = self._process_known_data(
+            known_bdays, known_rates
+        )
+        self.method = self._validate_method(method)
+
+    @staticmethod
+    def _validate_method(method: str) -> str:
+        """
+        Validate the interpolation method.
+
+        Args:
+            method (str): Interpolation method to validate.
+
+        Returns:
+            str: Validated interpolation method.
+        """
+        valid_methods = ["flat_forward", "linear"]
+        if method not in valid_methods:
+            raise ValueError(f"Unknown interpolation method: {method}.")
+        return method
+
+    @staticmethod
+    def _process_known_data(
+        known_bdays: pd.Series | list, known_rates: pd.Series | list
+    ) -> tuple[list, list]:
+        """
+        Process and validate known business days and interest rates.
+
+        Args:
+            known_bdays (pd.Series): Series of known business days.
+            known_rates (pd.Series): Series of known interest rates.
+
+        Returns:
+            tuple: Processed lists of business days and interest rates.
+        """
+        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")
+
+        return df["bday"].to_list(), df["rate"].to_list()
+
+    def _flat_forward(self, bday: int) -> float:
+        """Performs the interest rate interpolation using the flat forward method."""
+
+        # Find i such that known_bdays[i-1] < bday < known_bdays[i]
+        i = bisect.bisect_left(self.known_bdays, bday)
+
+        # Get previous and next known rates and business days
+        prev_rate = self.known_rates[i - 1]
+        prev_bday = self.known_bdays[i - 1]
+        next_rate = self.known_rates[i]
+        next_bday = self.known_bdays[i]
+
+        # Perform flat forward interpolation
+        a = (1 + prev_rate) ** (prev_bday / 252)
+        b = (1 + next_rate) ** (next_bday / 252)
+        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
+        interpolated by the specified method from that point.
+
+        Args:
+            bday (int): Number of business days for which the interest rate is to be
+                calculated.
+
+        Returns:
+            float: The interest rate interpolated by the specified method for the given
+                number of business days.
+
+        Examples:
+                >>> known_bdays = [30, 60, 90]
+                >>> known_rates = [0.045, 0.05, 0.055]
+                >>> linear = Interpolator("linear", known_bdays, known_rates)
+                >>> linear.interpolate(45)
+                0.0475
+                >>> ffwd = Interpolator("flat_forward", known_bdays, known_rates)
+                >>> ffwd.interpolate(45)
+                0.04833068080970859
+        """
+        known_bdays = self.known_bdays
+        known_rates = self.known_rates
+
+        # Special cases
+        if bday < known_bdays[0]:
+            return known_rates[0]
+        elif bday > known_bdays[-1]:
+            return known_rates[-1]
+        elif bday in known_bdays:
+            return known_rates[known_bdays.index(bday)]
+
+        if self.method == "flat_forward":
+            return self._flat_forward(bday)
+        elif self.method == "linear":
+            return self._linear(bday)

{pyield-0.9.4 → pyield-0.9.6}/pyield/ntnb.py

@@ -3,9 +3,9 @@ import pandas as pd
 
 from . import bday
 from . import date_validator as dv
-from . import interpolators as ip
 from .fetchers.anbima import anbima
 from .fetchers.futures import futures
+from .interpolator import Interpolator
 from .spreads import spread
 
 # 6% per year compounded semi-annually and rounded to 8 decimal places
@@ -35,7 +35,7 @@ def ytm_rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
     Returns:
         pd.DataFrame: A DataFrame containing the maturity dates and corresponding rates.
     """
-    df = anbima(reference_date, bond_type="NTN-B")
+    df = anbima("NTN-B", reference_date)
 
     # Keep only the relevant columns for the output
     keep_columns = ["ReferenceDate", "BondType", "MaturityDate", "IndicativeRate"]
@@ -188,30 +188,6 @@ def quotation(
     return _truncate(dcf.sum(), 4)
 
 
-def _prepare_interpolation_data(
-    reference_date: pd.Timestamp, maturity_dates: pd.Series, rates: pd.Series
-) -> tuple:
-    """
-    Prepare the data needed for interpolation by sorting the YTM rates by the number of
-    business days.
-
-    Args:
-        reference_date (str | pd.Timestamp): The reference date for calculating the
-            number of business days.
-        maturity_dates (pd.Series): Series of maturity dates for the bonds.
-        rates (pd.Series): Series of rates corresponding to the maturity dates.
-
-    Returns:
-        tuple: Two lists containing the ordered business days and YTM rates.
-    """
-    bdays = bday.count(reference_date, maturity_dates)
-    df = pd.DataFrame({"BDays": bdays, "Rates": rates})
-    df.sort_values(by="BDays", ignore_index=True, inplace=True)
-    ordered_bdays = df["BDays"].to_list()
-    ordered_rates = df["Rates"].to_list()
-    return ordered_bdays, ordered_rates
-
-
 def spot_rates(
     settlement_date: str | pd.Timestamp,
     maturity_dates: pd.Series,
@@ -223,37 +199,44 @@ def spot_rates(
 
     Args:
         settlement_date (str | pd.Timestamp): The reference date for settlement.
-        maturity_dates (pd.Series): Series of maturity dates for the bonds.
-        ytm_rates (pd.Series): Series of Yield to Maturity rates corresponding to the
+        maturity_dates (pd.Series): Series of maturity dates for the bonds. ytm_rates
+        (pd.Series): Series of Yield to Maturity rates corresponding to the
             maturity dates.
 
     Returns:
-        pd.DataFrame: DataFrame containing the maturity dates and corresponding spot
-            rates.
+        pd.DataFrame: DataFrame containing the maturity dates and corresponding real
+            spot rates (RSR).
 
     Notes:
         The calculation of the spot rates for NTN-B bonds considers the following steps:
             - Map all all possible payment dates up to the longest maturity date.
             - Interpolate the YTM rates in the intermediate payment dates.
             - Calculate the NTN-B quotation for each maturity date.
-            - Calculate the spot rates for each maturity date.
+            - Calculate the real spot rates (RSR) for each maturity date.
     """
     # COUPON = (1.06) ** 0.5 - 1  # Coupon without rounding
     # Validate and normalize the settlement date
     settlement_date = dv.normalize_date(settlement_date)
 
-    # Prepare the data for interpolation
-    ordered_bdays, ordered_ytms = _prepare_interpolation_data(
-        settlement_date, maturity_dates, ytm_rates
+    # Create the interpolator object
+    flat_fwd = Interpolator(
+        method="flat_forward",
+        known_bdays=bday.count(settlement_date, maturity_dates),
+        known_rates=ytm_rates,
+    )
+
+    # Generate coupon dates up to the longest maturity date
+    all_coupon_dates = coupon_dates_map(
+        start=settlement_date,
+        end=maturity_dates.max(),
     )
-    # Generate coupon dates and initialize the main DataFrame
-    longest_ntnb = maturity_dates.max()
-    coupon_dates_all = coupon_dates_map(settlement_date, longest_ntnb)
-    df = pd.DataFrame(coupon_dates_all, columns=["MaturityDate"])
+
+    # Create a DataFrame with all coupon dates
+    df = pd.DataFrame(all_coupon_dates, columns=["MaturityDate"])
 
     # Add auxiliary columns for calculations
     df["BDays"] = bday.count(settlement_date, df["MaturityDate"])
-    df["YTM"] = 0.0
+    df["YTM"] = df["BDays"].apply(flat_fwd.interpolate)
     df["RSR"] = 0.0
 
     # Main loop to calculate spot rates
@@ -273,15 +256,12 @@ def spot_rates(
         # Calculate the present value of the cash flows (discounted cash flows)
         dcfs = cfs / (1 + spot_rates) ** periods
 
-        # Interpolate YTM and calculate spot rate
+        # Calculate the real spot rate (RSR) for the bond
         bd = df.at[index, "BDays"]
-        ytm = ip.find_and_interpolate_flat_forward(bd, ordered_bdays, ordered_ytms)
+        ytm = df.at[index, "YTM"]
         ntnb_quotation = quotation(settlement_date, maturity_date, ytm) / 100
-        spot_rate = ((COUPON + 1) / (ntnb_quotation - dcfs.sum())) ** (252 / bd) - 1
-
-        # Update DataFrame with calculated values
-        df.at[index, "RSR"] = spot_rate
-        df.at[index, "YTM"] = ytm
+        rsr = ((COUPON + 1) / (ntnb_quotation - dcfs.sum())) ** (252 / bd) - 1
+        df.at[index, "RSR"] = rsr
 
     # Drop the BDays column, remove intermediate cupon dates and reset the index.
     return (
@@ -383,25 +363,28 @@ def bei_rates(
 
     # Fetch Nominal Spot Rate (NSR) data
     df_nsr = _get_nsr_df(reference_date)
-    known_bdays = df_nsr["BDaysToExp"].to_list()
-    known_rates = df_nsr["NSR_DI"].to_list()
 
+    ffwd = Interpolator(
+        method="flat_forward",
+        known_bdays=df_nsr["BDaysToExp"],
+        known_rates=df_nsr["NSR_DI"],
+    )
     # Calculate Real Spot Rate (RSR)
     df = spot_rates(settlement_date, maturity_dates, ytm_rates)
     df = df.rename(columns={"RSR": "RSR"})
     df["BDays"] = bday.count(reference_date, df["MaturityDate"])
-    df["NSR_DI"] = df["BDays"].apply(
-        lambda x: ip.find_and_interpolate_flat_forward(x, known_bdays, known_rates)
-    )
+    df["NSR_DI"] = df["BDays"].apply(ffwd.interpolate)
 
     # Calculate Breakeven Inflation Rate (BIR)
     df["BIR_DI"] = ((df["NSR_DI"] + 1) / (df["RSR"] + 1)) - 1
 
     # Adjust BEI for DI spread in prefixed bonds
-    known_rates = df_nsr["NSR_PRE"].to_list()
-    df["NSR_PRE"] = df["BDays"].apply(
-        lambda x: ip.find_and_interpolate_flat_forward(x, known_bdays, known_rates)
+    ffwd = Interpolator(
+        method="flat_forward",
+        known_bdays=df_nsr["BDaysToExp"],
+        known_rates=df_nsr["NSR_PRE"],
     )
+    df["NSR_PRE"] = df["BDays"].apply(ffwd.interpolate)
     df["BIR_PRE"] = ((df["NSR_PRE"] + 1) / (df["RSR"] + 1)) - 1
 
     cols_reordered = [

{pyield-0.9.4 → pyield-0.9.6}/pyield/spreads.py

@@ -76,7 +76,7 @@ def di_pre(reference_date: pd.Timestamp) -> pd.DataFrame:
     df_di["MaturityDate"] = df_di["MaturityDate"].dt.to_period("M").dt.to_timestamp()
 
     # Fetch bond rates, filtering for LTN and NTN-F types
-    df_anbima = anbima(reference_date, ["LTN", "NTN-F"])
+    df_anbima = anbima(["LTN", "NTN-F"], reference_date)
     # Keep only the relevant columns for the output
     keep_columns = ["ReferenceDate", "BondType", "MaturityDate", "IndicativeRate"]
     df_anbima = df_anbima[keep_columns].copy()

{pyield-0.9.4 → pyield-0.9.6}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "requests>=2.31.0",
 ]
 dynamic = []
-version = "0.9.4"
+version = "0.9.6"
 
 [project.license]
 file = "LICENSE"

pyield-0.9.4/pyield/__about__.py

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

pyield-0.9.4/pyield/interpolators.py

@@ -1,91 +0,0 @@
-import bisect
-
-
-def interpolate_flat_forward(
-    prev_rate: float, prev_bdays: int, next_rate: float, next_bdays: int, bdays: int
-) -> float:
-    """Performs interest rate interpolation using the flat forward interpolation method
-    considering a base of 252 business days.
-
-    The interpolation is done between two known pairs of vertices (prev_rate,
-    prev_business_days) and (next_rate, next_business_days), for a third vertex defined
-    by the number of business days 'business_days' where 'prev_business_days <
-    business_days < next_business_days'. This third vertex is the point in time for
-    which the interest rate is being calculated.
-
-    Args:
-    - prev_rate (float): Interest rate of the previous vertex.
-    - prev_bdays (int): Number of business days of the previous vertex.
-    - next_rate (float): Interest rate of the next vertex.
-    - next_bdays (int): Number of business days of the next vertex.
-    - bdays (int): Number of business days for which the interest rate is to be
-      interpolated.
-
-    Example:
-    interpolated_rate = interpolate_flat_forward(0.045, 30, 0.05, 60, 45)
-
-    Returns:
-        float: The interpolated interest rate at the given `business_days`.
-    """
-    a = (1 + prev_rate) ** (prev_bdays / 252)
-    b = (1 + next_rate) ** (next_bdays / 252)
-    c = (bdays - prev_bdays) / (next_bdays - prev_bdays)
-
-    return (a * (b / a) ** c) ** (252 / bdays) - 1
-
-
-def find_and_interpolate_flat_forward(
-    bdays: int,
-    known_bdays: list[int],
-    known_rates: list[float],
-) -> float:
-    """
-    Finds the appropriate interpolation point and returns the interest rate
-    interpolated by the flat forward method from that point. Uses the `bisect` module
-    for binary search in ordered lists.
-
-
-    Args:
-        business_days (int): Number of business days for which the flat forward interest
-            rate is to be calculated.
-        known_business_days (List[int]): List of business days where interest rates are
-            known.
-        known_rates (List[float]): List of known interest rates.
-
-    Notes:
-        - It is assumed that `known_business_days` and `known_rates` are sorted and have
-          the same size.
-        - The method uses 252 business days per year in the interpolation, which is the
-          standard in the Brazilian market.
-        - Special cases are handled for situations where `business_days` is less than
-          the first known business day, greater than the last known business day, or
-          exactly equal to a known business day, avoiding the need for interpolation.
-
-    Example:
-    known_bdays = [30, 60, 90]
-    known_rates = [0.045, 0.05, 0.055]
-    interpolated_rate = find_and_interpolate_flat_forward(45, known_bdays, known_rates)
-
-    Returns:
-        float: The interest rate interpolated by the flat forward method for the given
-            number of business days.
-    """
-    # Special cases
-    if bdays <= known_bdays[0]:
-        return known_rates[0]
-    elif bdays >= known_bdays[-1]:
-        return known_rates[-1]
-    # Do not interpolate vertex whose rate is known
-    elif bdays in known_bdays:
-        return known_rates[known_bdays.index(bdays)]
-
-    # Find i such that known_business_days[i-1] < business_days < known_business_days[i]
-    i = bisect.bisect_left(known_bdays, bdays)
-
-    return interpolate_flat_forward(
-        known_rates[i - 1],
-        known_bdays[i - 1],
-        known_rates[i],
-        known_bdays[i],
-        bdays,
-    )