PYield 0.22.0__tar.gz → 0.22.2__tar.gz

{pyield-0.22.0 → pyield-0.22.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.22.0
+Version: 0.22.2
 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>

pyield-0.22.2/pyield/__about__.py

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

{pyield-0.22.0 → pyield-0.22.2}/pyield/bonds/bond_tools.py

@@ -3,8 +3,9 @@ from typing import overload
 import numpy as np
 import pandas as pd
 
-from pyield import anbima, di
+from pyield import anbima
 from pyield import date_converter as dc
+from pyield.di import DIFutures
 
 
 @overload
@@ -72,13 +73,13 @@ def di_spreads(reference_date: str | pd.Timestamp) -> pd.DataFrame:
             business day according to the Brazilian calendar.
 
     Returns:
-        pd.DataFrame: DataFrame containing the bond type, reference date, maturity
-            date, and the calculated spread in basis points. The data is sorted by
-            bond type and maturity date.
+        pd.DataFrame: DataFrame containing the bond type, maturity date and the
+            calculated spread in basis points.
     """
     # Fetch DI rates for the reference date
     reference_date = dc.convert_input_dates(reference_date)
-    df_di = di.data(reference_date, adj_expirations=True)
+    di = DIFutures(reference_date, adj_expirations=True)
+    df_di = di.data()
     if "SettlementRate" not in df_di.columns:
         raise ValueError("DI rates data is missing the 'SettlementRate' column.")
 
@@ -103,5 +104,5 @@ def di_spreads(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
     # Prepare and return the final sorted DataFrame
     df_spreads = df_spreads.sort_values(["BondType", "MaturityDate"], ignore_index=True)
-    select_columns = ["BondType", "ReferenceDate", "MaturityDate", "DISpread"]
+    select_columns = ["BondType", "MaturityDate", "DISpread"]
     return df_spreads[select_columns].copy()

{pyield-0.22.0 → pyield-0.22.2}/pyield/bonds/ltn.py

@@ -1,8 +1,9 @@
 import pandas as pd
 
-from pyield import anbima, bday, di
+from pyield import anbima, bday
 from pyield import date_converter as dc
 from pyield.bonds import bond_tools as bt
+from pyield.di import DIFutures
 
 FACE_VALUE = 1000
 
@@ -16,6 +17,24 @@ def rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
     Returns:
         pd.DataFrame: DataFrame with columns "MaturityDate" and "IndicativeRate".
+
+    Examples:
+        >>> yd.ltn.rates("22-08-2024")
+           MaturityDate  IndicativeRate
+        0    2024-10-01        0.104444
+        1    2025-01-01        0.107555
+        2    2025-04-01        0.111592
+        3    2025-07-01         0.11387
+        4    2025-10-01        0.115483
+        5    2026-01-01        0.116013
+        6    2026-04-01        0.116294
+        7    2026-07-01        0.116743
+        8    2026-10-01        0.116767
+        9    2027-07-01        0.116982
+        10   2028-01-01        0.117289
+        11   2028-07-01        0.117948
+        12   2030-01-01        0.118746
+
     """
     ltn_rates = anbima.rates(reference_date, "LTN")
     if ltn_rates.empty:
@@ -32,9 +51,29 @@ def maturities(reference_date: str | pd.Timestamp) -> pd.Series:
 
     Returns:
         pd.Series: A Series of bond maturities available for the reference date.
+
+    Examples:
+        >>> yd.ltn.maturities("22-08-2024")
+        0    2024-10-01
+        1    2025-01-01
+        2    2025-04-01
+        3    2025-07-01
+        4    2025-10-01
+        5    2026-01-01
+        6    2026-04-01
+        7    2026-07-01
+        8    2026-10-01
+        9    2027-07-01
+        10   2028-01-01
+        11   2028-07-01
+        12   2030-01-01
+        dtype: datetime64[ns]
+
     """
     df_rates = rates(reference_date)
-    return df_rates["MaturityDate"]
+    s_maturities = df_rates["MaturityDate"]
+    s_maturities.name = None
+    return s_maturities
 
 
 def price(
@@ -93,6 +132,23 @@ def di_spreads(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
     Returns:
         pd.DataFrame: DataFrame with the columns "MaturityDate" and "DISpread" (in bps).
+
+    Examples:
+        >>> yd.ltn.di_spreads("22-08-2024")
+           MaturityDate  DISpread
+        0    2024-10-01     -3.06
+        1    2025-01-01     -9.95
+        2    2025-04-01     -8.28
+        3    2025-07-01      -6.1
+        4    2025-10-01     -2.57
+        5    2026-01-01     -1.57
+        6    2026-04-01     -0.86
+        7    2026-07-01      2.83
+        8    2026-10-01      4.17
+        9    2027-07-01      3.72
+        10   2028-01-01      6.19
+        11   2028-07-01      8.68
+        12   2030-01-01     14.96
     """
     # Fetch DI Spreads for the reference date
     df = bt.di_spreads(reference_date)
@@ -141,6 +197,11 @@ def historical_premium(
     Returns:
         float: The premium of the LTN bond over the DI Future rate for the given date.
                If the data is not available, returns NaN.
+
+    Example:
+        >>> yd.ltn.historical_premium("22-08-2024", "01-01-2030")
+        1.012072
+
     """
     # Convert input dates to a consistent format
     reference_date = dc.convert_input_dates(reference_date)
@@ -158,7 +219,8 @@ def historical_premium(
     ltn_rate = float(ltn_rates.iloc[0])
 
     # Retrieve DI rate for the reference date and maturity
-    di_rate = di.rate(trade_date=reference_date, expiration=maturity)
+    di = DIFutures(trade_date=reference_date)
+    di_rate = di.rate(expiration=maturity)
     if pd.isnull(di_rate):  # Check if the DI rate is NaN
         return float("NaN")
 

{pyield-0.22.0 → pyield-0.22.2}/pyield/bonds/ntnf.py

@@ -3,9 +3,10 @@ from collections.abc import Callable
 import numpy as np
 import pandas as pd
 
-from pyield import anbima, bday, di
+from pyield import anbima, bday
 from pyield import date_converter as dc
 from pyield.bonds import bond_tools as bt
+from pyield.di import DIFutures
 from pyield.interpolator import Interpolator
 
 """
@@ -30,6 +31,16 @@ def rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
     Returns:
         pd.DataFrame: DataFrame with columns "MaturityDate" and "IndicativeRate".
+
+    Examples:
+        >>> yd.ntnf.rates("23-08-2024")
+          MaturityDate  IndicativeRate
+        0   2025-01-01        0.107692
+        1   2027-01-01        0.115109
+        2   2029-01-01        0.116337
+        3   2031-01-01        0.117008
+        4   2033-01-01        0.116307
+        5   2035-01-01        0.116586
     """
     ntnf_rates = anbima.rates(reference_date, "NTN-F")
     if ntnf_rates.empty:
@@ -46,9 +57,22 @@ def maturities(reference_date: str | pd.Timestamp) -> pd.Series:
 
     Returns:
         pd.Series: A Series of NTN-F bond maturities available for the reference date.
+
+    Examples:
+        >>> yd.ntnf.maturities("23-08-2024")
+        0   2025-01-01
+        1   2027-01-01
+        2   2029-01-01
+        3   2031-01-01
+        4   2033-01-01
+        5   2035-01-01
+        dtype: datetime64[ns]
+
     """
     df_rates = rates(reference_date)
-    return df_rates["MaturityDate"]
+    s_maturities = df_rates["MaturityDate"]
+    s_maturities.name = None
+    return s_maturities
 
 
 def _check_maturity_date(maturity: pd.Timestamp) -> None:
@@ -298,11 +322,25 @@ def di_spreads(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
     Returns:
         pd.DataFrame: DataFrame with columns "MaturityDate", "DISpread".
+
+    Examples:
+        >>> yd.ntnf.di_spreads("23-08-2024")
+          MaturityDate  DISpread
+        0   2025-01-01     -5.38
+        1   2027-01-01      4.39
+        2   2029-01-01      7.37
+        3   2031-01-01     12.58
+        4   2033-01-01      7.67
+        5   2035-01-01     12.76
+
     """
     # Fetch DI Spreads for the reference date
     df = bt.di_spreads(reference_date)
-    df.query("BondType == 'NTN-F'", inplace=True)
-    df.sort_values(["MaturityDate"], ignore_index=True, inplace=True)
+    df = (
+        df.query("BondType == 'NTN-F'")
+        .sort_values(["MaturityDate"])
+        .reset_index(drop=True)
+    )
     return df[["MaturityDate", "DISpread"]]
 
 
@@ -389,6 +427,19 @@ def di_net_spread(  # noqa
 
     Returns:
         float: The net DI spread in basis points.
+
+    Example:
+        # Obs: only some of the DI rates will be used in the example.
+        >>> exp_dates = pd.to_datetime(["2025-01-01", "2030-01-01", "2035-01-01"])
+        >>> di_rates = pd.Series([0.10823, 0.11594, 0.11531])
+        >>> di_net_spread(
+        ...     settlement="23-08-2024",
+        ...     ntnf_maturity="01-01-2035",
+        ...     ntnf_rate=0.116586,
+        ...     di_expirations=exp_dates,
+        ...     di_rates=di_rates,
+        ... )
+        12.13
     """
     # Create an interpolator for the DI rates using the flat-forward method
     settlement = dc.convert_input_dates(settlement)
@@ -432,6 +483,47 @@ def premium(
     di_expirations: pd.Series,
     di_rates: pd.Series,
 ) -> float:
+    """
+    Calculate the premium of an NTN-F bond over DI rates.
+
+    This function computes the premium of an NTN-F bond by comparing its implied
+    discount factor with that of the DI curve. It determines the net premium based
+    on the difference between the discount factors of the bond's yield-to-maturity
+    (YTM) and the interpolated DI rates.
+
+    Args:
+        settlement (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
+            or a pandas Timestamp.
+        ntnf_maturity (str | pd.Timestamp): The maturity date of the NTN-F bond in
+            'DD-MM-YYYY' format or a pandas Timestamp.
+        ntnf_rate (float): The yield to maturity (YTM) of the NTN-F bond.
+        di_expirations (pd.Series): Series containing the expiration dates for DI
+        rates. di_rates (pd.Series): Series containing the DI rates corresponding to
+        the
+            expiration dates.
+
+    Returns:
+        float: The premium of the NTN-F bond over the DI curve, expressed as a
+        factor.
+
+    Example:
+        # Obs: only some of the DI rates will be used in the example.
+        >>> exp_dates = pd.to_datetime(["2025-01-01", "2030-01-01", "2035-01-01"])
+        >>> di_rates = pd.Series([0.10823, 0.11594, 0.11531])
+        >>> premium(
+        ...     settlement="23-08-2024",
+        ...     ntnf_maturity="01-01-2035",
+        ...     ntnf_rate=0.116586,
+        ...     di_expirations=exp_dates,
+        ...     di_rates=di_rates,
+        ... )
+        1.00996
+
+    Notes:
+        - The function adjusts coupon payment dates to business days and calculates
+          the present value of cash flows for the NTN-F bond using DI rates.
+
+    """
     ntnf_maturity = dc.convert_input_dates(ntnf_maturity)
     settlement = dc.convert_input_dates(settlement)
 
@@ -487,7 +579,8 @@ def historical_premium(
     df = cash_flows(reference_date, maturity, adj_payment_dates=True)
     df["BDays"] = bday.count(reference_date, df["PaymentDate"])
     df["BYears"] = df["BDays"] / 252
-    df["DIRate"] = df["PaymentDate"].apply(lambda x: di.rate(reference_date, x))
+    di = DIFutures(reference_date)
+    df["DIRate"] = df["PaymentDate"].apply(di.rate)
 
     # Calculate the present value of the cash flows using the DI rate
     bond_price = bt.calculate_present_value(

{pyield-0.22.0 → pyield-0.22.2}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "types-requests",
 ]
 dynamic = []
-version = "0.22.0"
+version = "0.22.2"
 
 [project.license]
 file = "LICENSE"

pyield-0.22.0/pyield/__about__.py

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