PYield 0.16.3__tar.gz → 0.16.4__tar.gz

{pyield-0.16.3 → pyield-0.16.4}/PKG-INFO

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

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

{pyield-0.16.3 → pyield-0.16.4}/pyield/bonds/lft.py

@@ -2,7 +2,7 @@ import pandas as pd
 
 from .. import bday
 from .. import date_converter as dc
-from ..data import anbima, di
+from ..data import anbima
 from . import bond_tools as bt
 
 
@@ -77,47 +77,26 @@ def quotation(
     return bt.truncate(100 * discount_factor, 4)
 
 
-def premium(lft_rate: float, di_rate: float) -> float:
-    di_factor = (1 + di_rate) ** (1 / 252)
-    lft_factor = (1 + lft_rate) ** (1 / 252) * di_factor
-
-    return (lft_factor - 1) / (di_factor - 1)
-
-
-def historical_premium(
-    reference_date: str | pd.Timestamp,
-    maturity: str | pd.Timestamp,
-) -> float:
+def premium(lft_rate: float, selic_over: float) -> float:
     """
-    Calculate the premium of the LFT bond over the DI Future rate for a given date.
+    Calculate the premium of the LFT bond over the Selic rate (overnight).
+    Obs: The Selic rate (overnight) is not the same as the Selic target rate
 
     Args:
-        reference_date (str | pd.Timestamp): The reference date to fetch the rates.
-        maturity (str | pd.Timestamp): The maturity date of the LFT bond.
+        lft_rate (float): The LFT rate for the bond.
+        selic_over (float): The Selic overnight rate.
 
     Returns:
-        float: The premium of the LFT bond over the DI Future rate for the given date.
-               If the data is not available, returns NaN.
-    """
-    # Convert input dates to a consistent format
-    reference_date = dc.convert_date(reference_date)
-    maturity = dc.convert_date(maturity)
+        float: The premium of the LFT bond over the Selic rate.
 
-    # Retrieve LFT rates for the reference date
-    df_anbima = rates(reference_date)
-    if df_anbima.empty:
-        return float("NaN")
-
-    # Extract the LFT rate for the specified maturity date
-    lft_rates = df_anbima.query("MaturityDate == @maturity")["IndicativeRate"]
-    if lft_rates.empty:
-        return float("NaN")
-    lft_rate = float(lft_rates.iloc[0])
-
-    # Retrieve DI rate for the reference date and maturity
-    di_rate = di.rate(trade_date=reference_date, expiration=maturity)
-    if pd.isnull(di_rate):  # Check if the DI rate is NaN
-        return float("NaN")
-
-    # Calculate and return the premium using the extracted rates
-    return premium(lft_rate, di_rate)
+    Examples:
+        Calculate the premium of a LFT bond with a 0.02 yield rate over the Selic rate:
+        >>> lft_rate = 0.1695 / 100  # 0.1695%
+        >>> selic_over = 10.40 / 100  # 10.40%
+        >>> lft.premium(lft_rate, selic_over)
+        101.71205192837589
+    """
+    adjusted_lft_rate = (lft_rate + 1) * (selic_over + 1) - 1
+    f1 = (adjusted_lft_rate + 1) ** (1 / 252) - 1
+    f2 = (selic_over + 1) ** (1 / 252) - 1
+    return f1 / f2

{pyield-0.16.3 → pyield-0.16.4}/pyield/bonds/ntnf.py

@@ -311,7 +311,6 @@ def _bisection_method(func, a, b, tol=1e-8, maxiter=100):
 def _solve_spread(
     price_difference_func: Callable,
     initial_guess: float | None = None,
-    range_width_bps: float = 50,
 ) -> float:
     """
     Solve for the spread that zeroes the price difference using a bisection method.
@@ -320,8 +319,6 @@ def _solve_spread(
         price_difference_func (callable): The function that computes the difference
             between the bond's market price and its discounted cash flows.
         initial_guess (float, optional): An initial guess for the spread.
-        range_width_bps (float, optional): The width of the range around the initial
-        guess in bps. Defaults to 50 bps.
 
     Returns:
         float: The solution for the spread in bps or NaN if no solution is found.
@@ -329,9 +326,9 @@ def _solve_spread(
     try:
         if initial_guess is not None:
             # range_width_bps below the initial guess
-            a = initial_guess - range_width_bps / 10_000
+            a = initial_guess - 0.005  # 50 bps
             # range_width_bps above the initial guess
-            b = initial_guess + range_width_bps / 10_000
+            b = initial_guess + 0.005  # 50 bps
         else:
             a = -0.01  # Initial guess of -100 bps
             b = 0.01  # Initial guess of 100 bps
@@ -371,7 +368,7 @@ def di_net_spread(  # noqa
         di_rates (pd.Series): A Series of DI rates.
         di_expirations (pd.Series): A list or Series of DI expiration dates.
         initial_guess (float, optional): An initial guess for the spread. Defaults to
-            None.
+            None. A good initial guess is the DI gross spread for the bond.
 
     Returns:
         float: The net DI spread in basis points.
@@ -405,7 +402,7 @@ def di_net_spread(  # noqa
         # Difference between the bond's price and its discounted cash flows
         return (bond_cash_flows / (1 + di_interp + p) ** byears).sum() - bond_price
 
-    # Solve for the spread that zeroes the price difference using the Brent method
+    # Solve for the spread that zeroes the price difference using the bisection method
     p_solution = _solve_spread(price_difference, initial_guess)
     # Convert the solution to basis points (bps) and round to two decimal places
     return round((p_solution * 10_000), 2)

{pyield-0.16.3 → pyield-0.16.4}/pyield/data/indicators.py

@@ -7,15 +7,17 @@ from .. import date_converter as dc
 
 
 def indicator(
-    indicator_type: Literal["IPCA_MR", "SELIC_TARGET", "DI", "VNA_LFT"],
+    indicator_type: Literal["IPCA_MR", "SELIC_TARGET", "SELIC_OVER", "DI", "VNA_LFT"],
     reference_date: str | pd.Timestamp,
-) -> float | None:
+) -> float:
     reference_date = dc.convert_date(reference_date)
     ind_type = str(indicator_type).upper()
     if ind_type == "IPCA_MR":
         return ipca_monthly_rate(reference_date)
     elif ind_type == "SELIC_TARGET":
         return selic_target(reference_date)
+    elif ind_type == "SELIC_OVER":
+        return selic_over(reference_date)
     elif ind_type == "DI":
         return di(reference_date)
     elif ind_type == "VNA_LFT":
@@ -24,7 +26,7 @@ def indicator(
         raise ValueError(f"Invalid indicator type: {ind_type}")
 
 
-def ipca_monthly_rate(reference_date: pd.Timestamp) -> float | None:
+def ipca_monthly_rate(reference_date: pd.Timestamp) -> float:
     """
     Fetches the IPCA (Índice Nacional de Preços ao Consumidor Amplo) monthly rate
     from the IBGE (Instituto Brasileiro de Geografia e Estatística) for a given
@@ -35,7 +37,7 @@ def ipca_monthly_rate(reference_date: pd.Timestamp) -> float | None:
             is fetched. If a string is passed, it should be in 'DD-MM-YYYY' format.
 
     Returns:
-        float | None: The IPCA monthly rate for the specified date as a float.
+        float: The IPCA monthly rate for the specified date as a float.
         Returns None if data is not found or in case of an error.
 
     Notes:
@@ -65,15 +67,14 @@ def ipca_monthly_rate(reference_date: pd.Timestamp) -> float | None:
     # Parse the JSON response
     data = response.json()
 
+    if not data:
+        return float("nan")
     # Extract and return the IPCA monthly growth rate if data is available
-    if data:
-        ipca_str = data[0]["resultados"][0]["series"][0]["serie"][ipca_date]
-        return round(float(ipca_str) / 100, 4)
-    else:
-        return None
+    ipca_str = data[0]["resultados"][0]["series"][0]["serie"][ipca_date]
+    return round(float(ipca_str) / 100, 4)
 
 
-def selic_target(reference_date: pd.Timestamp) -> float | None:
+def selic_target(reference_date: pd.Timestamp) -> float:
     """
     Examples:
         >>> selic_taget("31-05-2024")
@@ -85,14 +86,31 @@ def selic_target(reference_date: pd.Timestamp) -> float | None:
     response = requests.get(api_url, timeout=10)
     response.raise_for_status()
 
-    if selic_date in response.text:
-        data = response.json()
-        return round(float(data[0]["valor"]) / 100, 4)
-    else:
-        return None
+    if selic_date not in response.text:
+        return float("nan")
+    data = response.json()
+    return round(float(data[0]["valor"]) / 100, 4)
+
+
+def selic_over(reference_date: pd.Timestamp) -> float:
+    """
+    Examples:
+        >>> selic_over("26-08-2024")
+        0.1040  # Indicates a SELIC rate of 10.40% p.a.
+    """
+    # https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
+    formatted_date = reference_date.strftime("%d/%m/%Y")
+    api_url = f"https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial={formatted_date}&dataFinal={formatted_date}"
+    response = requests.get(api_url, timeout=10)
+    response.raise_for_status()
 
+    if formatted_date not in response.text:
+        return float("nan")
+    data = response.json()
+    return round(float(data[0]["valor"]) / 100, 4)
 
-def di(reference_date: pd.Timestamp) -> float | None:
+
+def di(reference_date: pd.Timestamp) -> float:
     """
     Examples:
         >>> di("31-05-2024")
@@ -104,14 +122,13 @@ def di(reference_date: pd.Timestamp) -> float | None:
     response = requests.get(api_url, timeout=10)
     response.raise_for_status()
 
-    if di_date in response.text:
-        data = response.json()
-        return round(float(data[0]["valor"]) / 100, 8)
-    else:
-        return None
+    if di_date not in response.text:
+        return float("nan")
+    data = response.json()
+    return round(float(data[0]["valor"]) / 100, 8)
 
 
-def vna_lft(reference_date: pd.Timestamp) -> float | None:
+def vna_lft(reference_date: pd.Timestamp) -> float:
     # url example: https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/20240418APC238
     url_base = "https://www3.bcb.gov.br/novoselic/rest/arquivosDiarios/pub/download/3/"
     url_file = f"{reference_date.strftime('%Y%m%d')}APC238"

{pyield-0.16.3 → pyield-0.16.4}/pyproject.toml

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

pyield-0.16.3/pyield/__about__.py

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