PYield 0.35.0__tar.gz → 0.35.2__tar.gz

{pyield-0.35.0 → pyield-0.35.2}/PKG-INFO

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

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

{pyield-0.35.0 → pyield-0.35.2}/pyield/b3/di1.py

@@ -15,7 +15,7 @@ TIMEZONE_BZ = ZoneInfo("America/Sao_Paulo")
 
 
 def data(
-    date: DateScalar,
+    dates: DateScalar | DateArray,
     month_start: bool = False,
     pre_filter: bool = False,
     all_columns: bool = True,
@@ -27,9 +27,7 @@ def data(
     (to month start) and optional filtering based on LTN and NTN-F bond maturities.
 
     Args:
-        date (DateScalar): The trade date for which to retrieve DI contract data.
-            If the date is invalid, a holiday, in the future, or None, an empty
-            DataFrame is returned with appropriate logging.
+        dates (DateScalar): The trade dates for which to retrieve DI contract data.
         month_start (bool, optional): If True, adjusts all expiration dates to the
             first day of their respective month (e.g., 2025-02-01 becomes
             2025-01-01). Defaults to False.
@@ -43,12 +41,12 @@ def data(
 
     Returns:
         pd.DataFrame: A DataFrame containing the DI futures contract data for the
-            specified date, sorted by expiration date. Returns an empty DataFrame
-            if no data is found, the date is invalid, a holiday, or in the future.
+            specified dates, sorted by trade dates and expiration dates.
+            Returns an empty DataFrame if no data is found
 
     Examples:
         >>> from pyield import di1
-        >>> df = di1.data(date="16-10-2024", month_start=True)
+        >>> df = di1.data(dates="16-10-2024", month_start=True)
         >>> df.iloc[:5, :5]  # Show the first five rows and columns
            TradeDate ExpirationDate TickerSymbol  BDaysToExp  OpenContracts
         0 2024-10-16     2024-11-01       DI1X24          12        1744269
@@ -57,31 +55,24 @@ def data(
         3 2024-10-16     2025-02-01       DI1G25          74         279491
         4 2024-10-16     2025-03-01       DI1H25          94         344056
     """
-    if date:
-        date = dc.convert_input_dates(date)
-        bz_today = dt.now(TIMEZONE_BZ).date()
-        if date.date() > bz_today:
-            logger.warning(f"DI date ({date}) after current date {bz_today}")
-            logger.warning("Returning empty DataFrame.")
-            return pd.DataFrame()
-    else:
-        logger.info("No date specified. Returning empty DataFrame.")
-        return pd.DataFrame()
-    # Return an empty DataFrame if the trade date is a holiday
-    if not bday.is_business_day(date):
-        logger.warning("Specified date is not a business day.")
-        logger.warning("Returning empty DataFrame.")
-        return pd.DataFrame()
+    dates = dc.convert_input_dates(dates)
+    # Force dates to be a Series for consistency
+    dates = pd.Series(dates) if isinstance(dates, pd.Timestamp) else dates
+    # Remove duplicates and sort dates
+    dates = dates.drop_duplicates().sort_values().reset_index(drop=True)
 
-    # Get historical data
-    df = get_cached_dataset("DI").query("TradeDate == @date").reset_index(drop=True)
+    df = get_cached_dataset("DI").query("TradeDate in @dates").reset_index(drop=True)
 
-    if df.empty:
-        logger.info("No historical data found. Trying real-time data.")
-        df = b3.futures(contract_code="DI1", date=date)
+    today = dt.now(TIMEZONE_BZ)
+    last_bday = bday.last_business_day()
+    is_trading_day = today.date() == last_bday.date()
+    if is_trading_day and last_bday in df["TradeDate"]:
+        logger.info("Trying to get DI Futures data for today.")
+        df_intraday = b3.futures(contract_code="DI1", date=last_bday)
+        df = pd.concat([df, df_intraday]).reset_index(drop=True)
 
     if df.empty:
-        logger.warning("No DI Futures data found for the specified date.")
+        logger.warning("No DI Futures data found for the specified dates.")
         logger.warning("Returning empty DataFrame.")
         return pd.DataFrame()
 
@@ -92,24 +83,37 @@ def data(
         df_pre = (
             get_cached_dataset("TPF")
             .query("BondType in ['LTN', 'NTN-F']")
-            .reset_index(drop=True)[["ReferenceDate", "MaturityDate"]]
+            .drop_duplicates(subset=["ReferenceDate", "MaturityDate"])
+            .sort_values(["ReferenceDate", "MaturityDate"])
+            .reset_index(drop=True)[["ReferenceDate", "MaturityDate", "BondType"]]
         )
+        # Assure that the MaturityDate is a business day
+        df_pre["MaturityDate"] = bday.offset(df_pre["MaturityDate"], 0)
 
-        nearest_date = _find_nearest_date(date, df_pre["ReferenceDate"])
-        if nearest_date is pd.NaT:
-            logger.warning("No matching reference date found in TPF dataset.")
-            return pd.DataFrame()
+        # Rename columns for merging
+        df_pre = df_pre.rename(
+            columns={"ReferenceDate": "TradeDate", "MaturityDate": "ExpirationDate"}
+        )
+        # merge_asof will be used to filter the most recent LTN and NTN-F
+        # maturities for the given trade date. Therefore, the intraday data
+        # will use LTN and NTN-F maturities from the previous day.
+        df = pd.merge_asof(
+            df, df_pre, on="TradeDate", by="ExpirationDate", direction="backward"
+        )
 
-        # Filter the TPF dataset for the nearest reference date
-        pre_maturities = (
-            df_pre.query("ReferenceDate == @nearest_date")["MaturityDate"]
-            .drop_duplicates()
+        # BondType was used as flag to filter the maturities
+        df = (
+            df.query("BondType.notna()")
+            .drop(columns=["BondType"])
             .reset_index(drop=True)
         )
 
-        # Force the expirations to be a business day as DI contracts
-        pre_maturities = bday.offset(pre_maturities, 0)
-        df = df.query("ExpirationDate in @pre_maturities").reset_index(drop=True)
+        if df.empty:
+            logger.warning(
+                "No DI Futures data found for the specified dates after pre-filtering."
+                "Returning empty DataFrame."
+            )
+            return pd.DataFrame()
 
     if month_start:
         df["ExpirationDate"] = df["ExpirationDate"].dt.to_period("M").dt.to_timestamp()
@@ -139,33 +143,6 @@ def data(
     return df.sort_values(by=["TradeDate", "ExpirationDate"]).reset_index(drop=True)
 
 
-def _find_nearest_date(
-    target_date: pd.Timestamp, date_series: pd.Series
-) -> pd.Timestamp:
-    """Finds the date in a Series closest to the target date.
-
-    Args:
-        target_date (pd.Timestamp): The reference date.
-        date_series (pd.Series): A Series of dates to search within.
-
-    Returns:
-        pd.Timestamp: The date from `date_series` that is closest in time
-            to `target_date`. Returns pd.NaT if the series is empty or
-            target_date is None.
-    """
-    if date_series.empty or target_date is None:
-        return pd.NaT
-    # The result will be a Series of positive Timedeltas (durations)
-    abs_differences = (date_series - target_date).abs()
-
-    # Find the index of the minimum difference in the differences Series
-    # idxmin() returns the index label where the minimum value occurs
-    closest_index = abs_differences.idxmin()
-
-    # Use the found index to get the corresponding date from the original Series
-    return date_series.loc[closest_index]  # or date_series[closest_index]
-
-
 def interpolate_rates(
     dates: DateScalar | DateArray,
     expirations: DateScalar | DateArray,
@@ -174,7 +151,7 @@ def interpolate_rates(
     """
     Interpolates DI rates for specified trade dates and expiration dates.
 
-    Calculates interpolated DI rates using the flat-forward method for given
+    Calculates interpolated DI rates using the **flat-forward** method for given
     sets of trade dates and expiration dates. This function is well-suited
     for vectorized calculations across multiple date pairs.
 
@@ -199,6 +176,52 @@ def interpolate_rates(
     Raises:
         ValueError: If `dates` and `expirations` are both array-like but have
             different lengths.
+
+    Examples:
+        >>> from pyield import di1
+        >>> # Note: by default, pandas shows floats with 6 decimal places
+        >>> # Interpolate rates for multiple trade and expiration dates
+        >>> # There is a contract with expiration 01-01-2027 in 08-05-2025
+        >>> # The rate is not interpolated (settlement rate is used)
+        >>> # There is no contract with expiration 25-11-2027 in 09-05-2025
+        >>> # The rate is interpolated (flat-forward method)
+        >>> # There is no data for trade date 10-05-2025 (Saturday) -> NaN
+        >>> # Note: 0.13461282461562996 is shown as 0.134613
+        >>> di1.interpolate_rates(
+        ...     dates=["08-05-2025", "09-05-2025", "10-05-2025"],
+        ...     expirations=["01-01-2027", "25-11-2027", "01-01-2030"],
+        ... )
+        0    0.13972
+        1    0.134613
+        2    <NA>
+        dtype: Float64
+
+        >>> # Interpolate rates for a single trade date and multiple expiration dates
+        >>> # There is no DI Contract in 09-05-2025 with expiration 01-01-2050
+        >>> # The longest available contract is used to extrapolate the rate
+        >>> # Note: extrapolation is allowed by default
+        >>> di1.interpolate_rates(
+        ...     dates="25-04-2025",
+        ...     expirations=["01-01-2027", "01-01-2050"],
+        ... )
+        0    0.13901
+        1    0.13881
+        dtype: Float64
+
+        >>> # With extrapolation set to False, the second rate will be NaN
+        >>> # Note: 0.13576348733268917 is shown as 0.135763
+        >>> di1.interpolate_rates(
+        ...     dates="25-04-2025",
+        ...     expirations=["01-11-2027", "01-01-2050"],
+        ...     extrapolate=False,
+        ... )
+        0    0.135763
+        1    <NA>
+        dtype: Float64
+
+    Notes:
+        - All available settlement rates are used for the flat-forward interpolation.
+        - The function handles broadcasting of scalar and array-like inputs.
     """
     # Convert input dates to a consistent format
     dates = dc.convert_input_dates(dates)
@@ -230,11 +253,7 @@ def interpolate_rates(
     dfi["irate"] = dfi["irate"].astype("Float64")
 
     # Load DI rates dataset filtered by the provided reference dates
-    dfr = (
-        get_cached_dataset("DI")
-        .query("TradeDate in @dfi['tdate'].unique()")
-        .reset_index(drop=True)
-    )
+    dfr = data(dates=dates)
 
     # Return an empty DataFrame if no rates are found
     if dfr.empty:
@@ -308,13 +327,12 @@ def interpolate_rate(
         >>> di1.interpolate_rate("25-04-2025", "01-01-2050", extrapolate=True)
         0.13881
     """
-
     expiration = dc.convert_input_dates(expiration)
     if not date:
         return float("NaN")
 
     # Get the DI contract DataFrame
-    df = data(date=date)
+    df = data(dates=date)
 
     if df.empty:
         return float("NaN")

{pyield-0.35.0 → pyield-0.35.2}/pyield/tpf/ltn.py

@@ -136,7 +136,9 @@ def di_spreads(date: DateScalar) -> pd.DataFrame:
 
     Examples:
         >>> from pyield import ltn
-        >>> ltn.di_spreads("22-08-2024")
+        >>> spreads = ltn.di_spreads("22-08-2024")
+        >>> spreads["DISpread"] = spreads["DISpread"] * 10000  # Convert to bps
+        >>> spreads
            MaturityDate  DISpread
         0    2024-10-01     -3.06
         1    2025-01-01     -9.95

{pyield-0.35.0 → pyield-0.35.2}/pyield/tpf/ntnf.py

@@ -344,7 +344,9 @@ def di_spreads(date: DateScalar) -> pd.DataFrame:
 
     Examples:
         >>> from pyield import ntnf
-        >>> ntnf.di_spreads("23-08-2024")
+        >>> df_spreads = ntnf.di_spreads("23-08-2024")
+        >>> df_spreads["DISpread"] = df_spreads["DISpread"] * 10_000  # Convert to bps
+        >>> df_spreads
           MaturityDate  DISpread
         0   2025-01-01     -5.38
         1   2027-01-01      4.39
@@ -444,19 +446,20 @@ def di_net_spread(  # noqa
             None. A good initial guess is the DI gross spread for the bond.
 
     Returns:
-        float: The net DI spread in basis points.
+        float: The net DI spread in decimal format (e.g., 0.0012 for 12 bps).
 
     Examples:
         # Obs: only some of the DI rates will be used in the example.
         >>> exp_dates = pd.to_datetime(["2025-01-01", "2030-01-01", "2035-01-01"])
         >>> di_rates = pd.Series([0.10823, 0.11594, 0.11531])
-        >>> di_net_spread(
+        >>> spread = di_net_spread(
         ...     settlement="23-08-2024",
         ...     ntnf_maturity="01-01-2035",
         ...     ntnf_rate=0.116586,
         ...     di_expirations=exp_dates,
         ...     di_rates=di_rates,
         ... )
+        >>> round(spread * 10_000, 2)  # Convert to bps for display
         12.13
     """
     # Create an interpolator for the DI rates using the flat-forward method
@@ -489,9 +492,7 @@ def di_net_spread(  # noqa
         return (bond_cash_flows / (1 + di_interp + p) ** byears).sum() - bond_price
 
     # 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)
+    return _solve_spread(price_difference, initial_guess)
 
 
 def premium(

{pyield-0.35.0 → pyield-0.35.2}/pyield/tpf/tools.py

@@ -77,7 +77,7 @@ def pre_spreads(date: DateScalar) -> pd.DataFrame:
     """
     # Fetch DI rates for the reference date
     converted_date = dc.convert_input_dates(date)
-    df_di = di1.data(date=converted_date, month_start=True)
+    df_di = di1.data(dates=converted_date, month_start=True)
     if "SettlementRate" not in df_di.columns or df_di.empty:
         raise ValueError("DI data is missing the 'SettlementRate' column or is empty.")
 
@@ -97,9 +97,6 @@ def pre_spreads(date: DateScalar) -> pd.DataFrame:
     # Calculate the DI spread as the difference between indicative and settlement rates
     df_spreads["DISpread"] = df_spreads["IndicativeRate"] - df_spreads["SettlementRate"]
 
-    # Convert spread to basis points for clarity
-    df_spreads["DISpread"] = (10_000 * df_spreads["DISpread"]).round(2)
-
     # Prepare and return the final sorted DataFrame
     df_spreads = df_spreads.sort_values(["BondType", "MaturityDate"], ignore_index=True)
     return df_spreads[["BondType", "MaturityDate", "DISpread"]].copy()

pyield-0.35.0/pyield/__about__.py

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