aponyx 0.1.0__py3-none-any.whl

aponyx/backtest/metrics.py

@@ -0,0 +1,216 @@
+"""
+Performance and risk metrics for backtest analysis.
+
+Provides standard quantitative metrics for strategy evaluation.
+Metrics follow industry conventions and are compatible with common
+performance attribution frameworks.
+"""
+
+import logging
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PerformanceMetrics:
+    """
+    Container for strategy performance statistics.
+
+    Attributes
+    ----------
+    sharpe_ratio : float
+        Annualized Sharpe ratio (assumes 252 trading days).
+    sortino_ratio : float
+        Annualized Sortino ratio (downside deviation).
+    max_drawdown : float
+        Maximum peak-to-trough decline in cumulative P&L.
+    calmar_ratio : float
+        Annualized return divided by max drawdown.
+    total_return : float
+        Total P&L over backtest period.
+    annualized_return : float
+        Total return annualized to yearly basis.
+    annualized_volatility : float
+        Annualized standard deviation of daily returns.
+    hit_rate : float
+        Proportion of profitable trades (0.0 to 1.0).
+    avg_win : float
+        Average P&L of winning trades.
+    avg_loss : float
+        Average P&L of losing trades (negative).
+    win_loss_ratio : float
+        Absolute value of avg_win / avg_loss.
+    n_trades : int
+        Total number of round-trip trades.
+    avg_holding_days : float
+        Average days per trade.
+
+    Notes
+    -----
+    All ratios use risk-free rate = 0 for simplicity.
+    Metrics are based on daily P&L, not mark-to-market equity curve.
+    """
+
+    sharpe_ratio: float
+    sortino_ratio: float
+    max_drawdown: float
+    calmar_ratio: float
+    total_return: float
+    annualized_return: float
+    annualized_volatility: float
+    hit_rate: float
+    avg_win: float
+    avg_loss: float
+    win_loss_ratio: float
+    n_trades: int
+    avg_holding_days: float
+
+
+def compute_performance_metrics(
+    pnl_df: pd.DataFrame,
+    positions_df: pd.DataFrame,
+) -> PerformanceMetrics:
+    """
+    Compute comprehensive performance metrics from backtest results.
+
+    Parameters
+    ----------
+    pnl_df : pd.DataFrame
+        Daily P&L data with 'net_pnl' and 'cumulative_pnl' columns.
+    positions_df : pd.DataFrame
+        Daily position data with 'position' and 'days_held' columns.
+
+    Returns
+    -------
+    PerformanceMetrics
+        Complete set of performance statistics.
+
+    Notes
+    -----
+    Calculations assume:
+    - 252 trading days per year for annualization
+    - No risk-free rate (excess returns = total returns)
+    - Daily P&L represents actual trading results
+
+    Sharpe and Sortino use daily P&L volatility, not equity curve volatility.
+    This better captures strategy risk for overlay strategies.
+
+    Examples
+    --------
+    >>> metrics = compute_performance_metrics(result.pnl, result.positions)
+    >>> print(f"Sharpe: {metrics.sharpe_ratio:.2f}, Max DD: ${metrics.max_drawdown:,.0f}")
+    """
+    logger.info("Computing performance metrics")
+
+    # Basic statistics
+    daily_pnl = pnl_df["net_pnl"]
+    cum_pnl = pnl_df["cumulative_pnl"]
+    n_days = len(pnl_df)
+    n_years = n_days / 252.0
+
+    # Return metrics
+    total_return = cum_pnl.iloc[-1]
+    annualized_return = total_return / n_years if n_years > 0 else 0.0
+
+    # Risk metrics
+    daily_std = daily_pnl.std()
+    annualized_vol = daily_std * np.sqrt(252)
+
+    # Sharpe ratio (using daily P&L, not equity curve)
+    if daily_std > 0:
+        sharpe_ratio = (daily_pnl.mean() / daily_std) * np.sqrt(252)
+    else:
+        sharpe_ratio = 0.0
+
+    # Sortino ratio (downside deviation)
+    downside_returns = daily_pnl[daily_pnl < 0]
+    if len(downside_returns) > 0:
+        downside_std = downside_returns.std()
+        if downside_std > 0:
+            sortino_ratio = (daily_pnl.mean() / downside_std) * np.sqrt(252)
+        else:
+            sortino_ratio = 0.0
+    else:
+        sortino_ratio = sharpe_ratio  # No downside = same as Sharpe
+
+    # Drawdown analysis
+    running_max = cum_pnl.expanding().max()
+    drawdown = cum_pnl - running_max
+    max_drawdown = drawdown.min()
+
+    # Calmar ratio
+    if max_drawdown < 0:
+        calmar_ratio = annualized_return / abs(max_drawdown)
+    else:
+        calmar_ratio = 0.0
+
+    # Trade-level statistics
+    # Identify trade entries (transitions from flat to positioned)
+    prev_position = positions_df["position"].shift(1).fillna(0)
+    position_entries = (prev_position == 0) & (positions_df["position"] != 0)
+    n_trades = position_entries.sum()
+
+    # Compute P&L per trade by grouping consecutive positions
+    # Assign a trade_id to each position period
+    position_changes = (positions_df["position"] != prev_position).astype(int)
+    trade_id = position_changes.cumsum()
+    
+    # Only include periods where we have a position
+    active_trades = positions_df[positions_df["position"] != 0].copy()
+    
+    if len(active_trades) > 0:
+        active_trades["trade_id"] = trade_id[positions_df["position"] != 0]
+        
+        # Sum P&L per trade_id
+        trade_pnls = pnl_df.loc[active_trades.index].groupby(
+            active_trades["trade_id"]
+        )["net_pnl"].sum()
+        
+        trade_pnls_array = trade_pnls.values
+        winning_trades = trade_pnls_array[trade_pnls_array > 0]
+        losing_trades = trade_pnls_array[trade_pnls_array < 0]
+
+        hit_rate = len(winning_trades) / len(trade_pnls_array) if len(trade_pnls_array) > 0 else 0.0
+        avg_win = winning_trades.mean() if len(winning_trades) > 0 else 0.0
+        avg_loss = losing_trades.mean() if len(losing_trades) > 0 else 0.0
+
+        if avg_loss < 0:
+            win_loss_ratio = abs(avg_win / avg_loss)
+        else:
+            win_loss_ratio = 0.0
+    else:
+        hit_rate = 0.0
+        avg_win = 0.0
+        avg_loss = 0.0
+        win_loss_ratio = 0.0
+
+    # Holding period statistics
+    holding_periods = positions_df[positions_df["position"] != 0]["days_held"]
+    avg_holding_days = holding_periods.mean() if len(holding_periods) > 0 else 0.0
+
+    logger.info(
+        "Metrics computed: sharpe=%.2f, max_dd=$%.0f, hit_rate=%.1f%%",
+        sharpe_ratio,
+        max_drawdown,
+        hit_rate * 100,
+    )
+
+    return PerformanceMetrics(
+        sharpe_ratio=sharpe_ratio,
+        sortino_ratio=sortino_ratio,
+        max_drawdown=max_drawdown,
+        calmar_ratio=calmar_ratio,
+        total_return=total_return,
+        annualized_return=annualized_return,
+        annualized_volatility=annualized_vol,
+        hit_rate=hit_rate,
+        avg_win=avg_win,
+        avg_loss=avg_loss,
+        win_loss_ratio=win_loss_ratio,
+        n_trades=int(n_trades),
+        avg_holding_days=avg_holding_days,
+    )

