aponyx 0.1.18__py3-none-any.whl

aponyx/examples/02_fetch_data_file.py

@@ -0,0 +1,82 @@
+"""
+Load all market data instruments from file sources.
+
+Prerequisites
+-------------
+Raw data files must exist in data/raw/synthetic/ with registry.json:
+- cdx_ig_5y_{hash}.parquet (CDX IG 5Y spreads)
+- cdx_ig_10y_{hash}.parquet (CDX IG 10Y spreads)
+- cdx_hy_5y_{hash}.parquet (CDX HY 5Y spreads)
+- itrx_xover_5y_{hash}.parquet (iTraxx Crossover 5Y spreads)
+- itrx_eur_5y_{hash}.parquet (iTraxx Europe 5Y spreads)
+- vix_{hash}.parquet (VIX volatility index)
+- hyg_{hash}.parquet (HYG high yield ETF)
+- lqd_{hash}.parquet (LQD investment grade ETF)
+- registry.json (security-to-file mapping)
+
+Run scripts/generate_synthetic.py first if files don't exist.
+
+Outputs
+-------
+Validated DataFrames for each instrument:
+- CDX instruments: spread column with DatetimeIndex
+- VIX: level column with DatetimeIndex
+- ETF instruments: close column with DatetimeIndex
+
+All data validated against schema expectations.
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.02_fetch_data_file
+
+Expected output: Eight validated DataFrames with ~1260 rows each.
+"""
+
+import pandas as pd
+
+from aponyx.config import RAW_DIR
+from aponyx.data import fetch_cdx, fetch_vix, fetch_etf, FileSource
+from aponyx.data.bloomberg_config import list_securities
+
+
+def main() -> dict[str, pd.DataFrame]:
+    """
+    Load and validate all market data from file sources.
+
+    Loads all instruments defined in bloomberg_securities.json from
+    the synthetic data directory. Uses FileSource with registry-based
+    lookup for security-to-file mapping.
+
+    Returns
+    -------
+    dict[str, pd.DataFrame]
+        Dictionary mapping security IDs to validated DataFrames.
+    """
+    synthetic_dir = RAW_DIR / "synthetic"
+
+    # Initialize FileSource with registry (auto-loads registry.json)
+    source = FileSource(synthetic_dir)
+
+    data = {}
+
+    # Load CDX instruments
+    cdx_securities = list_securities(instrument_type="cdx")
+    for security in cdx_securities:
+        df = fetch_cdx(source, security=security)
+        data[security] = df
+
+    # Load VIX
+    data["vix"] = fetch_vix(source, security="vix")
+
+    # Load ETF instruments
+    etf_securities = list_securities(instrument_type="etf")
+    for security in etf_securities:
+        df = fetch_etf(source, security=security)
+        data[security] = df
+
+    return data
+
+
+if __name__ == "__main__":
+    main()

aponyx/examples/03_fetch_data_bloomberg.py

