aponyx 0.1.18__py3-none-any.whl

aponyx/examples/06_run_backtest.py

@@ -0,0 +1,242 @@
+"""
+Execute backtest for signal using strategy from catalog.
+
+Prerequisites
+-------------
+Signals saved from signal computation (04_compute_signal.py):
+- Signal files exist in data/workflows/signals/{signal_name}.parquet
+CDX spread data available from registry.
+Strategy catalog configured in backtest/strategy_catalog.json.
+
+Outputs
+-------
+BacktestResult with positions and P&L:
+- positions: DataFrame with signal, position, days_held, spread
+- pnl: DataFrame with spread_pnl, cost, net_pnl, cumulative_pnl
+- metadata: Config and execution details
+Backtest results saved to data/workflows/backtests/{signal_name}_{strategy}_*.parquet.
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.06_run_backtest
+
+Expected output: BacktestResult with positions and P&L history.
+Results saved to data/workflows/backtests/spread_momentum_balanced_*.parquet.
+"""
+
+import pandas as pd
+
+from aponyx.config import (
+    REGISTRY_PATH,
+    DATA_DIR,
+    DATA_WORKFLOWS_DIR,
+    STRATEGY_CATALOG_PATH,
+)
+from aponyx.data.registry import DataRegistry
+from aponyx.backtest import BacktestResult, run_backtest, StrategyRegistry
+from aponyx.persistence import load_parquet, save_parquet
+
+
+def main() -> BacktestResult:
+    """
+    Execute backtest workflow.
+
+    Loads signal and spread data, selects strategy from catalog,
+    runs backtest, and saves results.
+
+    Returns
+    -------
+    BacktestResult
+        Backtest result with positions and P&L.
+    """
+    signal_name, product, strategy_name = define_backtest_parameters()
+    signal, spread = load_backtest_data(signal_name, product)
+    config = load_strategy_config(strategy_name)
+    result = execute_backtest(signal, spread, config)
+    save_backtest_result(result, signal_name, strategy_name)
+    return result
+
+
+def define_backtest_parameters() -> tuple[str, str, str]:
+    """
+    Define backtest parameters.
+
+    Returns
+    -------
+    tuple[str, str, str]
+        Signal name, product identifier, and strategy name.
+
+    Notes
+    -----
+    Choose one signal-product-strategy combination for demonstration.
+    In practice, evaluate multiple strategies per signal.
+    """
+    signal_name = "spread_momentum"
+    product = "cdx_ig_5y"
+    strategy_name = "balanced"
+    return signal_name, product, strategy_name
+
+
+def load_backtest_data(
+    signal_name: str,
+    product: str,
+) -> tuple[pd.Series, pd.Series]:
+    """
+    Load signal and spread data for backtest.
+
+    Parameters
+    ----------
+    signal_name : str
+        Name of signal to load from processed directory.
+    product : str
+        Product identifier for spread data.
+
+    Returns
+    -------
+    tuple[pd.Series, pd.Series]
+        Signal series and spread series (aligned).
+
+    Notes
+    -----
+    Loads signal saved by previous step (04_compute_signal.py).
+    Spread data loaded from registry using product identifier.
+    """
+    signal = load_signal(signal_name)
+    spread = load_spread_data(product)
+
+    # Align signal and spread to common dates
+    common_idx = signal.index.intersection(spread.index)
+    signal = signal.loc[common_idx]
+    spread = spread.loc[common_idx]
+
+    return signal, spread
+
+
+def load_signal(signal_name: str) -> pd.Series:
+    """
+    Load signal from processed directory.
+
+    Parameters
+    ----------
+    signal_name : str
+        Name of signal file (without .parquet extension).
+
+    Returns
+    -------
+    pd.Series
+        Signal series with DatetimeIndex.
+    """
+    signal_path = DATA_WORKFLOWS_DIR / "signals" / f"{signal_name}.parquet"
+    signal_df = load_parquet(signal_path)
+    return signal_df["value"]
+
+
+def load_spread_data(product: str) -> pd.Series:
+    """
+    Load spread data for target product.
+
+    Parameters
+    ----------
+    product : str
+        Product identifier (e.g., "cdx_ig_5y").
+
+    Returns
+    -------
+    pd.Series
+        Spread series with DatetimeIndex.
+
+    Notes
+    -----
+    Uses DataRegistry.load_dataset_by_security() for efficient lookup.
+    """
+    data_registry = DataRegistry(REGISTRY_PATH, DATA_DIR)
+    spread_df = data_registry.load_dataset_by_security(product)
+    return spread_df["spread"]
+
+
+def load_strategy_config(strategy_name: str):
+    """
+    Load strategy configuration from catalog.
+
+    Parameters
+    ----------
+    strategy_name : str
+        Name of strategy in catalog (e.g., "balanced", "conservative").
+
+    Returns
+    -------
+    BacktestConfig
+        Backtest configuration with strategy parameters.
+
+    Notes
+    -----
+    Reads strategy metadata from catalog and converts to BacktestConfig.
+    """
+    registry = StrategyRegistry(STRATEGY_CATALOG_PATH)
+    metadata = registry.get_metadata(strategy_name)
+    return metadata.to_config()
+
+
+def execute_backtest(
+    signal: pd.Series,
+    spread: pd.Series,
+    config,
+) -> BacktestResult:
+    """
+    Run backtest with signal and spread data.
+
+    Parameters
+    ----------
+    signal : pd.Series
+        Signal series with DatetimeIndex.
+    spread : pd.Series
+        Spread series with DatetimeIndex.
+    config : BacktestConfig
+        Backtest configuration.
+
+    Returns
+    -------
+    BacktestResult
+        Backtest result with positions and P&L.
+    """
+    return run_backtest(signal, spread, config)
+
+
+def save_backtest_result(
+    result: BacktestResult,
+    signal_name: str,
+    strategy_name: str,
+) -> None:
+    """
+    Save backtest results to processed directory.
+
+    Parameters
+    ----------
+    result : BacktestResult
+        Backtest result to save.
+    signal_name : str
+        Name of signal.
+    strategy_name : str
+        Name of strategy.
+
+    Notes
+    -----
+    Saves positions and P&L DataFrames to separate parquet files.
+    File naming: {signal_name}_{strategy_name}_positions.parquet
+                 {signal_name}_{strategy_name}_pnl.parquet
+    """
+    backtests_dir = DATA_WORKFLOWS_DIR / "backtests"
+    backtests_dir.mkdir(parents=True, exist_ok=True)
+
+    # Save positions
+    positions_path = backtests_dir / f"{signal_name}_{strategy_name}_positions.parquet"
+    save_parquet(result.positions, positions_path)
+
+    # Save P&L
+    pnl_path = backtests_dir / f"{signal_name}_{strategy_name}_pnl.parquet"
+    save_parquet(result.pnl, pnl_path)
+
+
+if __name__ == "__main__":
+    main()