aponyx/backtest/protocols.py

@@ -0,0 +1,101 @@
+"""
+Protocol definitions for backtest engine extensibility.
+
+These protocols define the interface for swappable backtest components,
+allowing easy integration of external libraries (vectorbt, backtrader, etc.)
+while maintaining our domain-specific API.
+"""
+
+from typing import Protocol
+
+import pandas as pd
+
+from .config import BacktestConfig
+from .engine import BacktestResult
+
+
+class BacktestEngine(Protocol):
+    """
+    Protocol for backtest engine implementations.
+
+    This allows swapping between our simple implementation and
+    more sophisticated libraries while maintaining the same API.
+
+    Examples
+    --------
+    >>> # Our implementation
+    >>> from aponyx.backtest import run_backtest
+    >>> result = run_backtest(signal, spread, config)
+    >>>
+    >>> # Future: vectorbt wrapper
+    >>> from aponyx.backtest.adapters import VectorBTEngine
+    >>> engine = VectorBTEngine()
+    >>> result = engine.run(signal, spread, config)
+    """
+
+    def run(
+        self,
+        composite_signal: pd.Series,
+        spread: pd.Series,
+        config: BacktestConfig | None = None,
+    ) -> BacktestResult:
+        """
+        Execute backtest on signal and price data.
+
+        Parameters
+        ----------
+        composite_signal : pd.Series
+            Daily positioning scores from signal computation.
+        spread : pd.Series
+            CDX spread levels aligned to signal dates.
+        config : BacktestConfig | None
+            Backtest parameters. Uses defaults if None.
+
+        Returns
+        -------
+        BacktestResult
+            Complete backtest results including positions and P&L.
+        """
+        ...
+
+
+class PerformanceCalculator(Protocol):
+    """
+    Protocol for performance metrics calculation.
+
+    Allows swapping between our simple implementation and
+    libraries like quantstats, empyrical, pyfolio, etc.
+
+    Examples
+    --------
+    >>> # Our implementation
+    >>> from aponyx.backtest import compute_performance_metrics
+    >>> metrics = compute_performance_metrics(result.pnl, result.positions)
+    >>>
+    >>> # Future: quantstats wrapper
+    >>> from aponyx.backtest.adapters import QuantStatsCalculator
+    >>> calc = QuantStatsCalculator()
+    >>> metrics = calc.compute(result.pnl, result.positions)
+    """
+
+    def compute(
+        self,
+        pnl_df: pd.DataFrame,
+        positions_df: pd.DataFrame,
+    ) -> pd.DataFrame | dict:
+        """
+        Compute performance metrics from backtest results.
+
+        Parameters
+        ----------
+        pnl_df : pd.DataFrame
+            Daily P&L data with 'net_pnl' and 'cumulative_pnl' columns.
+        positions_df : pd.DataFrame
+            Daily position data with 'position' and 'days_held' columns.
+
+        Returns
+        -------
+        pd.DataFrame | dict
+            Performance statistics. Format may vary by implementation.
+        """
+        ...

