PYield 0.8.2__tar.gz → 0.8.4__tar.gz

{pyield-0.8.2 → pyield-0.8.4}/PKG-INFO

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

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

pyield-0.8.2/pyield/tn_bonds.py → pyield-0.8.4/pyield/anbima.py

@@ -8,14 +8,16 @@ ANBIMA_NON_MEMBER_URL = "https://www.anbima.com.br/informacoes/merc-sec/arqs/"
 ANBIMA_MEMBER_URL = "http://www.anbima.associados.rtm/merc_sec/arqs/"
 
 
-def _get_anbima_content(reference_date: pd.Timestamp) -> str:
+def _get_file_content(reference_date: pd.Timestamp, headers: dict = None) -> str:
+    headers = headers or {}  # Default empty headers
     url_date = reference_date.strftime("%y%m%d")
     member_url = f"{ANBIMA_MEMBER_URL}ms{url_date}.txt"
+    # Non member url example: https://www.anbima.com.br/informacoes/merc-sec/arqs/ms240614.txt
     non_member_url = f"{ANBIMA_NON_MEMBER_URL}ms{url_date}.txt"
 
     # Tries to access the member URL first
     try:
-        response = requests.get(member_url, timeout=5)
+        response = requests.get(member_url, headers=headers, timeout=5)
         # Checks if the response was successful (status code 200)
         response.raise_for_status()
         return response.text
@@ -33,14 +35,9 @@ def _get_anbima_content(reference_date: pd.Timestamp) -> str:
         return ""
 
 
