aponyx 0.1.0__py3-none-any.whl

aponyx/models/signals.py

@@ -0,0 +1,221 @@
+"""
+Core signal generation functions for CDX overlay strategy.
+
+Implements the three pilot signals:
+1. CDX-ETF basis (flow-driven mispricing)
+2. CDX-VIX gap (cross-asset risk sentiment)
+3. Spread momentum (short-term continuation)
+"""
+
+import logging
+import pandas as pd
+
+from .config import SignalConfig
+
+logger = logging.getLogger(__name__)
+
+
+def compute_cdx_etf_basis(
+    cdx_df: pd.DataFrame,
+    etf_df: pd.DataFrame,
+    config: SignalConfig | None = None,
+) -> pd.Series:
+    """
+    Compute normalized basis between CDX index spreads and ETF-implied spreads.
+
+    The signal captures temporary mispricing driven by ETF flows and liquidity
+    constraints. Positive values indicate CDX is cheap relative to ETF (long CDX
+    vs short ETF). Negative values indicate CDX is expensive (short CDX vs long ETF).
+
+    Parameters
+    ----------
+    cdx_df : pd.DataFrame
+        CDX spread data with DatetimeIndex and 'spread' column.
+    etf_df : pd.DataFrame
+        ETF price data with DatetimeIndex and 'close' column.
+    config : SignalConfig | None
+        Configuration parameters. Uses defaults if None.
+
+    Returns
+    -------
+    pd.Series
+        Z-score normalized basis signal aligned to common dates.
+
+    Notes
+    -----
+    - Uses z-score normalization over rolling window for regime independence.
+    - Assumes ETF prices have been converted to spread-equivalent units externally.
+    - Missing values are forward-filled before alignment to avoid spurious gaps.
+    """
+    if config is None:
+        config = SignalConfig()
+
+    logger.info(
+        "Computing CDX-ETF basis: cdx_rows=%d, etf_rows=%d, lookback=%d",
+        len(cdx_df),
+        len(etf_df),
+        config.lookback,
+    )
+
+    # Align data to common dates
+    cdx_spread = cdx_df["spread"]
+    etf_spread = etf_df["close"].reindex(cdx_df.index, method="ffill")
+
+    # Compute raw basis
+    raw_basis = cdx_spread - etf_spread
+
+    # Normalize using rolling z-score
+    rolling_mean = raw_basis.rolling(
+        window=config.lookback,
+        min_periods=config.min_periods,
+    ).mean()
+    rolling_std = raw_basis.rolling(
+        window=config.lookback,
+        min_periods=config.min_periods,
+    ).std()
+
+    signal = (raw_basis - rolling_mean) / rolling_std
+
+    valid_count = signal.notna().sum()
+    logger.debug("Generated %d valid basis signals", valid_count)
+
+    return signal
+
+
+def compute_cdx_vix_gap(
+    cdx_df: pd.DataFrame,
+    vix_df: pd.DataFrame,
+    config: SignalConfig | None = None,
+) -> pd.Series:
+    """
+    Compute cross-asset risk sentiment gap between credit spreads and equity vol.
+
+    Identifies divergence between CDX and VIX movements. Positive values indicate
+    credit stress outpacing equity stress (long credit risk). Negative values indicate
+    equity stress outpacing credit stress (short credit risk).
+
+    Parameters
+    ----------
+    cdx_df : pd.DataFrame
+        CDX spreads with DatetimeIndex and 'spread' column.
+    vix_df : pd.DataFrame
+        VIX levels with DatetimeIndex and 'close' column.
+    config : SignalConfig | None
+        Configuration parameters. Uses defaults if None.
+
+    Returns
+    -------
+    pd.Series
+        Z-score normalized CDX-VIX gap signal.
+
+    Notes
+    -----
+    - Both CDX and VIX deviations are computed from their own rolling means.
+    - Gap computed as CDX stress minus VIX stress for consistent sign convention.
+    - Normalized to account for varying volatility regimes.
+    - Filters out transient spikes by using mean deviation over the lookback period.
+    """
+    if config is None:
+        config = SignalConfig()
+
+    logger.info(
+        "Computing CDX-VIX gap: cdx_rows=%d, vix_rows=%d, lookback=%d",
+        len(cdx_df),
+        len(vix_df),
+        config.lookback,
+    )
+
+    # Align data to common dates
+    cdx = cdx_df["spread"]
+    vix = vix_df["close"].reindex(cdx_df.index, method="ffill")
+
+    # Compute deviations from rolling means
+    cdx_deviation = (
+        cdx
+        - cdx.rolling(
+            window=config.lookback,
+            min_periods=config.min_periods,
+        ).mean()
+    )
+    vix_deviation = (
+        vix
+        - vix.rolling(
+            window=config.lookback,
+            min_periods=config.min_periods,
+        ).mean()
+    )
+
+    # Raw gap: CDX stress minus VIX stress
+    # Positive when credit stress outpaces equity stress (buy CDX)
+    # Negative when equity stress outpaces credit stress (sell CDX)
+    raw_gap = cdx_deviation - vix_deviation
+
+    # Normalize the gap
+    rolling_std = raw_gap.rolling(
+        window=config.lookback,
+        min_periods=config.min_periods,
+    ).std()
+    signal = raw_gap / rolling_std
+
+    valid_count = signal.notna().sum()
+    logger.debug("Generated %d valid CDX-VIX gap signals", valid_count)
+
+    return signal
+
+
+def compute_spread_momentum(
+    cdx_df: pd.DataFrame,
+    config: SignalConfig | None = None,
+) -> pd.Series:
+    """
+    Compute short-term volatility-adjusted momentum in CDX spreads.
+
+    Captures continuation or mean-reversion tendencies over 3-10 day horizons.
+    Positive signal suggests long credit risk (spreads tightening, momentum favorable).
+    Negative signal suggests short credit risk (spreads widening, momentum unfavorable).
+
+    Parameters
+    ----------
+    cdx_df : pd.DataFrame
+        CDX spread data with DatetimeIndex and 'spread' column.
+    config : SignalConfig | None
+        Configuration parameters. Uses defaults if None.
+
+    Returns
+    -------
+    pd.Series
+        Z-score normalized momentum signal.
+
+    Notes
+    -----
+    - Uses negative of spread change: tightening spreads give positive signal.
+    - Short lookback (5-10 days) suitable for tactical overlay strategy.
+    - Positive signal indicates tightening momentum (bullish credit).
+    """
+    if config is None:
+        config = SignalConfig()
+
+    logger.info(
+        "Computing spread momentum: cdx_rows=%d, lookback=%d",
+        len(cdx_df),
+        config.lookback,
+    )
+
+    spread = cdx_df["spread"]
+
+    # Compute spread change over lookback period (negative for tightening)
+    spread_change = spread - spread.shift(config.lookback)
+
+    # Normalize by rolling volatility and negate
+    # Positive when spreads tightening (buy CDX)
+    # Negative when spreads widening (sell CDX)
+    rolling_std = spread.rolling(
+        window=config.lookback,
+        min_periods=config.min_periods,
+    ).std()
+    signal = -spread_change / rolling_std
+
+    valid_count = signal.notna().sum()
+    logger.debug("Generated %d valid momentum signals", valid_count)
+
+    return signal

