PYield 0.32.2__tar.gz → 0.32.3__tar.gz

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

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

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

{pyield-0.32.2 → pyield-0.32.3}/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.3}/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.3/pyield/fwd.py

@@ -0,0 +1,120 @@
+import pandas as pd
+
+
+def forwards(
+    bdays: pd.Series,
+    rates: pd.Series,
+    groupby_dates: pd.Series | None = None,
+) -> pd.Series:
+    """
+    Calculates forward rates from zero rates using the formula:
+        f₁→₂ = ((1 + r₂)^(du₂/252) / (1 + r₁)^(du₁/252))^(252/(du₂ - du₁)) - 1
+
+    Since du/252 = t, the formula can be simplified to:
+        f₁→₂ = ((1 + r₂)^t₂ / (1 + r₁)^t₁)^(1/(t₂ - t₁)) - 1
+
+    where:
+        - r₁ is the zero rate for the previous period
+        - r₂ is the zero rate for the current period
+        - t₁ is the time in years for the previous period
+        - t₂ is the time in years for the current period
+
+    The first forward rate is set to the corresponding zero rate.
+    This function can also handle grouping of the input data based on the
+    `groupby_dates` parameter. If provided, the calculations will be performed
+    separately for each group, allowing for different forward rate calculations
+    based on the grouping criteria.
+
+    Args:
+        bdays (pd.Series): Number of business days for each zero rate.
+        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
+    bdays = bdays.reset_index(drop=True)
+    rates = 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({"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 bd columns to ensure proper chronological order
+    df.sort_values(by=["groupby_date", "t2"], inplace=True)
+
+    # GetCalculate 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 converting to Float64 to handle NaN values
+    return df["f1_2"].astype("Float64")
+
+
+def forward(
+    bday1: int,
+    bday2: int,
+    rate1: float,
+    rate2: float,
+) -> float:
+    """
+    Calculates the forward rate between two business days using the formula:
+        f₁→₂ = ((1 + r₂)^(du₂/252) / (1 + r₁)^(du₁/252))^(252/(du₂ - du₁)) - 1
+
+    where:
+        - r₁ is the zero rate for the previous period
+        - r₂ is the zero rate for the current period
+        - du₁ is the number of business days until the first date
+        - du₂ is the number of business days until the second date
+
+    Args:
+        bday1 (int): Number of business days until the first date.
+        bday2 (int): Number of business days until the second date.
+        rate1 (float): Zero rate for the first date.
+        rate2 (float): Zero rate for the second date.
+
+    Returns:
+        float: The calculated forward rate.
+
+    Example:
+        >>> forward(10, 20, 0.05, 0.06)
+        0.0700952380952371
+    """
+    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 bday1 == bday2:
+        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"]