@@ -0,0 +1,104 @@
+"""
+Load all market data instruments from Bloomberg Terminal.
+
+Prerequisites
+-------------
+Active Bloomberg Terminal session required.
+Bloomberg securities configured in data/bloomberg_securities.json:
+- CDX instruments (IG 5Y, IG 10Y, HY 5Y, iTraxx Europe 5Y, iTraxx Crossover 5Y)
+- VIX volatility index
+- Credit ETFs (HYG, LQD)
+
+Note: Bloomberg data is automatically saved to data/raw/bloomberg/ with
+hash-based naming for permanent storage.
+
+Outputs
+-------
+Validated DataFrames for each instrument:
+- CDX instruments: spread column with DatetimeIndex
+- VIX: close column with DatetimeIndex
+- ETF instruments: close column with DatetimeIndex
+
+Data saved to:
+- Raw storage: data/raw/bloomberg/{security}_{hash}.parquet (permanent)
+- Cache: data/cache/bloomberg_{instrument}_{hash}.parquet (temporary)
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.03_fetch_data_bloomberg
+
+Expected output: Eight validated DataFrames with historical data.
+Date range depends on Bloomberg data availability (typically 5+ years).
+"""
+
+from datetime import datetime, timedelta
+
+import pandas as pd
+
+from aponyx.data import fetch_cdx, fetch_vix, fetch_etf, BloombergSource
+from aponyx.data.bloomberg_config import list_securities
+
+
+def main() -> dict[str, pd.DataFrame]:
+    """
+    Load and validate all market data from Bloomberg Terminal.
+
+    Fetches all securities defined in bloomberg_securities.json.
+    Uses fetch interface with BloombergSource for automatic validation,
+    caching, and raw storage.
+
+    Returns
+    -------
+    dict[str, pd.DataFrame]
+        Dictionary mapping security IDs to validated DataFrames.
+
+    Notes
+    -----
+    Data is automatically saved to raw/bloomberg/ for permanent storage.
+    Subsequent calls use cache unless data is stale (see CACHE_TTL_DAYS config).
+    """
+    from aponyx.data.bloomberg_config import get_security_spec
+
+    end_date = datetime.now().strftime("%Y-%m-%d")
+    start_date = (datetime.now() - timedelta(days=5 * 365)).strftime("%Y-%m-%d")
+
+    source = BloombergSource()
+    data = {}
+
+    # Load all securities from catalog
+    all_securities = list_securities()
+    for security_id in all_securities:
+        spec = get_security_spec(security_id)
+        instrument_type = spec.instrument_type
+
+        if instrument_type == "vix":
+            df = fetch_vix(
+                source,
+                start_date=start_date,
+                end_date=end_date,
+            )
+        elif instrument_type == "etf":
+            df = fetch_etf(
+                source,
+                security=security_id,
+                start_date=start_date,
+                end_date=end_date,
+            )
+        elif instrument_type == "cdx":
+            df = fetch_cdx(
+                source,
+                security=security_id,
+                start_date=start_date,
+                end_date=end_date,
+            )
+        else:
+            raise ValueError(f"Unknown instrument type: {instrument_type}")
+
+        data[security_id] = df
+
+    return data
+
+
+if __name__ == "__main__":
+    main()

aponyx/examples/04_compute_signal.py

