PYield 0.12.2__tar.gz → 0.13.0__tar.gz

{pyield-0.12.2 → pyield-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PYield
-Version: 0.12.2
+Version: 0.13.0
 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.13.0/pyield/__about__.py

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

{pyield-0.12.2 → pyield-0.13.0}/pyield/bonds/lft.py

@@ -32,7 +32,7 @@ def anbima_rates(reference_date: str | pd.Timestamp) -> pd.Series:
     return an.get_anbima_rates(reference_date, "LFT")
 
 
-def anbima_historical_rates(maturity_date: str | pd.Timestamp) -> pd.Series:
+def anbima_historical_rates(maturity: str | pd.Timestamp) -> pd.Series:
     """
     Fetch historical LFT Anbima indicative rates for the given maturity date.
 
@@ -42,21 +42,21 @@ def anbima_historical_rates(maturity_date: str | pd.Timestamp) -> pd.Series:
     Returns:
         pd.Series: A Series containing the rates indexed by reference date.
     """
-    return an.get_anbima_historical_rates("LFT", maturity_date)
+    return an.get_anbima_historical_rates("LFT", maturity)
 
 
 def quotation(
-    settlement_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
-    yield_rate: float,
+    settlement: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
+    rate: float,
 ) -> float:
     """
     Calculate the quotation of a LFT bond using Anbima rules.
 
     Args:
-        settlement_date (str | pd.Timestamp): The settlement date of the bond.
-        maturity_date (str | pd.Timestamp): The maturity date of the bond.
-        yield_rate (float): The annualized yield of the bond
+        settlement (str | pd.Timestamp): The settlement date of the bond.
+        maturity (str | pd.Timestamp): The maturity date of the bond.
+        rate (float): The annualized yield rate of the bond
 
     Returns:
         float: The quotation of the bond.
@@ -64,22 +64,22 @@ def quotation(
     Examples:
         Calculate the quotation of a LFT bond with a 0.02 yield rate:
         >>> lft.quotation(
-        ...     settlement_date="24-07-2024",
-        ...     maturity_date="01-09-2030",
-        ...     yield_rate=0.001717,  # 0.1717%
+        ...     settlement="24-07-2024",
+        ...     maturity="01-09-2030",
+        ...     rate=0.001717,  # 0.1717%
         ... )
         98.9645
     """
     # Validate and normalize dates
-    settlement_date = dc.convert_date(settlement_date)
-    maturity_date = dc.convert_date(maturity_date)
+    settlement = dc.convert_date(settlement)
+    maturity = dc.convert_date(maturity)
 
     # The number of bdays between settlement (inclusive) and the maturity (exclusive)
-    bdays = bday.count(settlement_date, maturity_date)
+    bdays = bday.count(settlement, maturity)
 
     # Calculate the number of periods truncated as per Anbima rules
     num_of_years = ut.truncate(bdays / 252, 14)
 
-    discount_factor = 1 / (1 + yield_rate) ** num_of_years
+    discount_factor = 1 / (1 + rate) ** num_of_years
 
     return ut.truncate(100 * discount_factor, 4)

{pyield-0.12.2 → pyield-0.13.0}/pyield/bonds/ltn.py

@@ -34,7 +34,7 @@ def anbima_rates(reference_date: str | pd.Timestamp) -> pd.Series:
     return an.get_anbima_rates(reference_date, "LTN")
 
 
-def anbima_historical_rates(maturity_date: str | pd.Timestamp) -> pd.Series:
+def anbima_historical_rates(maturity: str | pd.Timestamp) -> pd.Series:
     """
     Fetch historical LTN Anbima indicative rates for the given maturity date.
 
@@ -44,23 +44,23 @@ def anbima_historical_rates(maturity_date: str | pd.Timestamp) -> pd.Series:
     Returns:
         pd.Series: A Series containing the rates for the given maturity date.
     """
-    return an.get_anbima_historical_rates("LTN", maturity_date)
+    return an.get_anbima_historical_rates("LTN", maturity)
 
 
 def price(
-    settlement_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
-    discount_rate: float,
+    settlement: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
+    rate: float,
 ) -> float:
     """
     Calculate the LTN price using Anbima rules.
 
     Args:
-        settlement_date (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
+        settlement (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
             or a pandas Timestamp.
-        maturity_date (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
+        maturity (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
             a pandas Timestamp.
-        discount_rate (float): The discount rate used to calculate the present value of
+        rate (float): The discount rate used to calculate the present value of
             the cash flows, which is the yield to maturity (YTM) of the NTN-F.
 
     Returns:
@@ -75,16 +75,16 @@ def price(
     """
 
     # Validate and normalize dates
-    settlement_date = dc.convert_date(settlement_date)
-    maturity_date = dc.convert_date(maturity_date)
+    settlement = dc.convert_date(settlement)
+    maturity = dc.convert_date(maturity)
 
     # Calculate the number of business days between settlement and cash flow dates
-    bdays = bday.count(settlement_date, maturity_date)
+    bdays = bday.count(settlement, maturity)
 
     # Calculate the number of periods truncated as per Anbima rule
     num_of_years = ut.truncate(bdays / 252, 14)
 
-    discount_factor = (1 + discount_rate) ** num_of_years
+    discount_factor = (1 + rate) ** num_of_years
 
     # Truncate the price to 6 decimal places as per Anbima rules
     return ut.truncate(FACE_VALUE / discount_factor, 6)

{pyield-0.12.2 → pyield-0.13.0}/pyield/bonds/ntnb.py

@@ -47,7 +47,7 @@ def anbima_rates(reference_date: str | pd.Timestamp) -> pd.Series:
     return an.get_anbima_rates(reference_date, "NTN-B")
 
 
-def anbima_historical_rates(maturity_date: str | pd.Timestamp) -> pd.Series:
+def anbima_historical_rates(maturity: str | pd.Timestamp) -> pd.Series:
     """
     Fetch historical NTN-B Anbima indicative rates for the given maturity date.
 
@@ -57,7 +57,7 @@ def anbima_historical_rates(maturity_date: str | pd.Timestamp) -> pd.Series:
     Returns:
         pd.Series: A Series containing the rates for the given maturity date.
     """
-    return an.get_anbima_historical_rates("NTN-B", maturity_date)
+    return an.get_anbima_historical_rates("NTN-B", maturity)
 
 
 def _coupon_dates_map(
@@ -96,8 +96,8 @@ def _coupon_dates_map(
 
 
 def coupon_dates(
-    start_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
+    start: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
 ) -> pd.Series:
     """
     Generate all remaining coupon dates between a given date and the maturity date.
@@ -113,23 +113,23 @@ def coupon_dates(
         list[pd.Timestamp]: List of coupon dates between start and maturity dates.
     """
     # Validate and normalize dates
-    start_date = dc.convert_date(start_date)
-    maturity_date = dc.convert_date(maturity_date)
+    start = dc.convert_date(start)
+    maturity = dc.convert_date(maturity)
 
     # Check if maturity date is after the start date
-    if maturity_date < start_date:
+    if maturity < start:
         raise ValueError("Maturity date must be after the start date.")
 
     # Check if the maturity date is a valid NTN-B maturity date
-    if maturity_date.day != COUPON_DAY or maturity_date.month not in COUPON_MONTHS:
+    if maturity.day != COUPON_DAY or maturity.month not in COUPON_MONTHS:
         raise ValueError("NTN-B maturity must be 15/02, 15/05, 15/08, or 15/11.")
 
     # Initialize loop variables
-    cp_date = maturity_date
+    cp_date = maturity
     cp_dates = []
 
     # Iterate backwards from the maturity date to the settlement date
-    while cp_date >= start_date:
+    while cp_date >= start:
         cp_dates.append(cp_date)
         # Move the coupon date back 6 months
         cp_date -= pd.DateOffset(months=6)
@@ -138,19 +138,19 @@ def coupon_dates(
 
 
 def quotation(
-    settlement_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
-    discount_rate: float,
+    settlement: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
+    rate: float,
 ) -> float:
     """
     Calculate the NTN-B quotation in base 100 using Anbima rules.
 
     Args:
-        settlement_date (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
+        settlement (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
             or a pandas Timestamp.
-        maturity_date (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
+        maturity (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
             a pandas Timestamp.
-        discount_rate (float): The discount rate used to calculate the present value of
+        rate (float): The discount rate used to calculate the present value of
             the cash flows, which is the yield to maturity (YTM) of the NTN-B.
 
     Returns:
@@ -169,25 +169,25 @@ def quotation(
         99.5341
     """
     # Validate and normalize dates
-    settlement_date = dc.convert_date(settlement_date)
-    maturity_date = dc.convert_date(maturity_date)
+    settlement = dc.convert_date(settlement)
+    maturity = dc.convert_date(maturity)
 
     # Get the coupon dates between the settlement and maturity dates
-    payment_dates = coupon_dates(settlement_date, maturity_date)
+    payment_dates = coupon_dates(settlement, maturity)
 
     # Coupon payment dates must be after the settlement date
-    payment_dates = payment_dates[payment_dates > settlement_date]
+    payment_dates = payment_dates[payment_dates > settlement]
 
     # Calculate the number of business days between settlement and cash flow dates
-    bdays = bday.count(settlement_date, payment_dates)
+    bdays = bday.count(settlement, payment_dates)
 
     # Set the cash flow at maturity to FINAL_PMT and the others to COUPON_PMT
-    cash_flows = np.where(payment_dates == maturity_date, FINAL_PMT, COUPON_PMT)
+    cash_flows = np.where(payment_dates == maturity, FINAL_PMT, COUPON_PMT)
 
     # Calculate the number of periods truncated as per Anbima rules
     num_of_years = ut.truncate(bdays / 252, 14)
 
-    discount_factor = (1 + discount_rate) ** num_of_years
+    discount_factor = (1 + rate) ** num_of_years
 
     # Calculate the present value of each cash flow (DCF) rounded as per Anbima rules
     discounted_cash_flows = (cash_flows / discount_factor).round(10)
@@ -222,26 +222,30 @@ def price(
 
 def _calculate_coupons_pv(
     bootstrap_df: pd.DataFrame,
-    settlement_date: pd.Timestamp,
-    maturity_date: pd.Timestamp,
+    settlement: pd.Timestamp,
+    maturity: pd.Timestamp,
 ) -> float:
     # Create a subset DataFrame with only the coupon payments (without last payment)
-    cp_dates_wo_last = coupon_dates(settlement_date, maturity_date)[:-1]  # noqa
+    cp_dates_wo_last = coupon_dates(settlement, maturity)[:-1]  # noqa
+    if len(cp_dates_wo_last) == 0:
+        return 0
+
     df_coupons = bootstrap_df.query("MaturityDate in @cp_dates_wo_last").copy()
     df_coupons["Coupon"] = COUPON_PMT
 
     # Calculate the present value of the coupon payments
     pv = ut.calculate_present_value(
         cash_flows=df_coupons["Coupon"],
-        discount_rates=df_coupons["SpotRate"],
-        time_periods=df_coupons["BDays"] / 252,
+        rates=df_coupons["SpotRate"],
+        periods=df_coupons["BDays"] / 252,
     )
     return pv
 
 
 def spot_rates(
-    settlement_date: str | pd.Timestamp,
-    ytm_rates: pd.Series,
+    settlement: str | pd.Timestamp,
+    rates: list[float] | pd.Series,
+    maturities: list[str | pd.Timestamp],
 ) -> pd.DataFrame:
     """
     Calculate the spot rates for NTN-B bonds using the bootstrap method.
@@ -269,24 +273,24 @@ def spot_rates(
             - Calculate the real spot rates for each maturity date.
     """
     # Process and validate the input data
-    settlement_date = dc.convert_date(settlement_date)
-    ytm_rates = ut.standardize_rates(ytm_rates)
+    settlement = dc.convert_date(settlement)
+    maturities = pd.to_datetime(maturities, errors="coerce", dayfirst=True)
 
     # Create the interpolator object
     ytm_rate_interpolator = it.Interpolator(
         method="flat_forward",
-        known_bdays=bday.count(settlement_date, ytm_rates.index),
-        known_rates=ytm_rates,
+        known_bdays=bday.count(settlement, maturities),
+        known_rates=rates,
     )
 
-    last_ntnb = ytm_rates.index.max()
+    last_ntnb = maturities.max()
 
     # Generate coupon dates up to the longest maturity date
-    all_coupon_dates = _coupon_dates_map(start=settlement_date, end=last_ntnb)
+    all_coupon_dates = _coupon_dates_map(start=settlement, end=last_ntnb)
 
     # Create a DataFrame with all coupon dates and the corresponding YTM
     df_spot = pd.DataFrame(data=all_coupon_dates, columns=["MaturityDate"])
-    df_spot["BDays"] = bday.count(settlement_date, df_spot["MaturityDate"])
+    df_spot["BDays"] = bday.count(settlement, df_spot["MaturityDate"])
     df_spot["YTM"] = df_spot["BDays"].apply(ytm_rate_interpolator)
 
     # The Bootstrap loop to calculate spot rates
@@ -297,45 +301,26 @@ def spot_rates(
         ytm = df_spot.at[index, "YTM"]
 
         # Get the coupon dates for the bond without the last one (principal + coupon)
-        cp_dates = coupon_dates(settlement_date, maturity)
+        cp_dates = coupon_dates(settlement, maturity)
 
         # 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(cp_dates) == 1 and cp_dates[0] == ytm_rates.index[0]:
+        if len(cp_dates) == 1 and cp_dates[0] == rates.index[0]:
             df_spot.at[index, "SpotRate"] = ytm
             continue
 
         # Calculate the real spot rate for the bond
-        coupons_pv = _calculate_coupons_pv(df_spot, settlement_date, maturity)
-        bond_price = quotation(settlement_date, maturity, ytm)
+        coupons_pv = _calculate_coupons_pv(df_spot, settlement, maturity)
+        bond_price = quotation(settlement, maturity, ytm)
         spot_rate = (FINAL_PMT / (bond_price - coupons_pv)) ** (252 / bdays) - 1
         df_spot.at[index, "SpotRate"] = spot_rate
 
     df_spot.drop(columns=["BDays"], inplace=True)
     # Return the result without the intermediate coupon dates (virtual bonds)
-    existing_maturities = ytm_rates.index  # noqa
+    existing_maturities = rates.index  # noqa
     return df_spot.query("MaturityDate in @existing_maturities").reset_index(drop=True)
 
 
-def anbima_spot_rates(
-    reference_date: str | pd.Timestamp,
-    settlement_date: str | pd.Timestamp,
-) -> pd.DataFrame:
-    """
-    Fetch the NTN-B Anbima indicative rates and calculate the spot rates for the bonds.
-
-    Args:
-        reference_date (str | pd.Timestamp): The reference date for fetching the data.
-        settlement_date (str | pd.Timestamp): The reference date for settlement.
-
-    Returns:
-        pd.DataFrame: DataFrame containing the maturity dates and corresponding real
-            spot rates.
-    """
-    ytm_rates = anbima_rates(reference_date)
-    return spot_rates(settlement_date, ytm_rates)
-
-
 def _get_nir_df(reference_date: pd.Timestamp) -> pd.DataFrame:
     """
     Fetch the Nominal Interest Rate (NIR) data for NTN-B bonds.
@@ -355,8 +340,6 @@ def _get_nir_df(reference_date: pd.Timestamp) -> pd.DataFrame:
             "TickerSymbol",
             "ExpirationDate",
             "BDaysToExp",
-            "CurrentAskRate",
-            "CurrentBidRate",
             "NIR_DI",
         ]
     elif "SettlementRate" in df.columns:
@@ -369,7 +352,7 @@ def _get_nir_df(reference_date: pd.Timestamp) -> pd.DataFrame:
             "NIR_DI",
         ]
     else:
-        raise ValueError("NIR data not found in the DataFrame.")
+        raise ValueError("DI data not available.")
 
     df = df[keep_cols].dropna(subset=["NIR_DI"])
 
@@ -392,8 +375,9 @@ def _get_nir_df(reference_date: pd.Timestamp) -> pd.DataFrame:
 
 def bei_rates(
     reference_date: str | pd.Timestamp,
-    settlement_date: str | pd.Timestamp,
-    ytm_rates: pd.Series,
+    settlement: str | pd.Timestamp,
+    rates: list[float] | pd.Series,
+    maturities: list[str | pd.Timestamp] | pd.Series,
 ) -> pd.DataFrame:
     """
     Calculate the Breakeven Inflation (BEI) for NTN-B bonds based on nominal and real
@@ -402,26 +386,27 @@ def bei_rates(
     Args:
         reference_date (str or pd.Timestamp): The reference date for fetching data and
             performing calculations.
-        settlement_date (str or pd.Timestamp): The settlement date for the bonds.
-        ytm_rates (pd.Series): A series of Yield to Maturity (YTM) rates corresponding
+        settlement (str or pd.Timestamp): The settlement date for the bonds.
+        rates (pd.Series): A series of Yield to Maturity (YTM) rates corresponding
             to the maturity dates of the bonds indexed by the maturity dates.
 
     Returns:
         pd.DataFrame: DataFrame containing the breakeven inflation rates.
 
     Returned columns:
-        - MaturityDate: Maturity date of the bond.
+        - MaturityDate: Maturity date of the bonds
         - BDays: Number of business days from the settlement date to the maturity.
-        - YTM: Yield to Maturity rate for the bond.
-        - RIR: Real Interest Rate for the bond.
-        - NIR_DI: Nominal Interest Rate for the bond.
-        - NIR_PRE: Nominal Interest Rate for the bond with DI spread.
-        - BEI_DI: Breakeven Inflation Rate for the bond.
-        - BEI_PRE: Breakeven Inflation Rate for the bond adjusted for DI spread.
+        - YTM: Yield to Maturity rate for the bonds
+        - RIR: Real Interest Rate for the bonds based on the spot rates.
+        - NIR_DI: Nominal Interest Rate based on DI Futures.
+        - NIR_PRE: Nominal Interest Rate for the prefixed bonds.
+        - BEI_DI: Breakeven Inflation Rate calculated with DI Futures.
+        - BEI_PRE: Breakeven Inflation Rate calculated with prefixed bonds.
     """
     # Normalize input dates
     reference_date = dc.convert_date(reference_date)
-    settlement_date = dc.convert_date(settlement_date)
+    settlement = dc.convert_date(settlement)
+    maturities = pd.to_datetime(maturities, errors="coerce", dayfirst=True)
 
     # Fetch Nominal Interest Rate (NIR) data
     df_nir = _get_nir_df(reference_date)
@@ -432,7 +417,7 @@ def bei_rates(
         known_rates=df_nir["NIR_DI"],
     )
     # Calculate Real Interest Rate (RIR)
-    df = spot_rates(settlement_date, ytm_rates)
+    df = spot_rates(settlement, rates, maturities)
     df = df.rename(columns={"SpotRate": "RIR"})
     df["BDays"] = bday.count(reference_date, df["MaturityDate"])
     df["NIR_DI"] = df["BDays"].apply(ytm_interplator)

{pyield-0.12.2 → pyield-0.13.0}/pyield/bonds/ntnf.py

@@ -23,7 +23,7 @@ FINAL_PMT = 1048.80885
 di_data = di.DIData()
 
 
-def check_maturity_date(maturity_date: pd.Timestamp) -> None:
+def check_maturity_date(maturity: pd.Timestamp) -> None:
     """
     Check if the maturity date is a valid NTN-F maturity date.
 
@@ -33,13 +33,13 @@ def check_maturity_date(maturity_date: pd.Timestamp) -> None:
     Raises:
         ValueError: If the maturity date is not the 1st of January.
     """
-    if maturity_date.day != 1 or maturity_date.month not in COUPON_MONTHS:
+    if maturity.day != 1 or maturity.month not in COUPON_MONTHS:
         raise ValueError("NTN-F maturity date must be the 1st of January.")
 
 
 def coupon_dates(
-    settlement_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
+    settlement: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
 ) -> pd.Series:
     """
     Generate all remaining coupon dates between a settlement date and a maturity date.
@@ -48,29 +48,29 @@ def coupon_dates(
     The NTN-F bond is determined by its maturity date.
 
     Args:
-        settlement_date (str | pd.Timestamp): The settlement date.
-        maturity_date (str | pd.Timestamp): The maturity date.
+        settlement (str | pd.Timestamp): The settlement date.
+        maturity (str | pd.Timestamp): The maturity date.
 
     Returns:
         pd.Series: Series of coupon dates within the specified range.
     """
     # Validate and normalize dates
-    settlement_date = dc.convert_date(settlement_date)
-    maturity_date = dc.convert_date(maturity_date)
+    settlement = dc.convert_date(settlement)
+    maturity = dc.convert_date(maturity)
 
     # Check if the maturity date is valid
-    check_maturity_date(maturity_date)
+    check_maturity_date(maturity)
 
     # Check if maturity date is after the start date
-    if maturity_date <= settlement_date:
+    if maturity <= settlement:
         raise ValueError("Maturity date must be after the start date.")
 
     # Initialize loop variables
-    coupon_date = maturity_date
+    coupon_date = maturity
     coupon_dates = []
 
     # Iterate backwards from the maturity date to the settlement date
-    while coupon_date > settlement_date:
+    while coupon_date > settlement:
         coupon_dates.append(coupon_date)
         # Move the coupon date back 6 months
         coupon_date -= pd.DateOffset(months=6)
@@ -80,8 +80,8 @@ def coupon_dates(
 
 
 def cash_flows(
-    settlement_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
+    settlement: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
 ) -> pd.Series:
     """
     Generate the cash flows for the NTN-F bond between the settlement (exclusive) and
@@ -89,24 +89,24 @@ def cash_flows(
     payment at maturity.
 
     Args:
-        settlement_date (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
+        settlement (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
             or a pandas Timestamp.
-        maturity_date (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
+        maturity (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
             a pandas Timestamp.
 
     Returns:
         pd.Series: Series of cash flows within the specified range.
     """
     # Validate input dates
-    settlement_date = dc.convert_date(settlement_date)
-    maturity_date = dc.convert_date(maturity_date)
-    check_maturity_date(maturity_date)
+    settlement = dc.convert_date(settlement)
+    maturity = dc.convert_date(maturity)
+    check_maturity_date(maturity)
 
     # Get the coupon payment dates between the settlement and maturity dates
-    payment_dates = coupon_dates(settlement_date, maturity_date)
+    payment_dates = coupon_dates(settlement, maturity)
 
     # Set the cash flow at maturity to FINAL_PMT and the others to COUPON_PMT
-    cfs = np.where(payment_dates == maturity_date, FINAL_PMT, COUPON_PMT)
+    cfs = np.where(payment_dates == maturity, FINAL_PMT, COUPON_PMT)
 
     df = pd.DataFrame(data=cfs, index=payment_dates, columns=["CashFlow"])
     df.index.name = "PaymentDate"
@@ -115,21 +115,21 @@ def cash_flows(
 
 
 def price(
-    settlement_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
-    ytm_rate: float,
+    settlement: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
+    rate: float,
 ) -> float:
     """
     Calculate the NTN-F price using Anbima rules, which corresponds to the present
         value of the cash flows discounted at the given yield to maturity rate (YTM).
 
     Args:
-        settlement_date (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
+        settlement (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
             or a pandas Timestamp.
-        maturity_date (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
+        maturity (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY' format or
             a pandas Timestamp.
-        ytm_rate (float): The discount rate used to calculate the present value of
-            the cash flows.
+        rate (float): The discount rate (yield to maturity) used to calculate the
+            present value of the cash flows.
 
     Returns:
         float: The NTN-F price using Anbima rules.
@@ -144,17 +144,32 @@ def price(
         >>> price("05-07-2024", "01-01-2035", 0.11921)
         895.359254
     """
-    df_cf = cash_flows(settlement_date, maturity_date).reset_index()
+    df_cf = cash_flows(settlement, maturity).reset_index()
     cfs = df_cf["CashFlow"]
-    bdays = bday.count(settlement_date, df_cf["PaymentDate"])
+    bdays = bday.count(settlement, df_cf["PaymentDate"])
     byears = ut.truncate(bdays / 252, 14)
-    discount_factors = (1 + ytm_rate) ** byears
+    discount_factors = (1 + rate) ** byears
     # Calculate the present value of each cash flow (DCF) rounded as per Anbima rules
     dcf = (cfs / discount_factors).round(9)
     # Return the sum of the discounted cash flows truncated as per Anbima rules
     return ut.truncate(dcf.sum(), 6)
 
 
+def maturities(reference_date: str | pd.Timestamp) -> list[pd.Timestamp]:
+    """
+    Fetch the NTN-F bond maturities available for the given reference date.
+
+    Args:
+        reference_date (str | pd.Timestamp): The reference date for fetching the data.
+
+    Returns:
+        list[pd.Timestamp]: A list of NTN-F bond maturities available for the reference
+            date.
+    """
+    rates = an.get_anbima_rates(reference_date, "NTN-F")
+    return rates.index.to_list()
+
+
 def anbima_data(reference_date: str | pd.Timestamp) -> pd.DataFrame:
     """
     Fetch NTN-F Anbima data for the given reference date.
@@ -170,23 +185,24 @@ def anbima_data(reference_date: str | pd.Timestamp) -> pd.DataFrame:
 
 def indicative_rates(
     reference_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp | None = None,
+    maturity: str | pd.Timestamp | None = None,
 ) -> pd.Series | float:
     """
-    Fetch NTN-F Anbima indicative rates for the given reference date.
+    Fetch NTN-F Anbima indicative rates for the given reference date. If a maturity date
+    is provided, the function returns the rate for the given maturity date.
 
     Args:
         reference_date (str | pd.Timestamp): The reference date for fetching the data.
+        maturity_date (str | pd.Timestamp, optional): The maturity date of the bond.
 
     Returns:
         pd.Series: A Series containing the rates indexed by maturity date.
     """
     rates = an.get_anbima_rates(reference_date, "NTN-F")
-
-    if maturity_date:
-        maturity_date = dc.convert_date(maturity_date)
-        if maturity_date in rates.index:
-            return float(rates[maturity_date])
+    if maturity:
+        maturity = dc.convert_date(maturity)
+        if maturity in rates.index:
+            return float(rates[maturity])
         else:
             return float("nan")
     return rates
@@ -207,27 +223,29 @@ def anbima_historical_rates(maturity_date: str | pd.Timestamp) -> pd.Series:
 
 def _calculate_coupons_pv(
     bootstrap_df: pd.DataFrame,
-    settlement_date: pd.Timestamp,
-    maturity_date: pd.Timestamp,
+    settlement: pd.Timestamp,
+    maturity: pd.Timestamp,
 ) -> float:
     # Create a subset DataFrame with only the coupon payments (without last payment)
-    cp_dates_wo_last = coupon_dates(settlement_date, maturity_date)[:-1]  # noqa
+    cp_dates_wo_last = coupon_dates(settlement, maturity)[:-1]  # noqa
     df_coupons = bootstrap_df.query("MaturityDate in @cp_dates_wo_last").copy()
     df_coupons["Coupon"] = COUPON_PMT
 
     # Calculate the present value of the coupon payments
     pv = ut.calculate_present_value(
         cash_flows=df_coupons["Coupon"],
-        discount_rates=df_coupons["SpotRate"],
-        time_periods=df_coupons["BDays"] / 252,
+        rates=df_coupons["SpotRate"],
+        periods=df_coupons["BDays"] / 252,
     )
     return pv
 
 
 def spot_rates(
-    settlement_date: str | pd.Timestamp,
-    ltn_rates: pd.Series,
-    ntnf_rates: pd.Series,
+    settlement: str | pd.Timestamp,
+    ltn_rates: list[float] | pd.Series,
+    ltn_maturities: list[pd.Timestamp] | pd.Series,
+    ntnf_rates: list[float] | pd.Series,
+    ntnf_maturities: list[pd.Timestamp] | pd.Series,
 ) -> pd.DataFrame:
     """
     Calculate the spot rates for NTN-F bonds using the bootstrap method.
@@ -249,32 +267,32 @@ def spot_rates(
             the corresponding spot rates.
     """
     # Process and validate the input data
-    settlement_date = dc.convert_date(settlement_date)
-    ltn_rates = ut.standardize_rates(ltn_rates)
-    ntnf_rates = ut.standardize_rates(ntnf_rates)
+    settlement = dc.convert_date(settlement)
+    ltn_maturities = pd.to_datetime(ltn_maturities, errors="coerce", dayfirst=True)
+    ntnf_maturities = pd.to_datetime(ntnf_maturities, errors="coerce", dayfirst=True)
 
     # Create flat forward interpolators for LTN and NTN-F rates
     ltn_rate_interpolator = Interpolator(
         method="flat_forward",
-        known_bdays=bday.count(settlement_date, ltn_rates.index),
+        known_bdays=bday.count(settlement, ltn_maturities),
         known_rates=ltn_rates,
     )
     ntnf_rate_interpolator = Interpolator(
         method="flat_forward",
-        known_bdays=bday.count(settlement_date, ntnf_rates.index),
+        known_bdays=bday.count(settlement, ntnf_maturities),
         known_rates=ntnf_rates,
     )
 
     # Determine the last maturity dates for LTN and NTN-F rates
-    last_ltn = ltn_rates.index.max()
-    last_ntnf = ntnf_rates.index.max()
+    last_ltn = ltn_maturities.max()
+    last_ntnf = ntnf_maturities.max()
 
     # Generate all coupon dates up to the last NTN-F maturity date
-    all_coupon_dates = coupon_dates(settlement_date, last_ntnf)
+    all_coupon_dates = coupon_dates(settlement, last_ntnf)
 
     # Create a DataFrame with all coupon dates and the corresponding YTM
     df_spot = pd.DataFrame(data=all_coupon_dates, columns=["MaturityDate"])
-    df_spot["BDays"] = bday.count(start=settlement_date, end=df_spot["MaturityDate"])
+    df_spot["BDays"] = bday.count(start=settlement, end=df_spot["MaturityDate"])
     df_spot["YTM"] = df_spot["BDays"].apply(ntnf_rate_interpolator)
 
     # The Bootstrap loop to calculate spot rates
@@ -288,16 +306,16 @@ def spot_rates(
             continue
 
         # Calculate the spot rate for the bond
-        coupons_pv = _calculate_coupons_pv(df_spot, settlement_date, maturity)
+        coupons_pv = _calculate_coupons_pv(df_spot, settlement, maturity)
         ytm = df_spot.at[index, "YTM"]
-        bond_price = price(settlement_date, maturity, ytm)
+        bond_price = price(settlement, maturity, ytm)
         spot_rate = (FINAL_PMT / (bond_price - coupons_pv)) ** (252 / bdays) - 1
         df_spot.at[index, "SpotRate"] = spot_rate
 
     return df_spot
 
 
-def gross_di_spreads(reference_date: str | pd.Timestamp) -> pd.Series:
+def di_gross_spreads(reference_date: str | pd.Timestamp) -> pd.Series:
     """
     Calculates the DI spread for the NTN-F based on ANBIMA's indicative rates.
 
@@ -321,9 +339,9 @@ def gross_di_spreads(reference_date: str | pd.Timestamp) -> pd.Series:
     return df["DISpread"]
 
 
-def net_di_spread(  # noqa
-    settlement_date: str | pd.Timestamp,
-    maturity_date: str | pd.Timestamp,
+def di_net_spread(  # noqa
+    settlement: str | pd.Timestamp,
+    maturity: str | pd.Timestamp,
     ytm: float,
     di_rates: list[float] | pd.Series,
     di_expirations: list[pd.Timestamp] | pd.Series,
@@ -338,47 +356,45 @@ def net_di_spread(  # noqa
     (in bps) that zeroes the difference between the bond's market price and its
     discounted cash flows.
 
-    Parameters:
-    ----------
-    settlement_date : pd.Timestamp
-        The date on which the bond is settled.
-    maturity_date : pd.Timestamp
-        The date on which the bond matures.
-    ytm : float
-        The yield to maturity of the bond.
-    di_rates : list[float]
-        A list of DI rates corresponding to the DI expirations.
-    di_expirations : list[pd.Timestamp]
-        A list of DI expiration dates.
+    Args:
+        settlement (str | pd.Timestamp): The settlement date in 'DD-MM-YYYY' format
+            or a pandas Timestamp.
+        maturity (str | pd.Timestamp): The maturity date in 'DD-MM-YYYY'
+            format or a pandas Timestamp.
+        ytm (float): The yield to maturity (YTM) of the bond.
+        di_rates (list[float] | pd.Series): A list or Series of DI rates.
+        di_expirations (list[pd.Timestamp] | pd.Series): A list or Series of DI
+            expiration dates.
+        initial_guess (float, optional): An initial guess for the spread.
+            Defaults to None.
 
     Returns:
-    -------
-    float
-        The net DI spread in basis points. Returns NaN if a solution cannot be found.
+        float: The net DI spread in basis points.
     """
-
     # Create an interpolator for the DI rates using the flat-forward method
-    settlement_date = dc.convert_date(settlement_date)
-    maturity_date = dc.convert_date(maturity_date)
+    settlement = dc.convert_date(settlement)
+    maturity = dc.convert_date(maturity)
 
     ff_interpolator = Interpolator(
         "flat_forward",
-        bday.count(settlement_date, di_expirations),
+        bday.count(settlement, di_expirations),
         di_rates,
     )
 
-    # Ensure the DI rates and expirations lists are of equal length
+    # Ensure the DI data is valid
     if len(di_rates) != len(di_expirations):
         raise ValueError("di_rates and di_expirations must have the same length.")
+    if len(di_rates) == 0:
+        return float("nan")
 
     # Calculate cash flows and business days between settlement and payment dates
-    df = cash_flows(settlement_date, maturity_date).reset_index()
-    df["BDays"] = bday.count(settlement_date, df["PaymentDate"])
+    df = cash_flows(settlement, maturity).reset_index()
+    df["BDays"] = bday.count(settlement, df["PaymentDate"])
 
     # Calculate business years (252 business days per year)
-    byears = bday.count(settlement_date, df["PaymentDate"]) / 252
+    byears = bday.count(settlement, df["PaymentDate"]) / 252
     di_interp = df["BDays"].apply(ff_interpolator)
-    bond_price = price(settlement_date, maturity_date, ytm)
+    bond_price = price(settlement, maturity, ytm)
     bond_cash_flows = df["CashFlow"]
 
     def price_difference(p):

{pyield-0.12.2 → pyield-0.13.0}/pyield/bonds/utils.py

@@ -36,16 +36,10 @@ def truncate(values: float | pd.Series, decimal_places: int) -> float | pd.Serie
 
 def calculate_present_value(
     cash_flows: pd.Series,
-    discount_rates: pd.Series,
-    time_periods: pd.Series,
+    rates: pd.Series,
+    periods: pd.Series,
 ) -> float:
-    return (cash_flows / (1 + discount_rates) ** time_periods).sum()
-
-
-def standardize_rates(rates: pd.Series) -> pd.Series:
-    if not isinstance(rates.index, pd.DatetimeIndex):
-        raise ValueError("The rates index must be a DatetimeIndex with maturity dates.")
-    return rates.dropna().sort_index()
+    return (cash_flows / (1 + rates) ** periods).sum()
 
 
 def di_spreads(reference_date: pd.Timestamp) -> pd.DataFrame:

{pyield-0.12.2 → pyield-0.13.0}/pyield/di.py

@@ -1,3 +1,5 @@
+from typing import Literal
+
 import pandas as pd
 
 from . import bday
@@ -9,6 +11,11 @@ DI_URL = "https://raw.githubusercontent.com/crdcj/pyield-data/main/di_data.parqu
 class DIData:
     _df = pd.DataFrame()
 
+    def __init__(self):
+        """Initialize the DIData class and load the data."""
+        if self._df.empty or not self._is_data_up_to_date():
+            self._load_data()
+
     @classmethod
     def _load_data(cls):
         print("Loading DI dataset...")
@@ -36,19 +43,31 @@ class DIData:
         cls._load_data()
         return cls._df.copy()
 
+    @staticmethod
+    def _get_rate_column(rate_type: str) -> str:
+        rate_map = {
+            "settlement": "SettlementRate",
+            "min": "MinRate",
+            "max": "MaxRate",
+            "close": "CloseRate",
+        }
+        if rate_type not in rate_map:
+            raise ValueError(
+                "Invalid rate type. Use 'settlement', 'min', 'max', or 'close'."
+            )
+        return rate_map[rate_type]
+
     @classmethod
-    def settlement_rates(
+    def rates(
         cls,
         trade_date: str | pd.Timestamp | None = None,
         expiration_date: str | pd.Timestamp | None = None,
+        rate_type: Literal["settlement", "min", "max", "close"] = "settlement",
         adjust_exp_date: bool = False,
-    ) -> pd.DataFrame:
+    ) -> pd.DataFrame | float:
+        rate_col = cls._get_rate_column(rate_type)
         cls._check_for_updates()
-        df = cls._df[["TradeDate", "ExpirationDate", "SettlementRate"]].copy()
-
-        if trade_date:
-            trade_date = dc.convert_date(trade_date)
-            df.query("TradeDate == @trade_date", inplace=True)
+        df = cls._df[["TradeDate", "ExpirationDate", f"{rate_col}"]].copy()
 
         if expiration_date:
             expiration_date = dc.convert_date(expiration_date)
@@ -56,28 +75,16 @@ class DIData:
             expiration_date = bday.offset(expiration_date, 0)
             df.query("ExpirationDate == @expiration_date", inplace=True)
 
-        if adjust_exp_date:
-            df["ExpirationDate"] = (
-                df["ExpirationDate"].dt.to_period("M").dt.to_timestamp()
-            )
-
-        return df.sort_values(["TradeDate", "ExpirationDate"]).reset_index(drop=True)
-
-    @classmethod
-    def settlement_rate(
-        cls,
-        trade_date: str | pd.Timestamp,
-        expiration_date: str | pd.Timestamp,
-    ) -> float:
-        cls._check_for_updates()
-        df = cls._df.copy()
-
-        trade_date = dc.convert_date(trade_date)
-        df.query("TradeDate == @trade_date", inplace=True)
-
-        expiration_date = dc.convert_date(expiration_date)
-        # Force the expiration date to be a business day
-        expiration_date = bday.offset(expiration_date, 0)
-        df.query("ExpirationDate == @expiration_date", inplace=True)
+        if trade_date:
+            trade_date = dc.convert_date(trade_date)
+            df.query("TradeDate == @trade_date", inplace=True)
 
-        return float(df["SettlementRate"].iat[0])
+        if adjust_exp_date:
+            df["ExpirationDate"] = df["ExpirationDate"].dt.to_period("M")
+            df["ExpirationDate"] = df["ExpirationDate"].dt.to_timestamp()
+
+        df.sort_values(["TradeDate", "ExpirationDate"]).reset_index(drop=True)
+        if len(df.index) == 1:
+            return float(df[f"{rate_col}"].values[0])
+        else:
+            return df

{pyield-0.12.2 → pyield-0.13.0}/pyield/fetchers/anbima.py

@@ -13,7 +13,7 @@ ANBIMA_URL = "https://www.anbima.com.br/informacoes/merc-sec/arqs"
 ANBIMA_MEMBER_URL = "http://www.anbima.associados.rtm/merc_sec/arqs"
 # URL example: https://www.anbima.com.br/informacoes/merc-sec/arqs/ms240614.txt
 RATES_URL = (
-    "https://raw.githubusercontent.com/crdcj/pyield-data/main/anbima_rates.parquet"
+    "https://raw.githubusercontent.com/crdcj/pyield-data/main/anbima_data.parquet"
 )
 
 # Before 13/05/2014 the file was zipped and the endpoint ended with ".exe"
@@ -157,9 +157,8 @@ class RatesData:
     @classmethod
     def _load_data(cls):
         # if cls._df.empty or not cls._is_data_up_to_date():
-        print("Loading ANBIMA rates data...")
+        print("Loading ANBIMA data...")
         cls._df = pd.read_parquet(RATES_URL)
-        cls._df["IndicativeRate"] = (cls._df["IndicativeRate"] / 100).round(6)
         cls._last_update = pd.Timestamp.today().normalize()
 
     @classmethod

{pyield-0.12.2 → pyield-0.13.0}/pyproject.toml

@@ -34,7 +34,7 @@ dependencies = [
     "pyarrow",
 ]
 dynamic = []
-version = "0.12.2"
+version = "0.13.0"
 
 [project.license]
 file = "LICENSE"

pyield-0.12.2/pyield/__about__.py

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