aponyx/config/__init__.py

@@ -0,0 +1,77 @@
+"""
+Configuration module for paths, constants, and environment settings.
+
+Defines project-wide constants including instrument universe, data paths,
+and default parameters for the CDX overlay strategy.
+"""
+
+from pathlib import Path
+from typing import Final, Any
+
+# Project root and data directories
+# From src/aponyx/config/__init__.py -> src/aponyx -> src -> project_root
+PROJECT_ROOT: Final[Path] = Path(__file__).parent.parent.parent.parent
+DATA_DIR: Final[Path] = PROJECT_ROOT / "data"
+REGISTRY_PATH: Final[Path] = DATA_DIR / "registry.json"
+LOGS_DIR: Final[Path] = PROJECT_ROOT / "logs"
+
+# Instrument universe for CDX overlay strategy
+CDX_INSTRUMENTS: Final[dict[str, list[str]]] = {
+    "IG": ["5Y", "10Y"],  # Investment Grade
+    "HY": ["5Y"],  # High Yield
+    "XO": ["5Y"],  # Crossover
+}
+
+# ETF proxies for signal generation (not direct trading)
+ETF_TICKERS: Final[list[str]] = ["HYG", "LQD"]
+
+# Market data identifiers
+MARKET_DATA_TICKERS: Final[dict[str, str]] = {
+    "VIX": "^VIX",
+    "SPX": "^GSPC",
+}
+
+# Default signal parameters
+DEFAULT_SIGNAL_PARAMS: Final[dict[str, int | float]] = {
+    "momentum_window": 5,
+    "volatility_window": 20,
+    "z_score_window": 60,
+    "basis_threshold": 0.5,
+}
+
+# Data versioning
+DATA_VERSION: Final[str] = "0.1.0"
+
+# Cache configuration
+CACHE_ENABLED: Final[bool] = True
+CACHE_TTL_DAYS: Final[dict[str, int | None]] = {
+    "cdx": 1,  # Daily refresh for market data
+    "vix": 1,
+    "etf": 1,
+}
+
+# Default data sources (can be overridden per fetch call)
+# Set to None to require explicit source in fetch calls
+DEFAULT_DATA_SOURCES: Final[dict[str, Any]] = {
+    "cdx": None,
+    "vix": None,
+    "etf": None,
+}
+
+
+def ensure_directories() -> None:
+    """
+    Create required directories if they don't exist.
+
+    Creates data, logs, and other necessary directories for the project.
+    Safe to call multiple times.
+    """
+    DATA_DIR.mkdir(parents=True, exist_ok=True)
+    LOGS_DIR.mkdir(parents=True, exist_ok=True)
+    (DATA_DIR / "raw").mkdir(exist_ok=True)
+    (DATA_DIR / "processed").mkdir(exist_ok=True)
+    (DATA_DIR / "cache").mkdir(exist_ok=True)
+
+
+# Initialize directories on module import
+ensure_directories()

