aponyx 0.1.6

Systematic research framework for tactical credit strategies

Aponyx

A modular Python framework for developing and backtesting systematic credit strategies.

Aponyx provides a type-safe, reproducible research environment for tactical fixed-income strategies. Built for investment professionals who need clean separation between strategy logic, data infrastructure, and backtesting workflows.

Key Features

• Type-safe data loading with schema validation (Parquet, CSV, Bloomberg Terminal)
• Modular signal framework with composable transformations and registry management
• Deterministic backtesting with transaction cost modeling and comprehensive metrics
• Interactive visualization with Plotly charts (equity curves, signals, drawdown)
• Production-ready persistence with metadata tracking and versioning
• Strategy governance with centralized registry and configuration management

Installation

From PyPI (Recommended)

pip install aponyx

Optional dependencies:

# Visualization (Plotly, Streamlit)
pip install aponyx[viz]

# Bloomberg Terminal support (requires manual blpapi install)
pip install aponyx[bloomberg]

# Development tools
pip install aponyx[dev]

From Source

Requires Python 3.12 and uv:

git clone https://github.com/stabilefrisur/aponyx.git
cd aponyx
uv sync                    # Install dependencies
uv sync --extra viz        # Include visualization
uv run python -m aponyx.examples.backtest_demo

Bloomberg Terminal Setup (Optional)

Note: Bloomberg data loading requires an active Terminal session and manual blpapi installation.

1. Download blpapi from Bloomberg's API Library
2. Install: pip install path/to/blpapi-*.whl
3. Install Bloomberg extra: pip install aponyx[bloomberg]

File-based data loading (FileSource) works without Bloomberg dependencies.

Quick Start

from aponyx.data import fetch_cdx, fetch_etf, FileSource
from aponyx.models import compute_cdx_etf_basis, SignalConfig
from aponyx.backtest import run_backtest, BacktestConfig, compute_performance_metrics

# Load validated market data
cdx_df = fetch_cdx(FileSource("data/raw/cdx_data.parquet"), security="cdx_ig_5y")
etf_df = fetch_etf(FileSource("data/raw/etf_data.parquet"), security="hyg")

# Generate signal with configuration
signal_config = SignalConfig(lookback=20, min_periods=10)
signal = compute_cdx_etf_basis(cdx_df, etf_df, signal_config)

# Evaluate signal-product suitability (optional pre-backtest gate)
from aponyx.evaluation import evaluate_signal_suitability
result = evaluate_signal_suitability(signal, cdx_df["spread"])
if result.decision != "PASS":
    print(f"Signal evaluation: {result.decision} (score: {result.composite_score:.2f})")
    # Optionally skip backtest for low-quality signals

# Run backtest with transaction costs
backtest_config = BacktestConfig(
    entry_threshold=1.5,
    exit_threshold=0.75,
    transaction_cost_bps=1.0
)
results = run_backtest(signal, cdx_df["spread"], backtest_config)

# Compute performance metrics
metrics = compute_performance_metrics(results.pnl, results.positions)

# Analyze results
print(f"Sharpe Ratio: {metrics.sharpe_ratio:.2f}")
print(f"Max Drawdown: ${metrics.max_drawdown:,.0f}")
print(f"Hit Rate: {metrics.hit_rate:.2%}")

Bloomberg Terminal alternative:

from aponyx.data import BloombergSource

source = BloombergSource()
cdx_df = fetch_cdx(source, security="cdx_ig_5y")

Architecture

Aponyx follows a layered architecture with clean separation of concerns:

Layer	Purpose	Key Modules
Data	Load, validate, transform market data	fetch_cdx, fetch_vix, fetch_etf, FileSource, BloombergSource
Models	Generate signals for independent evaluation	compute_cdx_etf_basis, compute_cdx_vix_gap, SignalRegistry
Evaluation	Pre-backtest signal screening and quality gates	evaluate_signal_suitability, SuitabilityRegistry
Backtest	Simulate execution and compute metrics	run_backtest, BacktestConfig, StrategyRegistry
Visualization	Interactive charts and dashboards	plot_equity_curve, plot_signal, plot_drawdown
Persistence	Save/load data with metadata registry	save_parquet, load_parquet, DataRegistry

Research Workflow

Raw Data (Parquet/CSV/Bloomberg)
    ↓
Data Layer (load, validate, transform)
    ↓
Models Layer (signal computation)
    ↓
Evaluation Layer (signal-product suitability)
    ├─ PASS → Backtest Layer (simulation, metrics)
    │            ↓
    │         Visualization Layer (charts)
    │            ↓
    │         Persistence Layer (results)
    │
    └─ FAIL → Archive (no backtest)

Examples

Examples are included with the installed package and demonstrate specific workflows with synthetic data.

After installing via PyPI:

# Locate installed examples
python -c "from aponyx.examples import get_examples_dir; print(get_examples_dir())"

