aponyx 0.1.18__py3-none-any.whl

aponyx/examples/08_visualize_results.py

@@ -0,0 +1,272 @@
+"""
+Generate visualization charts for backtest results.
+
+Prerequisites
+-------------
+Backtest results saved from backtest execution (06_run_backtest.py):
+- P&L file: data/workflows/backtests/{signal}_{strategy}_pnl.parquet
+- Positions file: data/workflows/backtests/{signal}_{strategy}_positions.parquet
+
+Outputs
+-------
+Three Plotly figure objects:
+- Equity curve: cumulative P&L over time
+- Drawdown chart: underwater equity visualization
+- Signal plot: time series of signal values with thresholds
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.08_visualize_results
+
+Expected output: Three interactive Plotly charts displayed or saved.
+Figures can be rendered in notebooks, Streamlit apps, or exported to HTML.
+"""
+
+import pandas as pd
+import plotly.graph_objects as go
+
+from aponyx.config import DATA_WORKFLOWS_DIR
+from aponyx.persistence import load_parquet
+from aponyx.visualization import plot_equity_curve, plot_drawdown, plot_signal
+
+
+def main() -> dict[str, go.Figure]:
+    """
+    Execute visualization workflow.
+
+    Loads backtest results and generates three key charts:
+    equity curve, drawdown, and signal time series.
+
+    Returns
+    -------
+    dict[str, go.Figure]
+        Dictionary of figure names to Plotly figure objects.
+
+    Notes
+    -----
+    Figures are returned for flexible rendering (Streamlit, Jupyter, HTML).
+    To display in Jupyter: fig.show()
+    To save to HTML: fig.write_html("output.html")
+    To display in Streamlit: st.plotly_chart(fig)
+    """
+    signal_name, strategy_name = define_visualization_parameters()
+    pnl, positions = load_backtest_data(signal_name, strategy_name)
+    return generate_all_charts(pnl, positions, signal_name, strategy_name)
+
+
+def define_visualization_parameters() -> tuple[str, str]:
+    """
+    Define visualization 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_data(
+    signal_name: str,
+    strategy_name: str,
+) -> tuple[pd.DataFrame, pd.DataFrame]:
+    """
+    Load P&L and positions from backtest results.
+
+    Parameters
+    ----------
+    signal_name : str
+        Name of signal.
+    strategy_name : str
+        Name of strategy.
+
+    Returns
+    -------
+    tuple[pd.DataFrame, pd.DataFrame]
+        P&L DataFrame and positions DataFrame.
+
+    Notes
+    -----
+    Loads data saved by 06_run_backtest.py from processed directory.
+    P&L DataFrame contains net_pnl column for equity curve.
+    Positions DataFrame contains signal column for signal plot.
+    """
+    backtests_dir = DATA_WORKFLOWS_DIR / "backtests"
+
+    pnl_path = backtests_dir / f"{signal_name}_{strategy_name}_pnl.parquet"
+    positions_path = backtests_dir / f"{signal_name}_{strategy_name}_positions.parquet"
+
+    pnl = load_parquet(pnl_path)
+    positions = load_parquet(positions_path)
+
+    return pnl, positions
+
+
+def generate_all_charts(
+    pnl: pd.DataFrame,
+    positions: pd.DataFrame,
+    signal_name: str,
+    strategy_name: str,
+) -> dict[str, go.Figure]:
+    """
+    Generate all visualization charts.
+
+    Parameters
+    ----------
+    pnl : pd.DataFrame
+        P&L data with net_pnl column.
+    positions : pd.DataFrame
+        Positions data with signal column.
+    signal_name : str
+        Signal name for titles.
+    strategy_name : str
+        Strategy name for titles.
+
+    Returns
+    -------
+    dict[str, go.Figure]
+        Dictionary with keys: equity_curve, drawdown, signal.
+
+    Notes
+    -----
+    Charts are configured for research presentation:
+    - Equity curve shows drawdown shading for regime visualization
+    - Drawdown uses underwater chart format (absolute dollars)
+    - Signal includes ±2 threshold lines for regime boundaries
+    """
+    figures = {}
+
+    figures["equity_curve"] = create_equity_curve(
+        pnl,
+        signal_name,
+        strategy_name,
+    )
+
+    figures["drawdown"] = create_drawdown_chart(
+        pnl,
+        signal_name,
+        strategy_name,
+    )
+
+    figures["signal"] = create_signal_chart(
+        positions,
+        signal_name,
+    )
+
+    return figures
+
+
+def create_equity_curve(
+    pnl: pd.DataFrame,
+    signal_name: str,
+    strategy_name: str,
+) -> go.Figure:
+    """
+    Create equity curve chart with drawdown shading.
+
+    Parameters
+    ----------
+    pnl : pd.DataFrame
+        P&L data with net_pnl column.
+    signal_name : str
+        Signal name for title.
+    strategy_name : str
+        Strategy name for title.
+
+    Returns
+    -------
+    go.Figure
+        Plotly equity curve figure.
+
+    Notes
+    -----
+    Uses net_pnl column for cumulative P&L calculation.
+    Drawdown shading highlights underwater periods in red.
+    """
+    title = f"Equity Curve: {signal_name} ({strategy_name})"
+    return plot_equity_curve(
+        pnl["net_pnl"],
+        title=title,
+        show_drawdown_shading=True,
+    )
+
+
+def create_drawdown_chart(
+    pnl: pd.DataFrame,
+    signal_name: str,
+    strategy_name: str,
+) -> go.Figure:
+    """
+    Create drawdown chart showing peak-to-trough decline.
+
+    Parameters
+    ----------
+    pnl : pd.DataFrame
+        P&L data with net_pnl column.
+    signal_name : str
+        Signal name for title.
+    strategy_name : str
+        Strategy name for title.
+
+    Returns
+    -------
+    go.Figure
+        Plotly drawdown figure.
+
+    Notes
+    -----
+    Uses underwater chart format (absolute dollars).
+    Drawdown is always non-positive (zero at peaks, negative otherwise).
+    """
+    title = f"Drawdown: {signal_name} ({strategy_name})"
+    return plot_drawdown(
+        pnl["net_pnl"],
+        title=title,
+        show_underwater_chart=True,
+    )
+
+
+def create_signal_chart(
+    positions: pd.DataFrame,
+    signal_name: str,
+) -> go.Figure:
+    """
+    Create signal time series chart with threshold lines.
+
+    Parameters
+    ----------
+    positions : pd.DataFrame
+        Positions data with signal column.
+    signal_name : str
+        Signal name for title.
+
+    Returns
+    -------
+    go.Figure
+        Plotly signal figure.
+
+    Notes
+    -----
+    Threshold lines at ±2 mark typical entry/exit levels.
+    Signal convention: positive = long credit risk (buy CDX).
+    """
+    title = f"Signal: {signal_name}"
+    signal = positions["signal"]
+    signal.name = signal_name
+
+    return plot_signal(
+        signal,
+        title=title,
+        threshold_lines=[-2.0, 2.0],
+    )
+
+
+if __name__ == "__main__":
+    main()

aponyx/main.py

@@ -0,0 +1,7 @@
+def main() -> None:
+    """Main entry point."""
+    print("Hello from aponyx!")
+
+
+if __name__ == "__main__":
+    main()

aponyx/models/__init__.py

@@ -0,0 +1,45 @@
+"""
+Models layer for systematic credit strategies.
+
+This module provides signal generation via the four-stage transformation pipeline:
+Security → Indicator → Score → Signal → Position
+
+Module Organization:
+-------------------
+metadata.py         - Metadata dataclasses (SignalMetadata, IndicatorMetadata, TransformationMetadata, SignalTransformationMetadata)
+registry.py         - Registry classes for catalog management (IndicatorTransformationRegistry, ScoreTransformationRegistry, SignalTransformationRegistry, SignalRegistry)
+orchestrator.py     - compute_registered_signals() batch computation
+signal_composer.py  - compose_signal() four-stage pipeline composition
+indicators.py       - Indicator compute functions
+config.py           - SignalConfig dataclass
+"""
+
+from .config import SignalConfig
+from .metadata import (
+    CatalogValidationError,
+    IndicatorMetadata,
+    SignalMetadata,
+    SignalTransformationMetadata,
+    TransformationMetadata,
+)
+from .orchestrator import compute_registered_signals
+from .registry import (
+    IndicatorTransformationRegistry,
+    ScoreTransformationRegistry,
+    SignalRegistry,
+    SignalTransformationRegistry,
+)
+
+__all__ = [
+    "CatalogValidationError",
+    "IndicatorMetadata",
+    "IndicatorTransformationRegistry",
+    "ScoreTransformationRegistry",
+    "SignalConfig",
+    "SignalMetadata",
+    "SignalRegistry",
+    "SignalTransformationMetadata",
+    "SignalTransformationRegistry",
+    "TransformationMetadata",
+    "compute_registered_signals",
+]

aponyx/models/config.py

@@ -0,0 +1,83 @@
+"""
+Configuration dataclasses for indicator and signal generation.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class IndicatorConfig:
+    """
+    Runtime configuration parameters for indicator computation.
+
+    Note: Most indicator parameters are defined at catalog-time in IndicatorMetadata.
+    This config is for runtime overrides and caching behavior.
+
+    Attributes
+    ----------
+    use_cache : bool
+        Whether to use cached indicator values if available.
+    force_recompute : bool
+        Force recomputation even if cache exists.
+    """
+
+    use_cache: bool = True
+    force_recompute: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate configuration parameters."""
+        if self.use_cache and self.force_recompute:
+            raise ValueError("Cannot set both use_cache and force_recompute to True")
+
+
+@dataclass(frozen=True)
+class TransformationConfig:
+    """
+    Runtime configuration parameters for signal transformations.
+
+    Note: Most transformation parameters are defined at catalog-time in
+    TransformationMetadata. This config is for runtime behavior.
+
+    Attributes
+    ----------
+    min_valid_pct : float
+        Minimum percentage of valid (non-NaN) values required after transformation.
+        Values between 0.0 and 1.0. Default: 0.5 (50%)
+    """
+
+    min_valid_pct: float = 0.5
+
+    def __post_init__(self) -> None:
+        """Validate configuration parameters."""
+        if not 0.0 <= self.min_valid_pct <= 1.0:
+            raise ValueError(
+                f"min_valid_pct must be between 0.0 and 1.0, got {self.min_valid_pct}"
+            )
+
+
+@dataclass(frozen=True)
+class SignalConfig:
+    """
+    Configuration parameters for individual signal computation.
+
+    Attributes
+    ----------
+    lookback : int
+        Rolling window size for normalization and statistics.
+    min_periods : int
+        Minimum observations required for valid calculation.
+    """
+
+    lookback: int = 20
+    min_periods: int = 10
+
+    def __post_init__(self) -> None:
+        """Validate configuration parameters."""
+        if self.lookback <= 0:
+            raise ValueError(f"lookback must be positive, got {self.lookback}")
+        if self.min_periods <= 0:
+            raise ValueError(f"min_periods must be positive, got {self.min_periods}")
+        if self.min_periods > self.lookback:
+            raise ValueError(
+                f"min_periods ({self.min_periods}) cannot exceed lookback ({self.lookback})"
+            )

aponyx/models/indicator_transformation.json

@@ -0,0 +1,52 @@
+[
+  {
+    "name": "cdx_etf_spread_diff",
+    "description": "CDX spread minus ETF spread in basis points (raw basis without normalization)",
+    "compute_function_name": "compute_cdx_etf_spread_diff",
+    "data_requirements": {
+      "cdx": "spread",
+      "etf": "spread"
+    },
+    "default_securities": {
+      "cdx": "cdx_ig_5y",
+      "etf": "lqd"
+    },
+    "output_units": "basis_points",
+    "parameters": {},
+    "enabled": true
+  },
+  {
+    "name": "spread_momentum_5d",
+    "description": "5-day spread change in basis points (short-term momentum without volatility adjustment)",
+    "compute_function_name": "compute_spread_momentum",
+    "data_requirements": {
+      "cdx": "spread"
+    },
+    "default_securities": {
+      "cdx": "cdx_ig_5y"
+    },
+    "output_units": "basis_points",
+    "parameters": {
+      "lookback": 5
+    },
+    "enabled": true
+  },
+  {
+    "name": "cdx_vix_deviation_gap_20d",
+    "description": "Gap between CDX and VIX deviations from 20-day means (cross-asset risk sentiment)",
+    "compute_function_name": "compute_cdx_vix_deviation_gap",
+    "data_requirements": {
+      "cdx": "spread",
+      "vix": "level"
+    },
+    "default_securities": {
+      "cdx": "cdx_ig_5y",
+      "vix": "vix"
+    },
+    "output_units": "basis_points",
+    "parameters": {
+      "lookback": 20
+    },
+    "enabled": true
+  }
+]