aponyx/persistence/__init__.py

@@ -0,0 +1,20 @@
+"""
+Persistence layer for time series data and metadata management.
+
+Provides clean abstractions for Parquet and JSON I/O, with a registry
+system to track available datasets.
+"""
+
+from .parquet_io import save_parquet, load_parquet, list_parquet_files
+from .json_io import save_json, load_json
+from .registry import DataRegistry, DatasetEntry
+
+__all__ = [
+    "save_parquet",
+    "load_parquet",
+    "list_parquet_files",
+    "save_json",
+    "load_json",
+    "DataRegistry",
+    "DatasetEntry",
+]

aponyx/persistence/json_io.py

@@ -0,0 +1,130 @@
+"""
+JSON I/O utilities for metadata, parameters, and run logs.
+
+Handles serialization of dictionaries with support for common data types
+including datetime, Path, and numpy arrays.
+"""
+
+import json
+import logging
+from pathlib import Path
+from typing import Any
+from datetime import datetime, date
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class EnhancedJSONEncoder(json.JSONEncoder):
+    """
+    JSON encoder with support for datetime, Path, and numpy types.
+
+    Extends standard JSONEncoder to handle common scientific computing types
+    that appear in metadata and parameter dictionaries.
+    """
+
+    def default(self, obj: Any) -> Any:
+        """Convert non-serializable objects to JSON-compatible types."""
+        if isinstance(obj, (datetime, date)):
+            return obj.isoformat()
+        elif isinstance(obj, Path):
+            return str(obj)
+        elif isinstance(obj, np.integer):
+            return int(obj)
+        elif isinstance(obj, np.floating):
+            return float(obj)
+        elif isinstance(obj, np.ndarray):
+            return obj.tolist()
+        return super().default(obj)
+
+
+def save_json(
+    data: dict[str, Any],
+    path: str | Path,
+    indent: int = 2,
+    sort_keys: bool = True,
+) -> Path:
+    """
+    Save dictionary to JSON file with enhanced type support.
+
+    Parameters
+    ----------
+    data : dict
+        Dictionary to serialize. Supports datetime, Path, and numpy types.
+    path : str or Path
+        Target file path. Parent directories created if needed.
+    indent : int, default 2
+        Number of spaces for indentation (for readability).
+    sort_keys : bool, default True
+        Whether to sort dictionary keys alphabetically.
+
+    Returns
+    -------
+    Path
+        Absolute path to the saved file.
+
+    Examples
+    --------
+    >>> metadata = {
+    ...     'timestamp': datetime.now(),
+    ...     'params': {'window': 5, 'threshold': 0.5},
+    ...     'version': '0.1.0'
+    ... }
+    >>> save_json(metadata, 'logs/run_20241025.json')
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    logger.info("Saving JSON to %s (%d top-level keys)", path, len(data))
+
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(
+            data,
+            f,
+            cls=EnhancedJSONEncoder,
+            indent=indent,
+            sort_keys=sort_keys,
+            ensure_ascii=False,
+        )
+
+    logger.debug("Successfully saved %d bytes to %s", path.stat().st_size, path)
+    return path.absolute()
+
+
+def load_json(path: str | Path) -> dict[str, Any]:
+    """
+    Load dictionary from JSON file.
+
+    Parameters
+    ----------
+    path : str or Path
+        Source file path.
+
+    Returns
+    -------
+    dict
+        Deserialized dictionary.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the specified file does not exist.
+    json.JSONDecodeError
+        If the file contains invalid JSON.
+
+    Examples
+    --------
+    >>> metadata = load_json('logs/run_20241025.json')
+    >>> print(metadata['timestamp'])
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"JSON file not found: {path}")
+
+    logger.info("Loading JSON from %s", path)
+
+    with path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+
+    logger.debug("Loaded JSON with %d top-level keys", len(data) if isinstance(data, dict) else 0)
+    return data