aponyx/data/__init__.py

@@ -0,0 +1,31 @@
+"""
+Data layer for systematic macro credit strategy.
+
+This module handles data fetching, cleaning, and transformation for:
+- CDX indices (IG, HY, XO) across tenors
+- VIX equity volatility index
+- Credit ETFs (HYG, LQD) used for signal generation
+
+All fetch functions produce standardized DataFrames with DatetimeIndex and validated schemas.
+Supports multiple data providers: local files, Bloomberg Terminal, APIs.
+"""
+
+from .fetch import fetch_cdx, fetch_vix, fetch_etf
+from .sources import FileSource, BloombergSource, APISource, DataSource
+from .validation import validate_cdx_schema, validate_vix_schema, validate_etf_schema
+
+__all__ = [
+    # Fetch functions
+    "fetch_cdx",
+    "fetch_vix",
+    "fetch_etf",
+    # Data sources
+    "FileSource",
+    "BloombergSource",
+    "APISource",
+    "DataSource",
+    # Validation
+    "validate_cdx_schema",
+    "validate_vix_schema",
+    "validate_etf_schema",
+]

aponyx/data/cache.py

@@ -0,0 +1,242 @@
+"""
+Transparent caching layer for fetched data.
+
+Caches API/provider responses to local Parquet files with staleness tracking.
+"""
+
+import hashlib
+import logging
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+from ..persistence.parquet_io import save_parquet, load_parquet
+from ..persistence.registry import DataRegistry
+from .sources import DataSource, resolve_provider
+
+logger = logging.getLogger(__name__)
+
+
+def _generate_cache_key(
+    source: DataSource,
+    instrument: str,
+    start_date: str | None,
+    end_date: str | None,
+    **params: Any,
+) -> str:
+    """
+    Generate unique cache key from fetch parameters.
+
+    Parameters
+    ----------
+    source : DataSource
+        Data source configuration.
+    instrument : str
+        Instrument identifier.
+    start_date : str or None
+        Start date.
+    end_date : str or None
+        End date.
+    **params : Any
+        Additional parameters.
+
+    Returns
+    -------
+    str
+        Hash-based cache key.
+    """
+    # Create stable string representation
+    key_parts = [
+        resolve_provider(source),
+        instrument,
+        start_date or "none",
+        end_date or "none",
+        str(sorted(params.items())),
+    ]
+    key_string = "|".join(key_parts)
+
+    # Generate hash
+    hash_obj = hashlib.sha256(key_string.encode())
+    return hash_obj.hexdigest()[:16]
+
+
+def get_cache_path(
+    cache_dir: Path,
+    provider: str,
+    instrument: str,
+    cache_key: str,
+) -> Path:
+    """
+    Generate file path for cached data.
+
+    Parameters
+    ----------
+    cache_dir : Path
+        Base cache directory.
+    provider : str
+        Provider type (file, bloomberg, api).
+    instrument : str
+        Instrument identifier.
+    cache_key : str
+        Unique cache key.
+
+    Returns
+    -------
+    Path
+        Path to cache file.
+    """
+    provider_dir = cache_dir / provider
+    provider_dir.mkdir(parents=True, exist_ok=True)
+
+    # Sanitize instrument name for filename
+    safe_instrument = instrument.replace(".", "_").replace("/", "_")
+    filename = f"{safe_instrument}_{cache_key}.parquet"
+
+    return provider_dir / filename
+
+
+def is_cache_stale(
+    cache_path: Path,
+    ttl_days: int | None = None,
+) -> bool:
+    """
+    Check if cached data is stale based on TTL.
+
+    Parameters
+    ----------
+    cache_path : Path
+        Path to cached file.
+    ttl_days : int or None
+        Time-to-live in days. None means cache never expires.
+
+    Returns
+    -------
+    bool
+        True if cache is stale or doesn't exist.
+    """
+    if not cache_path.exists():
+        return True
+
+    if ttl_days is None:
+        return False
+
+    # Check file modification time
+    mtime = datetime.fromtimestamp(cache_path.stat().st_mtime)
+    age = datetime.now() - mtime
+
+    is_stale = age > timedelta(days=ttl_days)
+
+    if is_stale:
+        logger.debug("Cache stale: age=%s, ttl=%d days", age, ttl_days)
+
+    return is_stale
+
+
+def get_cached_data(
+    source: DataSource,
+    instrument: str,
+    cache_dir: Path,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    ttl_days: int | None = None,
+    **params: Any,
+) -> pd.DataFrame | None:
+    """
+    Retrieve data from cache if available and fresh.
+
+    Parameters
+    ----------
+    source : DataSource
+        Data source configuration.
+    instrument : str
+        Instrument identifier.
+    cache_dir : Path
+        Cache directory.
+    start_date : str or None
+        Start date filter.
+    end_date : str or None
+        End date filter.
+    ttl_days : int or None
+        Cache TTL in days.
+    **params : Any
+        Additional fetch parameters.
+
+    Returns
+    -------
+    pd.DataFrame or None
+        Cached data if available and fresh, None otherwise.
+    """
+    provider = resolve_provider(source)
+    cache_key = _generate_cache_key(source, instrument, start_date, end_date, **params)
+    cache_path = get_cache_path(cache_dir, provider, instrument, cache_key)
+
+    if is_cache_stale(cache_path, ttl_days):
+        logger.debug("Cache miss or stale: %s", cache_path.name)
+        return None
+
+    logger.info("Cache hit: %s", cache_path.name)
+    return load_parquet(cache_path)
+
+
+def save_to_cache(
+    df: pd.DataFrame,
+    source: DataSource,
+    instrument: str,
+    cache_dir: Path,
+    registry: DataRegistry | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    **params: Any,
+) -> Path:
+    """
+    Save fetched data to cache.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Data to cache.
+    source : DataSource
+        Data source configuration.
+    instrument : str
+        Instrument identifier.
+    cache_dir : Path
+        Cache directory.
+    registry : DataRegistry or None
+        Optional registry to register cached dataset.
+    start_date : str or None
+        Start date (for cache key).
+    end_date : str or None
+        End date (for cache key).
+    **params : Any
+        Additional parameters (for cache key).
+
+    Returns
+    -------
+    Path
+        Path to cached file.
+    """
+    provider = resolve_provider(source)
+    cache_key = _generate_cache_key(source, instrument, start_date, end_date, **params)
+    cache_path = get_cache_path(cache_dir, provider, instrument, cache_key)
+
+    # Save to Parquet
+    save_parquet(df, cache_path)
+    logger.info("Cached data: path=%s, rows=%d", cache_path, len(df))
+
+    # Register in catalog if provided
+    if registry is not None:
+        registry.register_dataset(
+            name=f"cache_{instrument}_{cache_key}",
+            file_path=cache_path,
+            instrument=instrument,
+            metadata={
+                "provider": provider,
+                "cached_at": datetime.now().isoformat(),
+                "cache_key": cache_key,
+                "params": params,
+            },
+        )
+
+    return cache_path