PYield 0.26.0__tar.gz → 0.26.2__tar.gz

{pyield-0.26.0 → pyield-0.26.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PYield
-Version: 0.26.0
+Version: 0.26.2
 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.26.2/pyield/__about__.py

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

{pyield-0.26.0 → pyield-0.26.2}/pyield/__init__.py

@@ -1,26 +1,27 @@
-from pyield import anbima, bday, di, tools
+from pyield import anbima, bday
 from pyield.__about__ import __version__
 from pyield.b3_futures import futures
-from pyield.di import DIFutures
+from pyield.b3_futures.di import DIFutures
+from pyield.ima import ima
 from pyield.indicators import indicator
 from pyield.interpolator import Interpolator
 from pyield.projections import projection
+from pyield.tools import forward_rates
 from pyield.tpf import lft, ltn, ntnb, ntnf
 
 __all__ = [
     "__version__",
     "anbima",
     "bday",
+    "DIFutures",
+    "forward_rates",
     "futures",
+    "ima",
     "indicator",
+    "Interpolator",
+    "lft",
+    "ltn",
     "ntnb",
     "ntnf",
-    "ltn",
-    "lft",
-    "DIFutures",
     "projection",
-    "Interpolator",
-    "tools",
-    "di",
-    "DIFutures",
 ]

pyield-0.26.2/pyield/bc/auction.py

@@ -0,0 +1,308 @@
+"""
+Documentação da API do BC
+https://olinda.bcb.gov.br/olinda/servico/leiloes_selic/versao/v1/aplicacao#!/recursos/leiloesTitulosPublicos#eyJmb3JtdWxhcmlvIjp7IiRmb3JtYXQiOiJqc29uIiwiJHRvcCI6MTAwfX0=
+"""
+
+import io
+import logging
+from typing import Literal
+
+import pandas as pd
+import requests
+
+import pyield as yd
+from pyield import date_converter as dc
+from pyield.date_converter import DateScalar
+from pyield.tpf.ntnb import duration as duration_b
+from pyield.tpf.ntnf import duration as duration_f
+
+"""Dicionário com o mapeamento das colunas da API do BC para o DataFrame final
+Chaves com comentário serão descartadas ao final do processamento
+A ordem das chaves será a ordem das colunas no DataFrame final
+FR = First Round and SR = Second Round
+"""
+COLUMN_MAPPING = {
+    # "id": "ID",
+    "dataMovimento": "Date",
+    "dataLiquidacao": "Settlement",
+    "tipoOferta": "AuctionType",  # ['Venda', 'Compra', 'Tomador']
+    # "ofertante": "Ofertante",  # ['Tesouro Nacional', 'Banco Central']
+    "edital": "Ordinance",
+    "tipoPublico": "Buyer",  # ['TodoMercado', 'SomenteDealerApto', 'SomenteDealer']
+    # "prazo": "...", # N. de DC entre a data de liquidação e a data de vencimento
+    "codigoTitulo": "SelicCode",  # [100000, 210100, 450000, 760199, 950199]
+    "dataVencimento": "Maturity",
+    "financeiro": "TotalValue",  # = FR + SR (in millions)
+    "quantidadeOfertada": "OfferedQuantity",
+    "quantidadeAceita": "AcceptedQuantity",
+    "quantidadeOfertadaSegundaRodada": "OfferedQuantitySR",
+    "quantidadeAceitaSegundaRodada": "AcceptedQuantitySR",
+    "cotacaoMedia": "AvgPrice",
+    "cotacaoCorte": "CutPrice",
+    "taxaMedia": "AvgRate",
+    "taxaCorte": "CutRate",
+}
+
+
+def _load_from_url(url: str) -> pd.DataFrame:
+    response = requests.get(url, timeout=10)
+    response.raise_for_status()
+    return pd.read_csv(
+        io.StringIO(response.text),
+        dtype_backend="numpy_nullable",
+        decimal=",",
+        date_format="%Y-%m-%d %H:%M:%S",
+        parse_dates=["dataMovimento", "dataLiquidacao", "dataVencimento"],
+    )
+
+
+def _pre_process_df(df: pd.DataFrame) -> pd.DataFrame:
+    # Only Tesouro Nacional auctions are considered
+    df = df.query("ofertante == 'Tesouro Nacional'").reset_index(drop=True)
+
+    # Remover colunas que não serão utilizadas
+    keep_columns = [col for col in COLUMN_MAPPING.keys() if col in df.columns]
+    return df[keep_columns].rename(columns=COLUMN_MAPPING)
+
+
+def _process_df(df: pd.DataFrame) -> pd.DataFrame:
+    # Second Round (SR) columns can be null -> remove nulls to avoid propagation
+    df["AcceptedQuantitySR"] = df["AcceptedQuantitySR"].fillna(0)
+    df["OfferedQuantitySR"] = df["OfferedQuantitySR"].fillna(0)
+
+    # Calcular o financeiro só do leilão
+    total_accepted_quantity = df["AcceptedQuantity"] + df["AcceptedQuantitySR"]
+    first_round_ratio = df["AcceptedQuantity"] / total_accepted_quantity
+    first_round_ratio = df["AcceptedQuantity"] / total_accepted_quantity
+    first_round_ratio = first_round_ratio.where(df["AcceptedQuantity"] != 0, 0)
+    # O dado do financeiro do BC está em milhões com uma casa decimal de precisão
+    # Portanto, podemos converter para inteiro sem perda de informação
+    df["Value"] = (first_round_ratio * df["TotalValue"]).round(1)
+    df["Value"] = (first_round_ratio * df["TotalValue"]).round(1)
+    df["Value"] = (df["Value"] * 1_000_000).astype("Int64")
+
+    # Calcular o financeiro só da SV
+    second_round_ratio = df["AcceptedQuantitySR"] / total_accepted_quantity
+    second_round_ratio = second_round_ratio.where(df["AcceptedQuantitySR"] != 0, 0)
+    df["ValueSR"] = (second_round_ratio * df["TotalValue"]).round(1)
+    df["ValueSR"] = (df["ValueSR"] * 1_000_000).astype("Int64")
+
+    bond_mappping = {
+        100000: "LTN",
+        210100: "LFT",
+        # 450000: "..." # Foi um título ofertado pelo BC em 2009/2010
+        760199: "NTN-B",
+        950199: "NTN-F",
+    }
+    df["BondType"] = df["SelicCode"].map(bond_mappping).astype("string")
+
+    # Em 11/06/2024 o BC passou a informar nas colunas de cotacao os valores dos PUs
+    # Isso afeta somente os títulos LFT e NTN-B
+    change_Date = pd.Timestamp("2024-06-11")
+    adjusted_price = (df["Value"] / df["AcceptedQuantity"]).round(6)
+    is_after_change_Date = df["Date"] >= change_Date
+    is_ltn_or_ntnf = df["BondType"].isin(["LTN", "NTN-F"])
+    keep_avg_price = is_after_change_Date | is_ltn_or_ntnf
+    df["AvgPrice"] = df["AvgPrice"].where(keep_avg_price, adjusted_price)
+
+    return df
+
+
+def _adjust_null_values(df: pd.DataFrame) -> pd.DataFrame:
+    # Onde não há quantidade aceita, não há nem taxa e nem PU definidos.
+    is_accepted = df["AcceptedQuantity"] != 0
+    df["AvgRate"] = df["AvgRate"].where(is_accepted, pd.NA)
+    df["CutRate"] = df["CutRate"].where(is_accepted, pd.NA)
+    df["AvgPrice"] = df["AvgPrice"].where(is_accepted, pd.NA)
+    df["CutPrice"] = df["CutPrice"].where(is_accepted, pd.NA)
+
+    return df
+
+
+def _add_dv01(df: pd.DataFrame) -> pd.DataFrame:
+    df["BDToMat"] = yd.bday.count(start=df["Date"], end=df["Maturity"])
+
+    is_accepted = df["AcceptedQuantity"] != 0  # noqa
+    df_not_accepted = df.query("~@is_accepted").reset_index(drop=True)
+    df_is_accepted = df.query("@is_accepted").reset_index(drop=True)
+
+    df_lft = df_is_accepted.query("BondType == 'LFT'").reset_index(drop=True)
+
+    df_ltn = df_is_accepted.query("BondType == 'LTN'").reset_index(drop=True)
+    if not df_ltn.empty:
+        df_ltn["Duration"] = df_ltn["BDToMat"] / 252
+        df_ltn["MDuration"] = df_ltn["Duration"] / (1 + df_ltn["AvgRate"] / 100)
+        df_ltn["DV01"] = 0.0001 * df_ltn["MDuration"] * df_ltn["AvgPrice"]
+
+    def compute_f_duration(row):
+        return duration_f(row["Date"], row["Maturity"], row["CutRate"] / 100)
+
+    df_ntnf = df_is_accepted.query("BondType == 'NTN-F'").reset_index(drop=True)
+    if not df_ntnf.empty:
+        df_ntnf["Duration"] = df_ntnf.apply(compute_f_duration, axis=1)
+        df_ntnf["Duration"] = df_ntnf["Duration"].astype("Float64")
+        df_ntnf["MDuration"] = df_ntnf["Duration"] / (1 + df_ntnf["AvgRate"] / 100)
+        df_ntnf["DV01"] = 0.0001 * df_ntnf["MDuration"] * df_ntnf["AvgPrice"]
+
+    def compute_b_duration(row):
+        return duration_b(row["Date"], row["Maturity"], row["CutRate"] / 100)
+
+    df_ntnb = df_is_accepted.query("BondType == 'NTN-B'").reset_index(drop=True)
+    if not df_ntnb.empty:
+        df_ntnb["Duration"] = df_ntnb.apply(compute_b_duration, axis=1)
+        df_ntnb["Duration"] = df_ntnb["Duration"].astype("Float64")
+        df_ntnb["MDuration"] = df_ntnb["Duration"] / (1 + df_ntnb["AvgRate"] / 100)
+        df_ntnb["DV01"] = 0.0001 * df_ntnb["MDuration"] * df_ntnb["AvgPrice"]
+
+    df = pd.concat([df_not_accepted, df_lft, df_ltn, df_ntnf, df_ntnb])
+
+    df["DV01"] *= df["AcceptedQuantity"]
+    df["DV01"] = df["DV01"].round(0).astype("Int64")
+
+    return df
+
+
+def _filter_auction_by_type(
+    df: pd.DataFrame, auction_type: Literal["Sell", "Buy"]
+) -> pd.DataFrame:
+    auction_type_mapping = {"Venda": "Sell", "Compra": "Buy"}
+    auction_type = auction_type_mapping.get(auction_type)
+    if auction_type:
+        df = df.query(f"AuctionType == '{auction_type}'").reset_index(drop=True)
+    return df
+
+
+def _sort_and_reorder_columns(df: pd.DataFrame) -> pd.DataFrame:
+    column_sequence = [
+        "Date",
+        "Settlement",
+        "AuctionType",
+        "Ordinance",
+        "Buyer",
+        "BondType",
+        "Maturity",
+        "SelicCode",
+        "TotalValue",
+        "Value",
+        "ValueSR",
+        "OfferedQuantity",
+        "OfferedQuantitySR",
+        "AcceptedQuantity",
+        "AcceptedQuantitySR",
+        "AvgPrice",
+        "CutPrice",
+        "AvgRate",
+        "CutRate",
+        "BDToMat",
+        "Duration",
+        "MDuration",
+        "DV01",
+    ]
+
+    primary_sort_keys = ["Date", "AuctionType", "BondType", "Maturity"]
+    return df[column_sequence].sort_values(by=primary_sort_keys).reset_index(drop=True)
+
+
+def _fetch_df_from_url(
+    url: str,
+    auction_type: Literal["Sell", "Buy"] = None,
+) -> pd.DataFrame:
+    try:
+        df = _load_from_url(url)
+        df = _pre_process_df(df)
+        df = _adjust_null_values(df)
+        df = _process_df(df)
+        df = _add_dv01(df)
+        df = _filter_auction_by_type(df, auction_type)
+        df = _sort_and_reorder_columns(df)
+        return df
+    except Exception as e:
+        logging.error(f"Error on fetching auction data from BC: {e}")
+        return pd.DataFrame()
+
+
+def get_all_auctions() -> pd.DataFrame:
+    """
+    Retrieves a DataFrame containing all public auction data from the BC.
+
+    This function fetches the complete series of public auctions conducted by the
+    National Treasury via the BC API and processes it to a standardized DataFrame.
+
+    Returns:
+        pd.DataFrame: A DataFrame sorted by Date, AuctionType, BondType, and Maturity
+            containing auction data. In case of an error during data retrieval, an empty
+            DataFrame is returned and an error message is logged.
+    """
+    # URL com toda a série de leilões de títulos públicos do Tesouro Nacional
+    url = "https://olinda.bcb.gov.br/olinda/servico/leiloes_selic/versao/v1/odata/leiloesTitulosPublicos(dataMovimentoInicio=@dataMovimentoInicio,dataMovimentoFim=@dataMovimentoFim,dataLiquidacao=@dataLiquidacao,codigoTitulo=@codigoTitulo,dataVencimento=@dataVencimento,edital=@edital,tipoPublico=@tipoPublico,tipoOferta=@tipoOferta)?$format=text/csv"
+    return _fetch_df_from_url(url)
+
+
+def auctions(
+    start: DateScalar,
+    end: DateScalar | None = None,
+    auction_type: Literal["Sell", "Buy"] = None,
+) -> pd.DataFrame:
+    """
+    Retrieves auction data for a given date range and auction type.
+
+    It fetches auction data from the BC API for the specified start and end dates.
+    If the end date is not provided, it defaults to the start date.
+    The resulting data is then filtered by the specified auction type ("Sell" or "Buy").
+    "Sell" auctions are those where the National Treasury sells bonds to the market.
+    "Buy" auctions are those where the National Treasury buys bonds from the market.
+
+    Args:
+        start (DateScalar): The start date for the auction data query.
+        end (DateScalar | None, optional): The end date for the auction data query.
+            If None, the start date is used. Defaults to None.
+        auction_type (Literal["Sell", "Buy"], optional): The type of auction to filter
+            by. Defaults to "Sell".
+
+    Returns:
+        pd.DataFrame: A DataFrame containing auction data for the specified date range
+            and auction type. In case of an error during data retrieval, an empty
+            DataFrame is returned and an error message is logged.
+
+    Notes:
+        FR = First Round
+        SR = Second Round
+
+        The DataFrame has the following columns:
+            - Date: Date of the auction.
+            - Settlement: Settlement date of the auction.
+            - AuctionType: Type of auction (e.g., "Sell" or "Buy").
+            - Ordinance: Normative ordinance associated with the auction.
+            - Buyer: Buyer category (e.g., "TodoMercado", "SomenteDealerApto").
+            - BondType: Category of the bond (e.g., "LTN", "LFT", "NTN-B", "NTN-F").
+            - Maturity: Bond maturity date.
+            - SelicCode: Bond code in the Selic system.
+            - TotalValue: Total value of the auction: FR + SR.
+            - Value: First round (FR) value of the auction.
+            - ValueSR: Value in the second round.
+            - OfferedQuantity: Quantity offered in the auction.
+            - OfferedQuantitySR: Quantity offered in the second round.
+            - AcceptedQuantity: Quantity accepted in the auction.
+            - AcceptedQuantitySR: Quantity accepted in the second round.
+            - AvgPrice: Average price in the auction.
+            - CutPrice: Cut-off price.
+            - AvgRate: Average interest rate.
+            - CutRate: Cut-off rate.
+            - BDToMat: Business days to maturity.
+            - Duration: Duration of the bond.
+            - MDuration: Modified duration of the bond.
+            - DV01: Dollar value of a 1 bp change in yield.
+
+    """
+
+    start = dc.convert_input_dates(start)
+    if end:
+        end = dc.convert_input_dates(end)
+    else:
+        end = start
+
+    start_str = start.strftime("%Y-%m-%d")
+    end_str = end.strftime("%Y-%m-%d")
+    url = f"https://olinda.bcb.gov.br/olinda/servico/leiloes_selic/versao/v1/odata/leiloesTitulosPublicos(dataMovimentoInicio=@dataMovimentoInicio,dataMovimentoFim=@dataMovimentoFim,dataLiquidacao=@dataLiquidacao,codigoTitulo=@codigoTitulo,dataVencimento=@dataVencimento,edital=@edital,tipoPublico=@tipoPublico,tipoOferta=@tipoOferta)?@dataMovimentoInicio='{start_str}'&@dataMovimentoFim='{end_str}'&$format=text/csv"
+
+    return _fetch_df_from_url(url, auction_type)

pyield-0.26.2/pyield/ima.py

@@ -0,0 +1,143 @@
+import io
+import logging
+import re
+import warnings
+
+import pandas as pd
+import requests
+from bs4 import XMLParsedAsHTMLWarning
+
+from pyield import date_converter as dc
+from pyield.date_converter import DateScalar
+
+IMA_URL = "https://www.anbima.com.br/informacoes/ima/ima-quantidade-mercado.asp"
+COLUMN_MAPPING = {
+    "Data Referência": "Date",
+    "Título": "BondType",
+    "Data de Vencimento": "Maturity",
+    "Codigo Selic": "SelicCode",
+    "Código ISIN": "ISIN",
+    "PU (R$)": "Price",
+    "Quantidade em Mercado (1.000 Títulos)": "MarketQuantity",
+    "Valor de Mercado (R$ Mil)": "MarketValue",
+    "Variação da Quantidade (1.000 Títulos)": "QuantityVariation",
+    "Status do Titulo": "BondStatus",
+}
+
+
+def _fetch_url_tables(target_date: pd.Timestamp) -> pd.DataFrame:
+    # Warning supression for BeautifulSoup, as the text is valid HTML and not XML
+    warnings.filterwarnings("ignore", category=XMLParsedAsHTMLWarning)
+
+    target_date_str = target_date.strftime("%d/%m/%Y")
+    payload = {
+        "Tipo": "",
+        "DataRef": "",
+        "Pai": "ima",
+        "Dt_Ref_Ver": "20250117",
+        "Dt_Ref": f"{target_date_str}",
+    }
+
+    r = requests.post(IMA_URL, data=payload, timeout=10)
+    r.raise_for_status()
+    r.encoding = "iso-8859-1"
+    if "Não há dados disponíveis" in r.text:
+        logging.warning("No data found. Returning empty DataFrame.")
+        return pd.DataFrame()
+
+    string_io_buffer = io.StringIO(r.text)
+
+    dfs = pd.read_html(
+        string_io_buffer,
+        flavor="html5lib",
+        attrs={"width": "100%"},
+        header=0,
+        thousands=".",
+        decimal=",",
+        displayed_only=True,
+        dtype_backend="numpy_nullable",
+    )
+
+    df = (
+        pd.concat(dfs)
+        .query("`Data de Vencimento`.notnull()")
+        .query("Título!='Título'")
+        .drop_duplicates(subset="Código ISIN")
+        .reset_index(drop=True)
+    )
+
+    # Convert to CSV and then back to pandas to get automatic type conversion
+    csv_buffer = io.StringIO(df.to_csv(index=False))
+    df = pd.read_csv(csv_buffer, dtype_backend="numpy_nullable")
+
+    # Expressão regular para datas no formato dd/mm/ano
+    date_pattern = r"\b(\d{2}/\d{2}/\d{4})\b"
+
+    # Busca pela primeira data
+    match = re.search(date_pattern, r.text)
+
+    if match:
+        anbima_date_str = match.group(1)
+        anbima_date = pd.to_datetime(anbima_date_str, format="%d/%m/%Y")
+    else:
+        logging.warning("No date found. Returning empty DataFrame.")
+        return pd.DataFrame()
+
+    df["Data Referência"] = anbima_date
+
+    return df
+
+
+def _process_df(df: pd.DataFrame) -> pd.DataFrame:
+    df = df.rename(columns=COLUMN_MAPPING)[COLUMN_MAPPING.values()]
+    df["Maturity"] = pd.to_datetime(df["Maturity"], format="%d/%m/%Y")
+    # Converter a valores para inteiros
+    df["MarketQuantity"] = (1000 * df["MarketQuantity"]).astype("Int64")
+    df["MarketValue"] = (1000 * df["MarketValue"]).astype("Int64")
+    df["QuantityVariation"] = (1000 * df["QuantityVariation"]).astype("Int64")
+
+    return df
+
+
+def ima(date: DateScalar) -> pd.DataFrame:
+    """
+    Fetch and process IMA market data for a given date.
+
+    This function retrieves IMA market data for the specified date from ANBIMA,
+    processes the data into a structured DataFrame, and returns the resulting DataFrame.
+    It handles conversion of date formats, renames columns to English, and converts
+    certain numeric columns to integer types. In the event of an error during data
+    fetching or processing, an empty DataFrame is returned.
+
+    Args:
+        date (DateScalar): A date-like object representing the target date for fetching
+            the data.
+
+    Returns:
+        pd.DataFrame: A DataFrame containing the IMA data with the following columns:
+            - Date: Reference date of the data.
+            - BondType: Type of bond.
+            - Maturity: Bond maturity date.
+            - SelicCode: Code representing the SELIC rate.
+            - ISIN: International Securities Identification Number.
+            - Price: Bond price.
+            - MarketQuantity: Market quantity (in units of 1000 bonds).
+            - MarketValue: Market value (in units of 1000 reais).
+            - QuantityVariation: Variation in quantity (in units of 1000 bonds).
+            - BondStatus: Status of the bond.
+
+    Raises:
+        Exception: Logs error and returns an empty DataFrame if any error occurs during
+            fetching or processing.
+
+    """
+    try:
+        date = dc.convert_input_dates(date)
+        df = _fetch_url_tables(date)
+        df = _process_df(df)
+        return df
+    except Exception as e:
+        date_str = date.strftime("%d/%m/%Y")
+        logging.error(f"Error fetching IMA for {date_str}. Returning empty DataFrame.")
+        logging.error(f"Error message: {e}", exc_info=True)
+        return pd.DataFrame()

{pyield-0.26.0 → pyield-0.26.2}/pyield/tpf/ltn.py

@@ -1,7 +1,8 @@
 import pandas as pd
 
-from pyield import anbima, bday, di
+from pyield import anbima, bday
 from pyield import date_converter as dc
+from pyield.b3_futures import di
 from pyield.date_converter import DateScalar
 from pyield.tpf import tools as tt
 

{pyield-0.26.0 → pyield-0.26.2}/pyield/tpf/ntnf.py

@@ -3,9 +3,10 @@ from collections.abc import Callable
 import numpy as np
 import pandas as pd
 
-from pyield import anbima, bday, data_cache, di
+from pyield import anbima, bday, data_cache
 from pyield import date_converter as dc
 from pyield import interpolator as ip
+from pyield.b3_futures import di
 from pyield.date_converter import DateScalar
 from pyield.tpf import tools as tt
 

{pyield-0.26.0 → pyield-0.26.2}/pyield/tpf/tools.py

@@ -5,8 +5,8 @@ import pandas as pd
 
 from pyield import anbima
 from pyield import date_converter as dc
+from pyield.b3_futures.di import DIFutures
 from pyield.date_converter import DateScalar
-from pyield.di import DIFutures
 
 
 @overload

pyield-0.26.0/pyield/__about__.py

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