aponyx/persistence/parquet_io.py

@@ -0,0 +1,174 @@
+"""
+Parquet I/O utilities for time series data persistence.
+
+Handles efficient storage and retrieval of market data (CDX spreads, VIX, ETF prices)
+with metadata preservation and validation.
+"""
+
+import logging
+from pathlib import Path
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+def save_parquet(
+    df: pd.DataFrame,
+    path: str | Path,
+    compression: str = "snappy",
+    index: bool = True,
+) -> Path:
+    """
+    Save DataFrame to Parquet with optimized settings for time series data.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        DataFrame to persist. For time series, index should be DatetimeIndex.
+    path : str or Path
+        Target file path. Parent directories created if needed.
+    compression : str, default "snappy"
+        Compression algorithm. Options: "snappy", "gzip", "brotli", "zstd".
+    index : bool, default True
+        Whether to write DataFrame index to file.
+
+    Returns
+    -------
+    Path
+        Absolute path to the saved file.
+
+    Raises
+    ------
+    ValueError
+        If DataFrame is empty or path is invalid.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'spread': [100, 105, 98]}, 
+    ...                   index=pd.date_range('2024-01-01', periods=3))
+    >>> save_parquet(df, 'data/cdx_ig_5y.parquet')
+    """
+    if df.empty:
+        raise ValueError("Cannot save empty DataFrame")
+
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    logger.info(
+        "Saving DataFrame to Parquet: path=%s, rows=%d, columns=%d, compression=%s",
+        path,
+        len(df),
+        len(df.columns),
+        compression,
+    )
+
+    df.to_parquet(
+        path,
+        engine="pyarrow",
+        compression=compression,
+        index=index,
+    )
+
+    logger.debug("Successfully saved %d bytes to %s", path.stat().st_size, path)
+    return path.absolute()
+
+
+def load_parquet(
+    path: str | Path,
+    columns: list[str] | None = None,
+    start_date: pd.Timestamp | None = None,
+    end_date: pd.Timestamp | None = None,
+) -> pd.DataFrame:
+    """
+    Load DataFrame from Parquet with optional filtering.
+
+    Parameters
+    ----------
+    path : str or Path
+        Source file path.
+    columns : list of str, optional
+        Subset of columns to load. If None, loads all columns.
+    start_date : pd.Timestamp, optional
+        Filter data from this date (inclusive). Requires DatetimeIndex.
+    end_date : pd.Timestamp, optional
+        Filter data to this date (inclusive). Requires DatetimeIndex.
+
+    Returns
+    -------
+    pd.DataFrame
+        Loaded and optionally filtered DataFrame.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the specified file does not exist.
+    ValueError
+        If date filtering is requested but index is not DatetimeIndex.
+
+    Examples
+    --------
+    >>> df = load_parquet('data/cdx_ig_5y.parquet', 
+    ...                   start_date=pd.Timestamp('2024-01-01'))
+    >>> df = load_parquet('data/vix.parquet', columns=['close'])
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Parquet file not found: {path}")
+
+    logger.info("Loading Parquet file: path=%s, columns=%s", path, columns or "all")
+
+    df = pd.read_parquet(path, engine="pyarrow", columns=columns)
+
+    # Apply date filtering if requested
+    if start_date is not None or end_date is not None:
+        if not isinstance(df.index, pd.DatetimeIndex):
+            raise ValueError(
+                "Date filtering requires DatetimeIndex. "
+                f"Got {type(df.index).__name__}"
+            )
+
+        if start_date is not None:
+            df = df[df.index >= start_date]
+        if end_date is not None:
+            df = df[df.index <= end_date]
+
+        logger.debug(
+            "Applied date filter: start=%s, end=%s, resulting_rows=%d",
+            start_date,
+            end_date,
+            len(df),
+        )
+
+    logger.info("Loaded %d rows, %d columns from %s", len(df), len(df.columns), path)
+    return df
+
+
+def list_parquet_files(directory: str | Path, pattern: str = "*.parquet") -> list[Path]:
+    """
+    List all Parquet files in a directory matching a pattern.
+
+    Parameters
+    ----------
+    directory : str or Path
+        Directory to search.
+    pattern : str, default "*.parquet"
+        Glob pattern for file matching.
+
+    Returns
+    -------
+    list of Path
+        Sorted list of matching file paths.
+
+    Examples
+    --------
+    >>> files = list_parquet_files('data/', pattern='cdx_*.parquet')
+    >>> files = list_parquet_files('data/raw/')
+    """
+    directory = Path(directory)
+    if not directory.exists():
+        logger.debug("Directory does not exist: %s", directory)
+        return []
+
+    files = sorted(directory.glob(pattern))
+    logger.info("Found %d Parquet files in %s (pattern=%s)", len(files), directory, pattern)
+    return files