# Run examples as modules
python -m aponyx.examples.data_demo          # Data loading and validation
python -m aponyx.examples.models_demo        # Signal generation and catalog
python -m aponyx.examples.suitability_demo   # Pre-backtest signal screening
python -m aponyx.examples.backtest_demo      # Complete backtest workflow
python -m aponyx.examples.visualization_demo # Interactive charts (requires viz extra)
python -m aponyx.examples.persistence_demo   # Data I/O and registry
python -m aponyx.examples.bloomberg_demo     # Bloomberg Terminal integration

During development:

# Clone repo and run directly
git clone https://github.com/stabilefrisur/aponyx.git
cd aponyx
uv sync
uv run python -m aponyx.examples.backtest_demo

Research Notebooks

Complete workflow notebooks are included in the package for end-to-end research workflows.

Access installed notebooks:

# Locate notebook directory
from pathlib import Path
import aponyx
notebooks_dir = Path(aponyx.__file__).parent / "notebooks"
print(notebooks_dir)

Workflow notebooks:

Notebook	Description
01_data_download.ipynb	Download market data from Bloomberg Terminal
02_signal_computation.ipynb	Generate signals using SignalRegistry
03_suitability_evaluation.ipynb	Pre-backtest signal screening and evaluation
04_backtest.ipynb	Execute backtests and compute metrics (coming soon)
05_analysis.ipynb	Visualize results and generate reports (coming soon)

Usage:

# Copy notebooks to your workspace
pip install aponyx[viz]  # Install with notebook dependencies
python -c "from pathlib import Path; import aponyx, shutil; src = Path(aponyx.__file__).parent / 'notebooks'; shutil.copytree(src, 'notebooks')"
jupyter notebook notebooks/

Notebooks demonstrate the complete systematic research workflow from data acquisition through performance analysis.

Documentation

Documentation is included with the package and available after installation:

# Access docs programmatically
from aponyx.docs import get_docs_dir
docs_path = get_docs_dir()
print(docs_path)  # Path to installed documentation

Available documentation:

Document	Description
python_guidelines.md	Code standards and best practices
cdx_overlay_strategy.md	Investment thesis and pilot implementation
signal_registry_usage.md	Signal management workflow
signal_suitability_evaluation.md	Pre-backtest evaluation framework
visualization_design.md	Chart architecture and patterns
logging_design.md	Logging conventions and metadata
caching_design.md	Cache layer architecture
adding_data_providers.md	Provider extension guide
governance_design.md	Registry, catalog, and config patterns

During development, docs are also available on GitHub:

• Documentation Index

What's Included

Implemented

• ✅ Type-safe data loading with schema validation (Parquet, CSV, Bloomberg)
• ✅ Modular signal framework with registry and catalog management
• ✅ Deterministic backtesting with transaction costs and comprehensive metrics
• ✅ Interactive Plotly visualizations (equity curves, signals, drawdown)
• ✅ Strategy governance with centralized registry and versioning
• ✅ Metadata tracking and reproducibility controls
• ✅ Comprehensive test suite with >90% coverage

Pilot Signals

Three signals for CDX overlay strategies:

1. CDX-ETF Basis - Flow-driven mispricing from cash-derivative basis
2. CDX-VIX Gap - Cross-asset risk sentiment divergence
3. Spread Momentum - Short-term continuation in credit spreads

Roadmap

• 🔜 Streamlit dashboard (architecture defined, implementation pending)
• 🔜 Advanced attribution charts (performance decomposition)
• 🔜 Multi-asset portfolio backtesting
• 🔜 Position sizing and risk budgeting

Development

Running Tests

pytest                              # All tests
pytest --cov=aponyx                # With coverage
pytest tests/models/                # Specific module

Code Quality

black src/ tests/                   # Format code
ruff check src/ tests/              # Lint
mypy src/                          # Type check

All tools are configured in pyproject.toml with project-specific settings.

Design Philosophy

Core Principles

1. Modularity - Clean separation between data, models, backtest, and infrastructure
2. Reproducibility - Deterministic outputs with seed control and metadata logging
3. Type Safety - Strict type hints and runtime validation throughout
4. Simplicity - Prefer functions over classes, explicit over implicit
5. Transparency - Clear separation between strategy logic and execution

Signal Convention

All signals follow a consistent sign convention for interpretability:

• Positive values → Long credit risk (buy CDX = sell protection)
• Negative values → Short credit risk (sell CDX = buy protection)

This ensures clarity when evaluating signals independently or combining them in future research.

Requirements

• Python 3.12 (no backward compatibility with 3.11 or earlier)
• Modern type syntax (str | None, not Optional[str])
• Optional: Bloomberg Terminal with blpapi for live data

Contributing

Contributions welcome! This is a research framework under active development.

• Code standards: See Python Guidelines (or from aponyx.docs import get_docs_dir after install)
• Testing: All new features require unit tests
• Documentation: NumPy-style docstrings required

License

MIT License - see LICENSE for details.

Links

• PyPI: https://pypi.org/project/aponyx/
• Repository: https://github.com/stabilefrisur/aponyx
• Issues: https://github.com/stabilefrisur/aponyx/issues
• Changelog: https://github.com/stabilefrisur/aponyx/blob/master/CHANGELOG.md

---

Maintained by stabilefrisur Version: 0.1.6 Last Updated: November 9, 2025