PYield 0.25.2__tar.gz → 0.25.4__tar.gz

{pyield-0.25.2 → pyield-0.25.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: PYield
-Version: 0.25.2
+Version: 0.25.4
 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.25.4/pyield/__about__.py

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

{pyield-0.25.2 → pyield-0.25.4}/pyield/bonds/ntnb.py

@@ -127,7 +127,7 @@ def maturities(reference_date: DateScalar) -> pd.Series:
     return s_maturities
 
 
-def _generate_coupon_dates_map(
+def _generate_all_coupon_dates(
     start: DateScalar,
     end: DateScalar,
 ) -> pd.Series:
@@ -336,6 +336,7 @@ def spot_rates(
     settlement: DateScalar,
     maturities: pd.Series,
     rates: pd.Series,
+    show_coupons: bool = False,
 ) -> pd.DataFrame:
     """
     Calculate the spot rates for NTN-B bonds using the bootstrap method.
@@ -349,6 +350,8 @@ def spot_rates(
         settlement (DateScalar): The reference date for settlement.
         maturities (pd.Series): Series of maturity dates for the bonds.
         rates (pd.Series): Series of yield to maturity rates.
+        show_coupons (bool, optional): If True, the result will include the
+            intermediate coupon dates. Defaults to False.
 
     Returns:
         pd.DataFrame: DataFrame with columns "MaturityDate", "SpotRate".
@@ -363,21 +366,21 @@ def spot_rates(
         ...     maturities=df_rates["MaturityDate"],
         ...     rates=df_rates["IndicativeRate"],
         ... )
-           MaturityDate  SpotRate
-        0    2025-05-15  0.063894
-        1    2026-08-15  0.066141
-        2    2027-05-15  0.064087
-        3    2028-08-15  0.063057
-        4    2029-05-15  0.061458
-        5    2030-08-15  0.059491
-        6    2032-08-15  0.059652
-        7    2033-05-15  0.059497
-        8    2035-05-15  0.059151
-        9    2040-08-15  0.058326
-        10   2045-05-15  0.060371
-        11   2050-08-15  0.060772
-        12   2055-05-15  0.059909
-        13   2060-08-15  0.060652
+           MaturityDate  BDToMat  SpotRate
+        0    2025-05-15      185  0.063894
+        1    2026-08-15      502  0.066141
+        2    2027-05-15      687  0.064087
+        3    2028-08-15     1002  0.063057
+        4    2029-05-15     1186  0.061458
+        5    2030-08-15     1500  0.059491
+        6    2032-08-15     2004  0.059652
+        7    2033-05-15     2191  0.059497
+        8    2035-05-15     2690  0.059151
+        9    2040-08-15     4009  0.058326
+        10   2045-05-15     5196  0.060371
+        11   2050-08-15     6511  0.060772
+        12   2055-05-15     7700  0.059909
+        13   2060-08-15     9017  0.060652
 
     Notes:
         The calculation of the spot rates for NTN-B bonds considers the following steps:
@@ -387,6 +390,7 @@ def spot_rates(
             - Calculate the real spot rates for each maturity date.
             - Columns in the returned DataFrame:
                 - MaturityDate: The maturity date of the bond.
+                - BDToMat: The number of business days from settlement to maturities.
                 - SpotRate: The real spot rate for the bond.
     """
     # Process and validate the input data
@@ -394,7 +398,7 @@ def spot_rates(
     maturities = pd.to_datetime(maturities, errors="raise", dayfirst=True)
     _check_maturities(maturities)
 
-    # Create the interpolator object
+    # Create the interpolator to calculate the YTM rates for intermediate dates
     ff_interpolator = ip.Interpolator(
         method="flat_forward",
         known_bdays=bday.count(settlement, maturities),
@@ -402,15 +406,15 @@ def spot_rates(
     )
 
     # Generate coupon dates up to the longest maturity date
-    all_coupon_dates = _generate_coupon_dates_map(
+    all_coupon_dates = _generate_all_coupon_dates(
         start=settlement, end=maturities.max()
     )
 
     # Create a DataFrame with all coupon dates and the corresponding YTM
     df = pd.DataFrame(data=all_coupon_dates, columns=["MaturityDate"])
-    df["BDays"] = bday.count(settlement, df["MaturityDate"])
-    df["BYears"] = df["BDays"] / 252
-    df["YTM"] = df["BDays"].apply(ff_interpolator)
+    df["BDToMat"] = bday.count(settlement, df["MaturityDate"])
+    df["BYears"] = df["BDToMat"] / 252
+    df["YTM"] = df["BDToMat"].apply(ff_interpolator)
     df["Coupon"] = COUPON_PMT
     df["SpotRate"] = np.nan
 
@@ -419,9 +423,9 @@ def spot_rates(
         # Get the cash flow dates for the bond
         cf_dates = payment_dates(settlement, row["MaturityDate"])
 
-        # If there is only one coupon date and this date is the first maturity date
-        # of an existing bond, the ytm rate is also a spot rate.
-        if len(cf_dates) == 1 and cf_dates[0] == maturities[0]:
+        # If there is only one cash flow date, it means the bond is a single payment
+        # bond, so the spot rate is equal to the YTM rate
+        if len(cf_dates) == 1:
             df.at[index, "SpotRate"] = row["YTM"]
             continue
 
@@ -439,11 +443,14 @@ def spot_rates(
         price_factor = FINAL_PMT / (bond_price - cf_present_value)
         df.at[index, "SpotRate"] = price_factor ** (1 / row["BYears"]) - 1
 
-    df = df[["MaturityDate", "SpotRate"]].copy()
+    df = df[["MaturityDate", "BDToMat", "SpotRate"]].copy()
     # Force Float64 type in float columns to standardize the output
     df["SpotRate"] = df["SpotRate"].astype("Float64")
-    # Return the result without the intermediate coupon dates (virtual bonds)
-    return df.query("MaturityDate in @maturities").reset_index(drop=True)
+
+    # Filter the result without the intermediate coupon dates (virtual bonds)
+    if not show_coupons:
+        df = df.query("MaturityDate in @maturities").reset_index(drop=True)
+    return df
 
 
 def bei_rates(
@@ -473,6 +480,7 @@ def bei_rates(
 
     Returned columns:
         - MaturityDate: The maturity date of the bonds.
+        - BDToMat: The number of business days from the settlement to the maturity.
         - RIR: The calculated Real Interest Rates based on the spot rates.
         - NIR: The Nominal Interest Rates interpolated for the maturity date.
         - BEI: The calculated Breakeven Inflation Rates.
@@ -500,21 +508,21 @@ def bei_rates(
         ...     nominal_maturities=df_di["ExpirationDate"],
         ...     nominal_rates=df_di["SettlementRate"],
         ... )
-           MaturityDate       RIR       NIR       BEI
-        0    2025-05-15  0.061749  0.113836  0.049058
-        1    2026-08-15  0.066133  0.117126   0.04783
-        2    2027-05-15  0.063816  0.117169  0.050152
-        3    2028-08-15  0.063635   0.11828  0.051376
-        4    2029-05-15  0.062532   0.11838  0.052561
-        5    2030-08-15  0.061809  0.118499   0.05339
-        6    2032-08-15  0.062135  0.118084  0.052676
-        7    2033-05-15  0.061897   0.11787   0.05271
-        8    2035-05-15  0.061711  0.117713  0.052747
-        9    2040-08-15  0.060468   0.11759  0.053865
-        10   2045-05-15    0.0625   0.11759   0.05185
-        11   2050-08-15  0.063016   0.11759  0.051339
-        12   2055-05-15  0.062252   0.11759  0.052095
-        13   2060-08-15  0.063001   0.11759  0.051354
+           MaturityDate  BDToMat       RIR       NIR       BEI
+        0    2025-05-15      171  0.061749  0.113836  0.049058
+        1    2026-08-15      488  0.066133  0.117126   0.04783
+        2    2027-05-15      673  0.063816  0.117169  0.050152
+        3    2028-08-15      988  0.063635   0.11828  0.051376
+        4    2029-05-15     1172  0.062532   0.11838  0.052561
+        5    2030-08-15     1486  0.061809  0.118499   0.05339
+        6    2032-08-15     1990  0.062135  0.118084  0.052676
+        7    2033-05-15     2177  0.061897   0.11787   0.05271
+        8    2035-05-15     2676  0.061711  0.117713  0.052747
+        9    2040-08-15     3995  0.060468   0.11759  0.053865
+        10   2045-05-15     5182    0.0625   0.11759   0.05185
+        11   2050-08-15     6497  0.063016   0.11759  0.051339
+        12   2055-05-15     7686  0.062252   0.11759  0.052095
+        13   2060-08-15     9003  0.063001   0.11759  0.051354
 
     """
     # Normalize input dates
@@ -523,7 +531,7 @@ def bei_rates(
 
     # Calculate Real Interest Rate (RIR)
     df = spot_rates(settlement, ntnb_maturities, ntnb_rates)
-    df["BDays"] = bday.count(settlement, df["MaturityDate"])
+    df["BDToMat"] = bday.count(settlement, df["MaturityDate"])
     df = df.rename(columns={"SpotRate": "RIR"})
 
     nir_interplator = ip.Interpolator(
@@ -533,12 +541,13 @@ def bei_rates(
         extrapolate=True,
     )
 
-    df["NIR"] = df["BDays"].apply(nir_interplator).astype("Float64")
+    df["NIR"] = df["BDToMat"].apply(nir_interplator).astype("Float64")
     # Calculate Breakeven Inflation Rate (BEI)
     df["BEI"] = ((df["NIR"] + 1) / (df["RIR"] + 1)) - 1
 
     cols_reordered = [
         "MaturityDate",
+        "BDToMat",
         "RIR",
         "NIR",
         "BEI",

{pyield-0.25.2 → pyield-0.25.4}/pyield/bonds/ntnf.py

@@ -239,7 +239,7 @@ def spot_rates(  # noqa
     ltn_rates: pd.Series,
     ntnf_maturities: pd.Series,
     ntnf_rates: pd.Series,
-    show_coupon_rates: bool = False,
+    show_coupons: bool = False,
 ) -> pd.DataFrame:
     """
     Calculate the spot rates (zero coupon rates) for NTN-F bonds using the bootstrap
@@ -259,11 +259,12 @@ def spot_rates(  # noqa
         ltn_rates (pd.Series): The LTN known rates.
         ntnf_maturities (pd.Series): The NTN-F known maturities.
         ntnf_rates (pd.Series): The NTN-F known rates.
-        show_coupon_rates (bool): If True, show also July rates corresponding to the
+        show_coupons (bool): If True, show also July rates corresponding to the
             coupon payments. Defaults to False.
 
     Returns:
-        pd.DataFrame: DataFrame with columns "MaturityDate" and "SpotRate"
+        pd.DataFrame: DataFrame with columns "BDToMat", "MaturityDate" and "SpotRate".
+            "BDToMat" is the business days from the settlement date to the maturities.
 
     Examples:
 
@@ -276,14 +277,13 @@ def spot_rates(  # noqa
         ...     ntnf_maturities=df_ntnf["MaturityDate"],
         ...     ntnf_rates=df_ntnf["IndicativeRate"],
         ... )
-          MaturityDate  SpotRate
-        0   2025-01-01  0.108837
-        1   2027-01-01  0.119981
-        2   2029-01-01  0.122113
-        3   2031-01-01  0.122231
-        4   2033-01-01  0.121355
-        5   2035-01-01  0.121398
-
+          MaturityDate  BDToMat  SpotRate
+        0   2025-01-01       83  0.108837
+        1   2027-01-01      584  0.119981
+        2   2029-01-01     1083  0.122113
+        3   2031-01-01     1584  0.122231
+        4   2033-01-01     2088  0.121355
+        5   2035-01-01     2587  0.121398
     """
     # Process and validate the input data
     settlement = dc.convert_input_dates(settlement)
@@ -305,16 +305,16 @@ def spot_rates(  # noqa
 
     # Create a DataFrame with all coupon dates and the corresponding YTM
     df = pd.DataFrame(data=all_coupon_dates, columns=["MaturityDate"])
-    df["BDays"] = bday.count(start=settlement, end=df["MaturityDate"])
-    df["BYears"] = df["BDays"] / 252
+    df["BDToMat"] = bday.count(start=settlement, end=df["MaturityDate"])
+    df["BYears"] = df["BDToMat"] / 252
     df["Coupon"] = COUPON_PMT
-    df["YTM"] = df["BDays"].apply(ntnf_rate_interpolator)
+    df["YTM"] = df["BDToMat"].apply(ntnf_rate_interpolator)
 
     # The Bootstrap loop to calculate spot rates
     for index, row in df.iterrows():
         if row["MaturityDate"] <= ltn_maturities.max():
             # Use LTN rates for maturities before the last LTN maturity date
-            df.at[index, "SpotRate"] = ltn_rate_interpolator(row["BDays"])
+            df.at[index, "SpotRate"] = ltn_rate_interpolator(row["BDToMat"])
             continue
 
         # Calculate the present value of the coupon payments
@@ -323,19 +323,20 @@ def spot_rates(  # noqa
         cf_present_value = bt.calculate_present_value(
             cash_flows=cf_df["Coupon"],
             rates=cf_df["SpotRate"],
-            periods=cf_df["BDays"] / 252,
+            periods=cf_df["BDToMat"] / 252,
         )
 
         bond_price = price(settlement, row["MaturityDate"], row["YTM"])
         price_factor = FINAL_PMT / (bond_price - cf_present_value)
         df.at[index, "SpotRate"] = price_factor ** (1 / row["BYears"]) - 1
 
-    df = df[["MaturityDate", "SpotRate"]].copy()
+    df = df[["MaturityDate", "BDToMat", "SpotRate"]].copy()
     df["SpotRate"] = df["SpotRate"].astype("Float64")
-    if show_coupon_rates:
-        return df
-    else:
-        return df.query("MaturityDate in @ntnf_maturities").reset_index(drop=True)
+
+    if not show_coupons:
+        df = df.query("MaturityDate in @ntnf_maturities").reset_index(drop=True)
+
+    return df
 
 
 def di_spreads(reference_date: DateScalar) -> pd.DataFrame:
@@ -485,10 +486,10 @@ def di_net_spread(  # noqa
 
     # Calculate cash flows and business days between settlement and payment dates
     df = cash_flows(settlement, ntnf_maturity).reset_index()
-    df["BDays"] = bday.count(settlement, df["PaymentDate"])
+    df["BDToMat"] = bday.count(settlement, df["PaymentDate"])
 
     byears = bday.count(settlement, df["PaymentDate"]) / 252
-    di_interp = df["BDays"].apply(ff_interpolator)
+    di_interp = df["BDToMat"].apply(ff_interpolator)
     bond_price = price(settlement, ntnf_maturity, ntnf_rate)
     bond_cash_flows = df["CashFlow"]
 
@@ -551,8 +552,8 @@ def premium(
     settlement = dc.convert_input_dates(settlement)
 
     df = cash_flows(settlement, ntnf_maturity, adj_payment_dates=True)
-    df["BDays"] = bday.count(settlement, df["PaymentDate"])
-    df["BYears"] = df["BDays"] / 252
+    df["BDToMat"] = bday.count(settlement, df["PaymentDate"])
+    df["BYears"] = df["BDToMat"] / 252
 
     ff_interpolator = ip.Interpolator(
         "flat_forward",
@@ -560,13 +561,13 @@ def premium(
         di_rates,
     )
 
-    df["DIRate"] = df["BDays"].apply(ff_interpolator)
+    df["DIRate"] = df["BDToMat"].apply(ff_interpolator)
 
     # Calculate the present value of the cash flows using the DI rate
     bond_price = bt.calculate_present_value(
         cash_flows=df["CashFlow"],
         rates=df["DIRate"],
-        periods=df["BDays"] / 252,
+        periods=df["BDToMat"] / 252,
     )
 
     # Calculate the rate corresponding to this price
@@ -600,8 +601,8 @@ def historical_premium(
     ntnf_ytm = float(ntnf_ytms.iloc[0])
 
     df = cash_flows(reference_date, maturity, adj_payment_dates=True)
-    df["BDays"] = bday.count(reference_date, df["PaymentDate"])
-    df["BYears"] = df["BDays"] / 252
+    df["BDToMat"] = bday.count(reference_date, df["PaymentDate"])
+    df["BYears"] = df["BDToMat"] / 252
     df["ReferenceDate"] = reference_date
 
     dif = di.DIFutures()  # Instantiate the DI Futures class
@@ -615,7 +616,7 @@ def historical_premium(
     bond_price = bt.calculate_present_value(
         cash_flows=df["CashFlow"],
         rates=df["DIRate"],
-        periods=df["BDays"] / 252,
+        periods=df["BDToMat"] / 252,
     )
 
     # Calculate the rate corresponding to this price

pyield-0.25.2/pyield/__about__.py

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