-def _get_raw_df(reference_date: pd.Timestamp) -> pd.DataFrame:
-    url_content = _get_anbima_content(reference_date)
-    if url_content == "":
-        date_str = reference_date.strftime("%d-%m-%Y")
-        raise ValueError(f"Could not fetch ANBIMA data for {date_str}.")
-
-    df = pd.read_csv(
-        io.StringIO(url_content),
+def _read_raw_df(file_content: str) -> pd.DataFrame:
+    return pd.read_csv(
+        io.StringIO(file_content),
         sep="@",
         encoding="latin-1",
         skiprows=2,
@@ -49,45 +46,41 @@ def _get_raw_df(reference_date: pd.Timestamp) -> pd.DataFrame:
         na_values=["--"],
         dtype_backend="numpy_nullable",
     )
-    return df
 
 
 def _process_raw_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     """
-    Process raw data from ANBIMA by filtering selected columns, renaming them and
-    adjusting data formats.
+    Process raw data from ANBIMA by renaming columns and adjusting data formats.
 
     Parameters:
-    - df (pd.DataFrame): Raw data DataFrame to process.
+        df (pd.DataFrame): Raw DataFrame to process.
 
     Returns:
-    - pd.DataFrame: Processed DataFrame.
+        pd.DataFrame: Processed DataFrame.
     """
     # Filter selected columns and rename them
     selected_columns_dict = {
         "Titulo": "BondType",
         "Data Referencia": "ReferenceDate",
-        # "Codigo SELIC": "SelicCode",
-        # "Data Base/Emissao": "IssueBaseDate",
+        "Codigo SELIC": "SelicCode",
+        "Data Base/Emissao": "IssueBaseDate",
         "Data Vencimento": "MaturityDate",
         "Tx. Compra": "BidRate",
         "Tx. Venda": "AskRate",
         "Tx. Indicativas": "IndicativeRate",
         "PU": "Price",
-        # "Desvio padrao": "StdDev",
-        # "Interv. Ind. Inf. (D0)",
-        # "Interv. Ind. Sup. (D0)",
-        # "Interv. Ind. Inf. (D+1)",
-        # "Interv. Ind. Sup. (D+1)",
-        # "Criterio": "Criteria",
+        "Desvio padrao": "StdDev",
+        "Interv. Ind. Inf. (D0)": "LowerBoundRateD0",
+        "Interv. Ind. Sup. (D0)": "UpperBoundRateD0",
+        "Interv. Ind. Inf. (D+1)": "LowerBoundRateD1",
+        "Interv. Ind. Sup. (D+1)": "UpperBoundRateD1",
+        "Criterio": "Criteria",
     }
-    select_columns = list(selected_columns_dict.keys())
-    df = df_raw[select_columns].copy()
-    df = df.rename(columns=selected_columns_dict)
+    df = df_raw.rename(columns=selected_columns_dict)
 
     # Remove percentage from rates
-    rate_cols = ["BidRate", "AskRate", "IndicativeRate"]
-    df[rate_cols] = df[rate_cols] / 100
+    rate_cols = [col for col in df.columns if "Rate" in col]
+    df[rate_cols] = (df[rate_cols] / 100).round(6)
 
     df["ReferenceDate"] = pd.to_datetime(df["ReferenceDate"], format="%Y%m%d")
     df["MaturityDate"] = pd.to_datetime(df["MaturityDate"], format="%Y%m%d")
@@ -95,31 +88,46 @@ def _process_raw_df(df_raw: pd.DataFrame) -> pd.DataFrame:
     return df.sort_values(["BondType", "MaturityDate"], ignore_index=True)
 
 
-def fetch_bonds(reference_date: pd.Timestamp, return_raw=False) -> pd.DataFrame:
+def fetch_data(reference_date: pd.Timestamp, headers: dict = None) -> pd.DataFrame:
     """
     Fetches indicative treasury rates from ANBIMA for a specified reference date.
 
     This function retrieves the indicative rates for Brazilian treasury securities
     from ANBIMA, processing them into a structured pandas DataFrame.
-    There is an option to return raw data directly from the source without processing.
 
     Parameters:
-        reference_date (str | pd.Timestamp, optional): The date for which to fetch the
-            indicative rates. If None or not provided, the function defaults to the
-            previous business day.
-        return_raw (bool, optional): Flag to return raw data without processing.
-            Defaults to False.
+        reference_date (pd.Timestamp): The date for which to fetch the indicative rates.
 
     Returns:
         pd.DataFrame: A DataFrame containing the processed indicative rates for the
-            given reference date, or raw data if `return_raw` is True. The processed
-            data includes bond type, reference date, maturity date and various rates
-            (bid, ask, indicative) among others, depending on the `return_raw` flag.
+            given reference date.
+
+    """
+    file_content = _get_file_content(reference_date, headers)
+
+    if file_content == "":
+        date_str = reference_date.strftime("%d-%m-%Y")
+        raise ValueError(f"Could not fetch ANBIMA data for {date_str}.")
+
+    df = _read_raw_df(file_content)
+
+    return _process_raw_df(df)
 
+
+def fetch_rates(reference_date: pd.Timestamp, headers: dict = None) -> pd.DataFrame:
     """
-    df = _get_raw_df(reference_date)
+    Fetches indicative treasury rates from ANBIMA for a specified reference date.
+
+    This function retrieves the indicative rates for Brazilian treasury securities
+    from ANBIMA, processing them into a structured pandas DataFrame.
 
-    if not return_raw:
-        df = _process_raw_df(df)
+    Parameters:
+        reference_date (pd.Timestamp): The date for which to fetch the indicative rates.
 
-    return df
+    Returns:
+        pd.DataFrame: A DataFrame containing the processed indicative rates for the
+            given reference date.
+
+    """
+    df = fetch_data(reference_date, headers)
+    return df[["BondType", "MaturityDate", "IndicativeRate"]].copy()

{pyield-0.8.2 → pyield-0.8.4}/pyield/data_access.py

@@ -1,11 +1,11 @@
 import pandas as pd
 
+from . import anbima as an
 from . import date_validator as dv
 from . import futures as ft
 from . import indicators as it
 from . import projections as pr
 from . import spreads as sp
-from . import tn_bonds as tb
 
 
 def fetch_asset(
@@ -17,7 +17,7 @@ def fetch_asset(
     Args:
         asset_code (str): The asset code identifying the type of financial asset.
         Supported options:
-            - "TRB": Treasury bonds (indicative rates from ANBIMA).
+            - "TRB": Brazilian treasury bonds (indicative rates from ANBIMA).
             - "LTN", "LFT", "NTN-F", "NTN-B": Specific types of Brazilian treasury bonds
                   (indicative rates from ANBIMA).
             - "DI1": One-day Interbank Deposit Futures (Futuro de DI) from B3.
@@ -42,7 +42,7 @@ def fetch_asset(
         ValueError: If the asset code is not recognized or supported.
 
     Examples:
-        >>> fetch_asset("TRB", "31-05-2024")
+        >>> fetch_asset("LTN", "31-05-2024")
         >>> fetch_asset("DI1", "31-05-2024")
     """
     SUPPORTED_BONDS = ["LTN", "LFT", "NTN-F", "NTN-B"]
@@ -55,13 +55,13 @@ def fetch_asset(
         return ft.fetch_intraday_df(future_code=asset_code.upper())
 
     if asset_code.upper() == "TRB":
-        return tb.fetch_bonds(reference_date=normalized_date)
+        return an.fetch_data(reference_date=normalized_date)
 
     if asset_code.upper() in SUPPORTED_BONDS:
-        df_bond = tb.fetch_bonds(reference_date=normalized_date)
+        df_bond = an.fetch_data(reference_date=normalized_date)
         df_bond.query(f"BondType == '{asset_code.upper()}'", inplace=True)
-        # Return the DataFrame sorted by maturity date
-        return df_bond.sort_values("MaturityDate", ignore_index=True)
+        # Return the DataFrame with the index reset
+        return df_bond.reset_index(drop=True)
 
     if asset_code.upper() in SUPPORTED_FUTURES:
         return ft.fetch_historical_df(

{pyield-0.8.2 → pyield-0.8.4}/pyield/ntnb.py

@@ -23,7 +23,7 @@ def anbima_data(reference_date: str | pd.Timestamp) -> pd.DataFrame:
     return da.fetch_asset(asset_code="NTN-B", reference_date=reference_date)
 
 
-def anbima_rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
+def ytm_rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
     """
     Fetch NTN-B Anbima indicative rates for the given reference date.
 
@@ -33,10 +33,12 @@ def anbima_rates(reference_date: str | pd.Timestamp) -> pd.DataFrame:
     Returns:
         pd.DataFrame: A DataFrame containing the maturity dates and corresponding rates.
     """
-    return anbima_data(reference_date)[["MaturityDate", "IndicativeRate"]]
+    df = anbima_data(reference_date)[["MaturityDate", "IndicativeRate"]]
+    # Rename IndicativeRate to YTM for consistency
+    return df.rename(columns={"IndicativeRate": "YTM"})
 
 
-def truncate(value, decimal_places):
+def _truncate(value, decimal_places):
     """
     Truncate a float or a Pandas Series to the specified decimal place.
 
@@ -178,16 +180,16 @@ def quotation(
     cf = np.where(payment_dates == maturity_date, FINAL_PMT, INTER_PMT)
 
     # Calculate the number of periods truncated to 14 decimal places
-    n = truncate(bdays / 252, 14)
+    n = _truncate(bdays / 252, 14)
 
     # Calculate the present value of each cash flow (DCF) rounded to 10 decimal places
     dcf = (cf / (1 + discount_rate) ** n).round(10)
 
     # Return the quotation (the dcf sum) truncated to 4 decimal places
-    return truncate(dcf.sum(), 4)
+    return _truncate(dcf.sum(), 4)
 
 
-def prepare_interpolation_data(
+def _prepare_interpolation_data(
     reference_date: pd.Timestamp, maturity_dates: pd.Series, rates: pd.Series
 ) -> tuple:
     """
@@ -242,7 +244,7 @@ def spot_rates(
     settlement_date = dv.normalize_date(settlement_date)
 
     # Prepare the data for interpolation
-    ordered_bdays, ordered_ytms = prepare_interpolation_data(
+    ordered_bdays, ordered_ytms = _prepare_interpolation_data(
         settlement_date, maturity_dates, ytm_rates
     )
     # Generate coupon dates and initialize the main DataFrame
@@ -253,7 +255,7 @@ def spot_rates(
     # Add auxiliary columns for calculations
     df["BDays"] = bday.count_bdays(settlement_date, df["MaturityDate"])
     df["YTM"] = 0.0
-    df["SpotRate"] = 0.0
+    df["RSR"] = 0.0
 
     # Main loop to calculate spot rates
     for index in df.index:
@@ -266,7 +268,7 @@ def spot_rates(
 
         # Create the Series that will be used to calculate the discounted cash flows
         cfs = pd.Series(COUPON, index=dfl.index)
-        spot_rates = dfl["SpotRate"]
+        spot_rates = dfl["RSR"]
         periods = dfl["BDays"] / 252
 
         # Calculate the present value of the cash flows (discounted cash flows)
@@ -279,7 +281,7 @@ def spot_rates(
         spot_rate = ((COUPON + 1) / (ntnb_quotation - dcfs.sum())) ** (252 / bd) - 1
 
         # Update DataFrame with calculated values
-        df.at[index, "SpotRate"] = spot_rate
+        df.at[index, "RSR"] = spot_rate
         df.at[index, "YTM"] = ytm
 
     # Drop the BDays column, remove intermediate cupon dates and reset the index.
@@ -290,7 +292,7 @@ def spot_rates(
     )
 
 
-def _get_nir_df(reference_date: pd.Timestamp) -> pd.DataFrame:
+def _get_nsr_df(reference_date: pd.Timestamp) -> pd.DataFrame:
     """
     Fetch the Nominal Interest Rate (NIR) data for NTN-B bonds.
 
@@ -345,14 +347,14 @@ def _get_nir_df(reference_date: pd.Timestamp) -> pd.DataFrame:
     return df
 
 
-def breakeven_inflation(
+def bei_rates(
     reference_date: str | pd.Timestamp,
     settlement_date: str | pd.Timestamp,
     maturity_dates: pd.Series,
     ytm_rates: pd.Series,
 ) -> pd.DataFrame:
     """
-    Calculate the Breakeven Inflation (INF) for NTN-B bonds based on nominal and real
+    Calculate the Breakeven Inflation (BEI) for NTN-B bonds based on nominal and real
     interest rates.
 
     Args:
@@ -364,45 +366,53 @@ def breakeven_inflation(
             to the maturity dates.
 
     Returns:
-        pd.DataFrame: DataFrame containing the maturity dates, business days to maturity
-            (BDays), Yield to Maturity (YTM), real spot rates (RSR), nominal spot rates
-            (NSR_DI and NSR_PRE), and breakeven inflation rates (INF_DI and INF_PRE).
+        pd.DataFrame: DataFrame containing the breakeven inflation rates.
+
+    Returned columns:
+        - MaturityDate: Maturity date of the bond.
+        - BDays: Number of business days from the settlement date to the maturity.
+        - YTM: Yield to Maturity rate for the bond.
+        - RSR: Real Spot Rate for the bond.
+        - NSR_DI: Nominal Spot Rate for the bond.
+        - NSR_PRE: Nominal Spot Rate for the bond with DI spread.
+        - BIR_DI: Breakeven Inflation Rate for the bond.
+        - BIR_PRE: Breakeven Inflation Rate for the bond adjusted for DI spread.
     """
     # Normalize input dates
     reference_date = dv.normalize_date(reference_date)
     settlement_date = dv.normalize_date(settlement_date)
 
     # Fetch Nominal Spot Rate (NSR) data
-    df_nir = _get_nir_df(reference_date)
-    known_bdays = df_nir["BDaysToExp"].to_list()
-    known_rates = df_nir["NSR_DI"].to_list()
+    df_nsr = _get_nsr_df(reference_date)
+    known_bdays = df_nsr["BDaysToExp"].to_list()
+    known_rates = df_nsr["NSR_DI"].to_list()
 
     # Calculate Real Spot Rate (RSR)
-    df_rir = spot_rates(settlement_date, maturity_dates, ytm_rates)
-    df_rir = df_rir.rename(columns={"SpotRate": "RSR"})
-    df_rir["BDays"] = bday.count_bdays(reference_date, df_rir["MaturityDate"])
-    df_rir["NSR_DI"] = df_rir["BDays"].apply(
+    df = spot_rates(settlement_date, maturity_dates, ytm_rates)
+    df = df.rename(columns={"RSR": "RSR"})
+    df["BDays"] = bday.count_bdays(reference_date, df["MaturityDate"])
+    df["NSR_DI"] = df["BDays"].apply(
         lambda x: ip.find_and_interpolate_flat_forward(x, known_bdays, known_rates)
     )
 
-    # Calculate Breakeven Inflation (INF)
-    df_rir["INF_DI"] = ((df_rir["NSR_DI"] + 1) / (df_rir["RSR"] + 1)) - 1
+    # 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_nir["NSR_PRE"].to_list()
-    df_rir["NSR_PRE"] = df_rir["BDays"].apply(
+    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)
     )
-    df_rir["INF_PRE"] = ((df_rir["NSR_PRE"] + 1) / (df_rir["RSR"] + 1)) - 1
+    df["BIR_PRE"] = ((df["NSR_PRE"] + 1) / (df["RSR"] + 1)) - 1
 
-    order_cols = [
+    cols_reordered = [
         "MaturityDate",
         "BDays",
         "YTM",
         "RSR",
         "NSR_DI",
         "NSR_PRE",
-        "INF_DI",
-        "INF_PRE",
+        "BIR_DI",
+        "BIR_PRE",
     ]
-    return df_rir[order_cols].copy()
+    return df[cols_reordered].copy()

{pyield-0.8.2 → pyield-0.8.4}/pyield/spreads.py

@@ -1,6 +1,6 @@
 import pandas as pd
 
-from . import tn_bonds as tb
+from . import anbima as an
 from .futures import historical as fh
 
 # Constant for conversion to basis points
@@ -38,7 +38,7 @@ def calculate_di_spreads(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 = tb.fetch_bonds(reference_date, False)
+    df_anbima = an.fetch_data(reference_date, False)
     df_anbima.query("BondType in ['LTN', 'NTN-F']", inplace=True)
 
     # Merge bond and DI rates by maturity date to calculate spreads

{pyield-0.8.2 → pyield-0.8.4}/pyproject.toml

@@ -32,7 +32,7 @@ dependencies = [
     "requests>=2.31.0",
 ]
 dynamic = []
-version = "0.8.2"
+version = "0.8.4"
 
 [project.license]
 file = "LICENSE"
@@ -52,6 +52,9 @@ dev = [
     "ipykernel",
     "pytest",
     "mypy",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
 ]
 
 [tool.ruff]

pyield-0.8.2/pyield/__about__.py

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