aponyx/examples/07_analyze_performance.py

@@ -0,0 +1,214 @@
+"""
+Compute comprehensive performance metrics for backtest results.
+
+Prerequisites
+-------------
+Backtest results saved from backtest execution (06_run_backtest.py):
+- Positions file: data/workflows/backtests/{signal}_{strategy}_positions.parquet
+- P&L file: data/workflows/backtests/{signal}_{strategy}_pnl.parquet
+
+Outputs
+-------
+PerformanceResult with comprehensive metrics:
+- All 21+ performance metrics (Sharpe, drawdown, profit factor, tail ratio, etc.)
+- Subperiod stability analysis (quarterly breakdown with full metrics per period)
+- Return attribution (directional, signal strength, win/loss decomposition)
+- Overall stability score and interpretive summary
+Performance report saved to reports/performance/{signal}_{strategy}_{timestamp}.md.
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.07_analyze_performance
+
+Expected output: PerformanceResult with stability score ~0.7, profit factor ~1.5.
+Markdown report saved to reports/performance/spread_momentum_balanced_{timestamp}.md.
+"""
+
+from aponyx.config import DATA_WORKFLOWS_DIR
+from aponyx.backtest import BacktestResult
+from aponyx.evaluation.performance import (
+    analyze_backtest_performance,
+    PerformanceConfig,
+    PerformanceResult,
+    generate_performance_report,
+    save_report,
+)
+from aponyx.persistence import load_parquet
+
+
+def main() -> PerformanceResult:
+    """
+    Execute performance analysis workflow.
+
+    Loads backtest results, computes comprehensive metrics,
+    generates interpretive report, and saves outputs.
+
+    Returns
+    -------
+    PerformanceResult
+        Performance evaluation with metrics, attribution, and summary.
+    """
+    signal_name, strategy_name = define_analysis_parameters()
+    backtest_result = load_backtest_result(signal_name, strategy_name)
+    config = define_performance_config()
+    performance = compute_performance_metrics(backtest_result, config)
+    save_performance_report(performance, signal_name, strategy_name)
+    return performance
+
+
+def define_analysis_parameters() -> tuple[str, str]:
+    """
+    Define analysis parameters.
+
+    Returns
+    -------
+    tuple[str, str]
+        Signal name and strategy name.
+
+    Notes
+    -----
+    Must match the signal-strategy combination from backtest step.
+    """
+    signal_name = "spread_momentum"
+    strategy_name = "balanced"
+    return signal_name, strategy_name
+
+
+def load_backtest_result(
+    signal_name: str,
+    strategy_name: str,
+) -> BacktestResult:
+    """
+    Load backtest results from processed directory.
+
+    Parameters
+    ----------
+    signal_name : str
+        Name of signal.
+    strategy_name : str
+        Name of strategy.
+
+    Returns
+    -------
+    BacktestResult
+        Backtest result with positions and P&L DataFrames.
+
+    Notes
+    -----
+    Loads positions and P&L from separate parquet files saved
+    by previous step (06_run_backtest.py). Reconstructs BacktestResult
+    with minimal metadata for analysis.
+    """
+    backtests_dir = DATA_WORKFLOWS_DIR / "backtests"
+
+    positions_path = backtests_dir / f"{signal_name}_{strategy_name}_positions.parquet"
+    pnl_path = backtests_dir / f"{signal_name}_{strategy_name}_pnl.parquet"
+
+    positions = load_parquet(positions_path)
+    pnl = load_parquet(pnl_path)
+
+    metadata = {
+        "signal_id": signal_name,
+        "strategy_id": strategy_name,
+    }
+
+    return BacktestResult(
+        positions=positions,
+        pnl=pnl,
+        metadata=metadata,
+    )
+
+
+def define_performance_config() -> PerformanceConfig:
+    """
+    Define performance evaluation configuration.
+
+    Returns
+    -------
+    PerformanceConfig
+        Configuration with analysis parameters.
+
+    Notes
+    -----
+    Uses quarterly subperiod analysis (n_subperiods=4) and
+    3-month rolling window (rolling_window=63) for stability metrics.
+    Attribution uses terciles (attribution_quantiles=3) for
+    low/medium/high signal strength decomposition.
+    """
+    return PerformanceConfig(
+        min_obs=252,
+        n_subperiods=4,
+        risk_free_rate=0.0,
+        rolling_window=63,
+        report_format="markdown",
+        attribution_quantiles=3,
+    )
+
+
+def compute_performance_metrics(
+    backtest_result: BacktestResult,
+    config: PerformanceConfig,
+) -> PerformanceResult:
+    """
+    Compute comprehensive performance metrics.
+
+    Parameters
+    ----------
+    backtest_result : BacktestResult
+        Backtest output with positions and P&L.
+    config : PerformanceConfig
+        Performance evaluation configuration.
+
+    Returns
+    -------
+    PerformanceResult
+        Complete performance analysis with metrics, attribution, and summary.
+
+    Notes
+    -----
+    Orchestrates all performance computations:
+    - Basic metrics: Sharpe, max drawdown, hit rate, trades
+    - Extended metrics: rolling Sharpe stability, recovery time, tail ratios
+    - Subperiod analysis: quarterly breakdown with full metrics per period
+    - Attribution: directional, signal strength, win/loss decomposition
+    - Stability score: consistency across subperiods
+    - Summary: interpretive text with key findings
+    """
+    return analyze_backtest_performance(backtest_result, config)
+
+
+def save_performance_report(
+    performance: PerformanceResult,
+    signal_name: str,
+    strategy_name: str,
+) -> None:
+    """
+    Generate and save performance report.
+
+    Parameters
+    ----------
+    performance : PerformanceResult
+        Performance analysis results.
+    signal_name : str
+        Name of signal.
+    strategy_name : str
+        Name of strategy.
+
+    Notes
+    -----
+    Generates markdown report with formatted tables and saves to
+    reports/performance/{signal}_{strategy}_{timestamp}.md.
+    Report includes all metrics, attribution breakdown, and summary.
+    """
+    report = generate_performance_report(
+        performance,
+        signal_id=signal_name,
+        strategy_id=strategy_name,
+        generate_tearsheet=False,
+    )
+    save_report(report, signal_name, strategy_name, DATA_WORKFLOWS_DIR / "reports")
+
+
+if __name__ == "__main__":
+    main()