@@ -0,0 +1,164 @@
+"""
+Compute all enabled signals from catalog using market data.
+
+Prerequisites
+-------------
+Data fetched from previous step (02_fetch_data_file.py or 03_fetch_data_bloomberg.py):
+- Cached data in data/cache/{provider}/ for required instruments
+- Data registry populated with dataset entries
+
+Workflow
+--------
+1. Determine required data keys from ALL enabled signals
+2. Load all required market data once from registry
+3. Compute all enabled signals via four-stage transformation pipeline
+4. Individual signals then used separately for evaluation/backtesting
+
+Four-Stage Transformation Pipeline
+----------------------------------
+Security → Indicator → Score → Signal → Position
+
+1. Indicator Transformation: Compute economic metric (e.g., spread difference in bps)
+2. Score Transformation: Normalize indicator (e.g., z-score)
+3. Signal Transformation: Apply trading rules (floor, cap, neutral_range)
+4. Position Calculation: Backtest layer (out of scope for this script)
+
+Outputs
+-------
+Dict of computed signals (one pd.Series per enabled signal).
+Saved to data/workflows/signals/{signal_name}.parquet for next steps.
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.04_compute_signal
+
+Returns dict with signal names as keys and pd.Series as values.
+Expected: 3 signals (cdx_etf_basis, cdx_vix_gap, spread_momentum).
+"""
+
+import pandas as pd
+
+from aponyx.config import (
+    REGISTRY_PATH,
+    DATA_DIR,
+    SIGNAL_CATALOG_PATH,
+    DATA_WORKFLOWS_DIR,
+    INDICATOR_TRANSFORMATION_PATH,
+)
+from aponyx.data import DataRegistry
+from aponyx.models import SignalRegistry, compute_registered_signals
+from aponyx.models.registry import (
+    IndicatorTransformationRegistry,
+)
+from aponyx.persistence import save_parquet
+
+
+def main() -> dict[str, pd.Series]:
+    """
+    Execute batch signal computation workflow.
+
+    Loads all required market data from registry, then computes
+    all enabled signals via the four-stage transformation pipeline.
+
+    Returns
+    -------
+    dict[str, pd.Series]
+        Mapping from signal name to computed signal series.
+    """
+    market_data = load_all_required_data()
+    signals = compute_all_signals(market_data)
+    save_all_signals(signals)
+    return signals
+
+
+def load_all_required_data() -> dict[str, pd.DataFrame]:
+    """
+    Load all market data required by enabled signals.
+
+    Uses default_securities from each indicator's metadata to determine
+    which specific securities to load for each instrument type.
+
+    Returns
+    -------
+    dict[str, pd.DataFrame]
+        Market data mapping with all required instruments.
+        Keys are generic identifiers (e.g., "cdx", "etf", "vix").
+
+    Notes
+    -----
+    Collects data requirements from indicator_transformation.json
+    based on which indicators are referenced by enabled signals.
+    """
+    data_registry = DataRegistry(REGISTRY_PATH, DATA_DIR)
+    signal_registry = SignalRegistry(SIGNAL_CATALOG_PATH)
+    indicator_registry = IndicatorTransformationRegistry(INDICATOR_TRANSFORMATION_PATH)
+
+    # Build mapping from instrument type to security ID
+    # by collecting default_securities from indicators used by enabled signals
+    instrument_to_security: dict[str, str] = {}
+    for signal_name, signal_meta in signal_registry.get_enabled().items():
+        indicator_meta = indicator_registry.get_metadata(
+            signal_meta.indicator_transformation
+        )
+        for inst_type, security_id in indicator_meta.default_securities.items():
+            instrument_to_security[inst_type] = security_id
+
+    # Load data for each instrument type using the mapped security
+    market_data: dict[str, pd.DataFrame] = {}
+    for inst_type, security_id in sorted(instrument_to_security.items()):
+        df = data_registry.load_dataset_by_security(security_id)
+        market_data[inst_type] = df
+
+    return market_data
+
+
+def compute_all_signals(
+    market_data: dict[str, pd.DataFrame],
+) -> dict[str, pd.Series]:
+    """
+    Compute all enabled signals using four-stage transformation pipeline.
+
+    Parameters
+    ----------
+    market_data : dict[str, pd.DataFrame]
+        Complete market data with all required instruments.
+
+    Returns
+    -------
+    dict[str, pd.Series]
+        Mapping from signal name to computed signal series.
+
+    Notes
+    -----
+    Orchestrator computes ALL enabled signals in one pass via compose_signal().
+    Individual signals are then selected for evaluation/backtesting.
+    """
+    signal_registry = SignalRegistry(SIGNAL_CATALOG_PATH)
+    return compute_registered_signals(signal_registry, market_data)
+
+
+def save_all_signals(signals: dict[str, pd.Series]) -> None:
+    """
+    Save computed signals to workflows directory.
+
+    Parameters
+    ----------
+    signals : dict[str, pd.Series]
+        Mapping from signal name to computed signal series.
+
+    Notes
+    -----
+    Saves each signal as data/workflows/signals/{signal_name}.parquet.
+    """
+    signals_dir = DATA_WORKFLOWS_DIR / "signals"
+    signals_dir.mkdir(parents=True, exist_ok=True)
+
+    for signal_name, signal_series in signals.items():
+        signal_path = signals_dir / f"{signal_name}.parquet"
+        signal_df = signal_series.to_frame(name="value")
+        save_parquet(signal_df, signal_path)
+
+
+if __name__ == "__main__":
+    main()

aponyx/examples/05_evaluate_suitability.py

