PYield 0.32.2__tar.gz → 0.32.4__tar.gz

{pyield-0.32.2 → pyield-0.32.4}/PKG-INFO

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

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

{pyield-0.32.2 → pyield-0.32.4}/pyield/__init__.py

@@ -4,7 +4,7 @@ from pyield import anbima, b3, bc, bday, ibge
 from pyield.__about__ import __version__
 from pyield.b3 import futures
 from pyield.b3.di import DIFutures
-from pyield.forward import forwards
+from pyield.fwd import forward, forwards
 from pyield.interpolator import Interpolator
 from pyield.tpf import lft, ltn, ntnb, ntnc, ntnf
 
@@ -14,6 +14,7 @@ __all__ = [
     "bday",
     "DIFutures",
     "forwards",
+    "forward",
     "futures",
     "ibge",
     "Interpolator",

{pyield-0.32.2 → pyield-0.32.4}/pyield/b3/di.py

@@ -5,8 +5,7 @@ from zoneinfo import ZoneInfo
 import pandas as pd
 
 import pyield.date_converter as dc
-import pyield.forward as fw
-from pyield import b3, bday, interpolator
+from pyield import b3, bday, fwd, interpolator
 from pyield.data_cache import get_cached_dataset
 from pyield.date_converter import DateArray, DateScalar
 
@@ -206,9 +205,9 @@ class DIFutures:
         if df.empty:
             return pd.DataFrame()
 
-        df["ForwardRate"] = fw.forwards(
-            business_days=bday.count(df["TradeDate"], df["ExpirationDate"]),
-            zero_rates=df["SettlementRate"],
+        df["ForwardRate"] = fwd.forwards(
+            bdays=bday.count(df["TradeDate"], df["ExpirationDate"]),
+            rates=df["SettlementRate"],
             groupby_dates=df["TradeDate"],
         )
 

{pyield-0.32.2 → pyield-0.32.4}/pyield/conftest.py

@@ -1,3 +1,4 @@
+import pandas
 import pytest
 
 import pyield
@@ -6,6 +7,7 @@ import pyield
 @pytest.fixture(autouse=True)
 def add_np(doctest_namespace):
     doctest_namespace["yd"] = pyield
+    doctest_namespace["pd"] = pandas
 
 
 def pytest_configure(config):

pyield-0.32.4/pyield/fwd.py

@@ -0,0 +1,164 @@
+import pandas as pd
+
+
+def forwards(
+    bdays: pd.Series,
+    rates: pd.Series,
+    groupby_dates: pd.Series | None = None,
+) -> pd.Series:
+    """
+    Calcula taxas a termo (forward rates) a partir de taxas zero (spot rates).
+
+    Utiliza a fórmula:
+        f₁→₂ = ((1 + r₂)^(du₂/252) / (1 + r₁)^(du₁/252))^(252/(du₂ - du₁)) - 1
+
+    Como du/252 = t (tempo em anos úteis), a fórmula pode ser simplificada para:
+        f₁→₂ = ((1 + r₂)^t₂ / (1 + r₁)^t₁)^(1/(t₂ - t₁)) - 1
+
+    Onde:
+        - r₁ é a taxa zero para o vértice anterior.
+        - r₂ é a taxa zero para o vértice atual.
+        - t₁ é o prazo em anos para o vértice anterior (calculado como du₁/252).
+        - t₂ é o prazo em anos para o vértice atual (calculado como du₂/252).
+        - A constante 252 representa o número de dias úteis no ano.
+
+    A primeira taxa a termo de cada sequência (ou grupo) é definida como a
+    taxa zero desse primeiro vértice (f₁→₂ = r₂), dado que não existe um vértice
+    anterior (r₁) para se calcular a taxa a termo do primeiro ponto.
+
+    A função lida internamente com o alinhamento dos índices das Séries de
+    entrada através de `reset_index`. Os cálculos são realizados após ordenar
+    os dados pelos prazos (`bdays`) dentro de cada grupo definido por
+    `groupby_dates` (ou como um único grupo se `groupby_dates` não for
+    fornecido), garantindo a ordem cronológica correta para a fórmula.
+
+    Valores NaN nas taxas ou prazos de entrada resultarão em NaN na saída,
+    exceto para o primeiro ponto de cada grupo, que é tratado separadamente.
+
+    Args:
+        bdays (pd.Series): Número de dias úteis para cada taxa zero.
+        rates (pd.Series): Taxas zero correspondentes aos dias úteis.
+        groupby_dates (pd.Series | None, optional): Critério de agrupamento
+            opcional para segmentar os cálculos (ex: por data de referência).
+            Se None, todos os dados são tratados como um único grupo.
+            Default None.
+
+    Returns:
+        pd.Series: Série contendo as taxas a termo calculadas (tipo Float64).
+            A primeira taxa de cada grupo corresponde à taxa zero inicial.
+
+    Example:
+        >>> bdays = pd.Series([10, 20, 30])
+        >>> rates = pd.Series([0.05, 0.06, 0.07])
+        >>> yd.forwards(bdays, rates)
+        0        0.05
+        1    0.070095
+        2    0.090284
+        dtype: Float64
+    """
+    # Reset Series indexes to avoid misalignment issues during calculations
+    bdays = bdays.reset_index(drop=True).astype("Int64")
+    rates = rates.reset_index(drop=True).astype("Float64")
+    if groupby_dates is not None:
+        groupby_dates = groupby_dates.reset_index(drop=True)
+
+    # Create a DataFrame to work with the given series
+    df = pd.DataFrame({"du2": bdays, "r2": rates})
+    df["t2"] = df["du2"] / 252
+
+    # If no groupby_dates is provided, create a dummy column to group the DataFrame
+    if groupby_dates is not None:
+        df["groupby_date"] = groupby_dates
+    else:
+        df["groupby_date"] = 0  # Dummy value to group the DataFrame
+
+    # Sort by the groupby_dates and t2 columns to ensure proper chronological order
+    df.sort_values(by=["groupby_date", "t2"], inplace=True)
+
+    # Calculate the next zero rate and business day for each group
+    df["r1"] = df.groupby("groupby_date")["r2"].shift(1)
+    df["t1"] = df.groupby("groupby_date")["t2"].shift(1)
+
+    # Calculate the formula components
+    factor_r2 = (1 + df["r2"]) ** df["t2"]  # (1 + r₂)^t₂
+    factor_r1 = (1 + df["r1"]) ** df["t1"]  # (1 + r₁)^t₁
+    time_exp = 1 / (df["t2"] - df["t1"])  # 1/(t₂ - t₁)
+
+    # f₁→₂ = ((1 + r₂)^t₂ / (1 + r₁)^t₁)^(1/(t₂ - t₁)) - 1
+    df["f1_2"] = (factor_r2 / factor_r1) ** time_exp - 1
+
+    # Identifify the first index of each group of dates
+    first_indices = df.groupby("groupby_date").head(1).index
+    # Set the first forward rate of each group to the zero rate
+    df.loc[first_indices, "f1_2"] = df.loc[first_indices, "r2"]
+
+    # Return the forward rates as a Series
+    f1_2 = df["f1_2"]
+    f1_2.name = None
+    return f1_2
+
+
+def forward(
+    bday1: int,
+    bday2: int,
+    rate1: float,
+    rate2: float,
+) -> float:
+    """
+    Calcula a taxa a termo (forward rate) entre dois prazos (dias úteis).
+
+    Utiliza a fórmula:
+        f₁→₂ = ((1 + r₂)^(du₂/252) / (1 + r₁)^(du₁/252))^(252/(du₂ - du₁)) - 1
+
+    Onde:
+        - r₁ é a taxa zero para o primeiro prazo (du₁).
+        - r₂ é a taxa zero para o segundo prazo (du₂).
+        - du₁ é o número de dias úteis até a primeira data.
+        - du₂ é o número de dias úteis até a segunda data.
+        - A constante 252 representa o número de dias úteis no ano.
+
+    Como du/252 = t (tempo em anos úteis), a fórmula pode ser simplificada para:
+        f₁→₂ = ((1 + r₂)^t₂ / (1 + r₁)^t₁)^(1/(t₂ - t₁)) - 1
+
+    Args:
+        bday1 (int): Número de dias úteis do primeiro ponto (prazo menor).
+        bday2 (int): Número de dias úteis do segundo ponto (prazo maior).
+        rate1 (float): Taxa zero (spot rate) para o prazo `bday1`.
+        rate2 (float): Taxa zero (spot rate) para o prazo `bday2`.
+
+    Returns:
+        float: A taxa a termo calculada entre `bday1` e `bday2`. Retorna
+            `float('nan')` se `bday2 <= bday1` ou se qualquer um dos
+            argumentos de entrada for NaN.
+
+    Example:
+        >>> # Exemplo correto: bday2 > bday1
+        >>> yd.forward(10, 20, 0.05, 0.06)
+        0.0700952380952371
+        >>> # Exemplo inválido: bday2 <= bday1
+        >>> yd.forward(20, 10, 0.06, 0.05)
+        nan
+        >>> yd.forward(10, 10, 0.05, 0.05)
+        nan
+        >>> # Exemplo com NaN na entrada
+        >>> yd.forward(10, 20, 0.05, pd.NA)
+        nan
+
+    Note:
+        É fundamental que `bday2` seja estritamente maior que `bday1` para que
+        o cálculo da taxa a termo seja matematicamente válido.
+    """
+    if pd.isna(rate1) or pd.isna(rate2) or pd.isna(bday1) or pd.isna(bday2):
+        # If any of the inputs are NaN, return NaN
+        return float("nan")
+
+    # Handle the case where the two dates are the same
+    if bday2 <= bday1:
+        return float("nan")
+
+    # Convert business days to business years
+    t1 = bday1 / 252
+    t2 = bday2 / 252
+
+    # f₁→₂ = ((1 + r₂)^t₂ / (1 + r₁)^t₁)^(1/(t₂ - t₁)) - 1
+    return ((1 + rate2) ** t2 / (1 + rate1) ** t1) ** (1 / (t2 - t1)) - 1

pyield-0.32.2/pyield/__about__.py

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

pyield-0.32.2/pyield/forward.py

@@ -1,56 +0,0 @@
-import pandas as pd
-
-
-def forwards(
-    business_days: pd.Series,
-    zero_rates: pd.Series,
-    groupby_dates: pd.Series | None = None,
-) -> pd.Series:
-    """Calculates forward rates from zero rates.
-
-    Args:
-        business_days (pd.Series): Number of business days for each zero rate.
-        zero_rates (pd.Series): Zero rates corresponding to the business days.
-        groupby_dates (pd.Series | None, optional): Optional grouping criteria to
-            segment calculations. If not provided, calculations will not be grouped.
-
-    Returns:
-        pd.Series: Series of calculated forward rates with the first rate set to the
-            corresponding zero rate.
-    """
-    # Reset Series indexes to avoid misalignment issues during calculations
-    business_days = business_days.reset_index(drop=True)
-    zero_rates = zero_rates.reset_index(drop=True)
-    if groupby_dates is not None:
-        groupby_dates = groupby_dates.reset_index(drop=True)
-
-    # Create a DataFrame to work with the given series
-    df = pd.DataFrame({"bd": business_days, "zero_rate": zero_rates})
-
-    # If no groupby_dates is provided, create a dummy column to group the DataFrame
-    if groupby_dates is not None:
-        df["groupby_date"] = groupby_dates
-    else:
-        df["groupby_date"] = 0  # Dummy value to group the DataFrame
-
-    # Sort by the groupby_dates and bd columns to ensure proper chronological order
-    df.sort_values(by=["groupby_date", "bd"], inplace=True)
-
-    # Calculate the next zero rate and business day for each group
-    df["next_rate"] = df.groupby("groupby_date")["zero_rate"].shift(1)
-    df["next_bday"] = df.groupby("groupby_date")["bd"].shift(1)
-
-    # Calculate the forward rates using the formula
-    factor1 = (1 + df["next_rate"]) ** (df["next_bday"] / 252)
-    factor2 = (1 + df["zero_rate"]) ** (df["bd"] / 252)
-    factor3 = 252 / (df["next_bday"] - df["bd"])
-    df["fwd_rate"] = (factor1 / factor2) ** factor3 - 1
-
-    # Identifify the first index of each group of dates
-    first_indices = df.groupby("groupby_date").head(1).index
-    # Set the first forward rate of each group to the zero rate
-    df.loc[first_indices, "fwd_rate"] = df.loc[first_indices, "zero_rate"]
-
-    df["fwd_rate"] = df["fwd_rate"].astype("Float64")
-
-    return df["fwd_rate"]