@@ -0,0 +1,224 @@
+"""
+Evaluate signal-product suitability before backtesting.
+
+Prerequisites
+-------------
+Signals saved from previous step (04_compute_signal.py):
+- Signal files exist in data/workflows/signals/{signal_name}.parquet
+- CDX spread data available from registry
+
+Outputs
+-------
+SuitabilityResult with decision and component scores:
+- Decision: PASS, HOLD, or FAIL
+- Component scores: data_health, predictive, economic, stability
+- Suitability report saved to data/workflows/reports/{signal_name}_{product}.md
+- Evaluation registered in suitability_registry.json
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.05_evaluate_suitability
+
+Expected output: SuitabilityResult with PASS/HOLD/FAIL decision.
+Report saved to data/workflows/reports/spread_momentum_cdx_ig_5y.md.
+"""
+
+import pandas as pd
+
+from aponyx.config import (
+    REGISTRY_PATH,
+    DATA_DIR,
+    DATA_WORKFLOWS_DIR,
+    SUITABILITY_REGISTRY_PATH,
+)
+from aponyx.data.registry import DataRegistry
+from aponyx.evaluation.suitability import (
+    SuitabilityConfig,
+    SuitabilityResult,
+    evaluate_signal_suitability,
+    compute_forward_returns,
+    generate_suitability_report,
+    save_report,
+    SuitabilityRegistry,
+)
+from aponyx.persistence import load_parquet
+
+
+def main() -> SuitabilityResult:
+    """
+    Execute suitability evaluation workflow.
+
+    Evaluates one signal against its target product using
+    4-component scoring framework.
+
+    Returns
+    -------
+    SuitabilityResult
+        Evaluation result with decision and component scores.
+    """
+    signal_name, product = define_evaluation_pair()
+    signal, target_change = prepare_evaluation_data(signal_name, product)
+    config = define_evaluation_config()
+    result = evaluate_suitability(signal, target_change, config)
+    save_and_register_evaluation(result, signal_name, product)
+    return result
+
+
+def define_evaluation_pair() -> tuple[str, str]:
+    """
+    Define signal-product pair for evaluation.
+
+    Returns
+    -------
+    tuple[str, str]
+        Signal name and product identifier.
+
+    Notes
+    -----
+    Choose one signal from catalog for demonstration.
+    In practice, evaluate all enabled signals separately.
+    """
+    signal_name = "spread_momentum"
+    product = "cdx_ig_5y"
+    return signal_name, product
+
+
+def prepare_evaluation_data(
+    signal_name: str,
+    product: str,
+) -> tuple[pd.Series, pd.Series]:
+    """
+    Load signal and compute target returns for evaluation.
+
+    Parameters
+    ----------
+    signal_name : str
+        Name of signal to load from processed directory.
+    product : str
+        Product identifier for target returns.
+
+    Returns
+    -------
+    tuple[pd.Series, pd.Series]
+        Signal series and target change series (aligned).
+
+    Notes
+    -----
+    Loads signal saved by previous step (04_compute_signal.py).
+    Target is forward spread change (positive = widening).
+    """
+    signal = load_signal(signal_name)
+    spread_df = load_spread_data(product)
+
+    # Compute forward returns for 1-day ahead (default evaluation horizon)
+    forward_returns = compute_forward_returns(spread_df["spread"], lags=[1])
+    target_change = forward_returns[1]
+
+    return signal, target_change
+
+
+def load_signal(signal_name: str) -> pd.Series:
+    """
+    Load signal from workflows 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.DataFrame:
+    """
+    Load spread data for target product.
+
+    Parameters
+    ----------
+    product : str
+        Product identifier (e.g., "cdx_ig_5y").
+
+    Returns
+    -------
+    pd.DataFrame
+        Spread data with DatetimeIndex.
+
+    Notes
+    -----
+    Uses DataRegistry.load_dataset_by_security() for efficient lookup.
+    """
+    data_registry = DataRegistry(REGISTRY_PATH, DATA_DIR)
+    return data_registry.load_dataset_by_security(product)
+
+
+def define_evaluation_config() -> SuitabilityConfig:
+    """
+    Define suitability evaluation configuration.
+
+    Returns
+    -------
+    SuitabilityConfig
+        Configuration with test parameters and thresholds.
+    """
+    return SuitabilityConfig()
+
+
+def evaluate_suitability(
+    signal: pd.Series,
+    target_change: pd.Series,
+    config: SuitabilityConfig,
+) -> SuitabilityResult:
+    """
+    Run suitability evaluation with 4-component scoring.
+
+    Parameters
+    ----------
+    signal : pd.Series
+        Signal to evaluate.
+    target_change : pd.Series
+        Forward target returns.
+    config : SuitabilityConfig
+        Evaluation configuration.
+
+    Returns
+    -------
+    SuitabilityResult
+        Evaluation result with decision and component scores.
+    """
+    return evaluate_signal_suitability(signal, target_change, config)
+
+
+def save_and_register_evaluation(
+    result: SuitabilityResult,
+    signal_name: str,
+    product: str,
+) -> None:
+    """
+    Save markdown report and register evaluation.
+
+    Parameters
+    ----------
+    result : SuitabilityResult
+        Evaluation result.
+    signal_name : str
+        Name of evaluated signal.
+    product : str
+        Product identifier.
+    """
+    report = generate_suitability_report(result, signal_name, product)
+    save_report(report, signal_name, product, DATA_WORKFLOWS_DIR / "reports")
+
+    registry = SuitabilityRegistry(SUITABILITY_REGISTRY_PATH)
+    registry.register_evaluation(result, signal_name, product)
+
+
+if __name__ == "__main__":
+    main()