aponyx 0.1.18__py3-none-any.whl

aponyx/evaluation/suitability/scoring.py

@@ -0,0 +1,367 @@
+"""
+Component scoring logic for suitability evaluation.
+
+Provides scoring functions for the four evaluation components and
+composite score computation.
+"""
+
+import logging
+
+from aponyx.evaluation.suitability.config import SuitabilityConfig
+
+logger = logging.getLogger(__name__)
+
+
+def score_data_health(
+    valid_obs: int,
+    missing_pct: float,
+    min_obs: int,
+) -> float:
+    """
+    Score data quality and sufficiency.
+
+    Parameters
+    ----------
+    valid_obs : int
+        Number of valid observations after alignment.
+    missing_pct : float
+        Percentage of missing data (0-100).
+    min_obs : int
+        Minimum required observations threshold.
+
+    Returns
+    -------
+    float
+        Data health score on 0-1 scale.
+        Returns 0.0 if insufficient observations.
+        Otherwise, penalizes missing data with tolerance up to 20%.
+
+    Notes
+    -----
+    Scoring logic:
+    - If valid_obs < min_obs: score = 0.0 (insufficient data)
+    - Else: score = max(0, 1 - missing_pct / 20)
+      Capped at 0% (score=1.0) and 20% (score=0.0) missing.
+
+    Examples
+    --------
+    >>> score_data_health(600, 5.0, 500)  # 600 obs, 5% missing
+    0.75
+    >>> score_data_health(400, 0.0, 500)  # Below threshold
+    0.0
+    """
+    if valid_obs < min_obs:
+        logger.debug(
+            "Insufficient observations: %d < %d, score=0.0",
+            valid_obs,
+            min_obs,
+        )
+        return 0.0
+
+    # Penalize missing data, tolerating up to 20%
+    score = max(0.0, 1.0 - missing_pct / 20.0)
+
+    logger.debug(
+        "Data health: valid_obs=%d, missing_pct=%.2f%%, score=%.3f",
+        valid_obs,
+        missing_pct,
+        score,
+    )
+
+    return score
+
+
+def score_predictive(mean_abs_tstat: float) -> float:
+    """
+    Score predictive association strength.
+
+    Parameters
+    ----------
+    mean_abs_tstat : float
+        Mean absolute t-statistic across lags.
+
+    Returns
+    -------
+    float
+        Predictive score on 0-1 scale.
+        Normalized by dividing by 3.0 (capped at 1.0).
+
+    Notes
+    -----
+    Scoring logic:
+    - score = min(1.0, mean_abs_tstat / 3.0)
+    - t-stat > 2.0: Statistically significant at conventional levels
+    - t-stat > 3.0: Strong evidence (score capped at 1.0)
+
+    Examples
+    --------
+    >>> score_predictive(2.5)  # Significant
+    0.833
+    >>> score_predictive(4.0)  # Strong (capped)
+    1.0
+    """
+    score = min(1.0, mean_abs_tstat / 3.0)
+
+    logger.debug(
+        "Predictive association: mean |t-stat|=%.3f, score=%.3f",
+        mean_abs_tstat,
+        score,
+    )
+
+    return score
+
+
+def score_economic(effect_size_bps: float) -> float:
+    """
+    Score economic relevance based on effect size.
+
+    Parameters
+    ----------
+    effect_size_bps : float
+        Estimated impact in basis points per 1σ signal change.
+
+    Returns
+    -------
+    float
+        Economic score on 0-1 scale.
+
+    Notes
+    -----
+    Scoring thresholds:
+    - effect_size < 0.5 bps: Negligible → score = 0.2
+    - 0.5 ≤ effect_size < 2.0 bps: Moderate → score = 0.6
+    - effect_size ≥ 2.0 bps: Meaningful → score = 1.0
+
+    For CDX spreads, 2 bps is ~0.4% spread change (economically relevant).
+
+    Examples
+    --------
+    >>> score_economic(0.3)  # Negligible
+    0.2
+    >>> score_economic(1.5)  # Moderate
+    0.6
+    >>> score_economic(3.0)  # Meaningful
+    1.0
+    """
+    if effect_size_bps < 0.5:
+        score = 0.2
+        category = "negligible"
+    elif effect_size_bps < 2.0:
+        score = 0.6
+        category = "moderate"
+    else:
+        score = 1.0
+        category = "meaningful"
+
+    logger.debug(
+        "Economic relevance: effect_size=%.3f bps (%s), score=%.3f",
+        effect_size_bps,
+        category,
+        score,
+    )
+
+    return score
+
+
+def score_stability(
+    sign_consistency_ratio: float,
+    beta_cv: float,
+) -> float:
+    """
+    Score temporal stability based on rolling window statistics.
+
+    Parameters
+    ----------
+    sign_consistency_ratio : float
+        Proportion of rolling windows with same sign as aggregate beta (0-1).
+    beta_cv : float
+        Coefficient of variation of rolling betas (std / |mean|).
+
+    Returns
+    -------
+    float
+        Stability score on 0-1 scale.
+        Weighted average of sign consistency and magnitude stability scores.
+
+    Notes
+    -----
+    Scoring logic:
+
+    Sign Consistency Component (50% weight):
+    - ratio ≥ 0.8: score = 1.0 (highly consistent)
+    - 0.6 ≤ ratio < 0.8: score = 0.5 (moderately consistent)
+    - ratio < 0.6: score = 0.0 (inconsistent)
+
+    Magnitude Stability Component (50% weight):
+    - CV < 0.5: score = 1.0 (stable magnitude)
+    - 0.5 ≤ CV < 1.0: score = 0.5 (moderate variation)
+    - CV ≥ 1.0: score = 0.0 (high variation)
+
+    Final score = 0.5 × sign_score + 0.5 × magnitude_score
+
+    Examples
+    --------
+    >>> score_stability(0.85, 0.3)  # High consistency, low CV
+    1.0
+    >>> score_stability(0.75, 0.6)  # Moderate both
+    0.5
+    >>> score_stability(0.5, 1.2)   # Low consistency, high CV
+    0.0
+    """
+    # Score sign consistency
+    if sign_consistency_ratio >= 0.8:
+        sign_score = 1.0
+        sign_category = "highly consistent"
+    elif sign_consistency_ratio >= 0.6:
+        sign_score = 0.5
+        sign_category = "moderately consistent"
+    else:
+        sign_score = 0.0
+        sign_category = "inconsistent"
+
+    # Score magnitude stability (lower CV = more stable)
+    if beta_cv < 0.5:
+        magnitude_score = 1.0
+        magnitude_category = "stable"
+    elif beta_cv < 1.0:
+        magnitude_score = 0.5
+        magnitude_category = "moderate variation"
+    else:
+        magnitude_score = 0.0
+        magnitude_category = "high variation"
+
+    # Weighted average (equal weights)
+    score = 0.5 * sign_score + 0.5 * magnitude_score
+
+    logger.debug(
+        "Temporal stability: sign_ratio=%.3f (%s, score=%.1f), "
+        "CV=%.3f (%s, score=%.1f), final_score=%.3f",
+        sign_consistency_ratio,
+        sign_category,
+        sign_score,
+        beta_cv,
+        magnitude_category,
+        magnitude_score,
+        score,
+    )
+
+    return score
+
+
+def compute_composite_score(
+    data_health_score: float,
+    predictive_score: float,
+    economic_score: float,
+    stability_score: float,
+    config: SuitabilityConfig,
+) -> float:
+    """
+    Compute weighted composite score from component scores.
+
+    Parameters
+    ----------
+    data_health_score : float
+        Data quality score (0-1).
+    predictive_score : float
+        Predictive association score (0-1).
+    economic_score : float
+        Economic relevance score (0-1).
+    stability_score : float
+        Temporal stability score (0-1).
+    config : SuitabilityConfig
+        Configuration with component weights.
+
+    Returns
+    -------
+    float
+        Composite score on 0-1 scale (weighted average).
+
+    Notes
+    -----
+    Default weights:
+    - Data health: 20%
+    - Predictive: 40%
+    - Economic: 20%
+    - Stability: 20%
+
+    Examples
+    --------
+    >>> config = SuitabilityConfig()
+    >>> compute_composite_score(0.8, 0.9, 0.6, 1.0, config)
+    0.82
+    """
+    composite = (
+        config.data_health_weight * data_health_score
+        + config.predictive_weight * predictive_score
+        + config.economic_weight * economic_score
+        + config.stability_weight * stability_score
+    )
+
+    logger.debug(
+        "Composite score: %.3f = %.2f×%.3f + %.2f×%.3f + %.2f×%.3f + %.2f×%.3f",
+        composite,
+        config.data_health_weight,
+        data_health_score,
+        config.predictive_weight,
+        predictive_score,
+        config.economic_weight,
+        economic_score,
+        config.stability_weight,
+        stability_score,
+    )
+
+    return composite
+
+
+def assign_decision(
+    composite_score: float,
+    config: SuitabilityConfig,
+) -> str:
+    """
+    Assign decision based on composite score and thresholds.
+
+    Parameters
+    ----------
+    composite_score : float
+        Composite score (0-1).
+    config : SuitabilityConfig
+        Configuration with decision thresholds.
+
+    Returns
+    -------
+    str
+        Decision: "PASS", "HOLD", or "FAIL".
+
+    Notes
+    -----
+    Decision logic:
+    - score ≥ pass_threshold (0.7): PASS → proceed to backtest
+    - pass_threshold > score ≥ hold_threshold (0.4): HOLD → marginal, requires judgment
+    - score < hold_threshold: FAIL → do not backtest
+
+    Examples
+    --------
+    >>> config = SuitabilityConfig()
+    >>> assign_decision(0.75, config)
+    'PASS'
+    >>> assign_decision(0.55, config)
+    'HOLD'
+    >>> assign_decision(0.35, config)
+    'FAIL'
+    """
+    if composite_score >= config.pass_threshold:
+        decision = "PASS"
+    elif composite_score >= config.hold_threshold:
+        decision = "HOLD"
+    else:
+        decision = "FAIL"
+
+    logger.debug(
+        "Decision assignment: score=%.3f, pass_threshold=%.2f, hold_threshold=%.2f → %s",
+        composite_score,
+        config.pass_threshold,
+        config.hold_threshold,
+        decision,
+    )
+
+    return decision

aponyx/evaluation/suitability/tests.py

@@ -0,0 +1,303 @@
+"""
+Statistical tests for signal-target relationships.
+
+Provides correlation, regression, and temporal stability tests for
+evaluating predictive associations.
+"""
+
+import logging
+
+import numpy as np
+import pandas as pd
+import statsmodels.api as sm
+
+logger = logging.getLogger(__name__)
+
+
+def compute_correlation(
+    signal: pd.Series,
+    target: pd.Series,
+) -> float:
+    """
+    Compute Pearson correlation between signal and target.
+
+    Parameters
+    ----------
+    signal : pd.Series
+        Signal time series.
+    target : pd.Series
+        Target time series (must be aligned with signal).
+
+    Returns
+    -------
+    float
+        Pearson correlation coefficient (-1 to 1).
+
+    Notes
+    -----
+    Returns 0.0 if either series has zero variance or contains NaN values.
+
+    Examples
+    --------
+    >>> signal = pd.Series([1, 2, 3, 4, 5])
+    >>> target = pd.Series([2, 4, 6, 8, 10])
+    >>> compute_correlation(signal, target)
+    1.0
+    """
+    if len(signal) == 0 or len(target) == 0:
+        logger.warning("Empty series provided, returning correlation=0.0")
+        return 0.0
+
+    if signal.std() == 0 or target.std() == 0:
+        logger.warning("Zero variance in series, returning correlation=0.0")
+        return 0.0
+
+    corr = signal.corr(target)
+    if pd.isna(corr):
+        logger.warning("NaN correlation (insufficient data), returning 0.0")
+        return 0.0
+
+    logger.debug("Computed correlation: %.4f", corr)
+    return float(corr)
+
+
+def compute_regression_stats(
+    signal: pd.Series,
+    target: pd.Series,
+) -> dict[str, float]:
+    """
+    Compute OLS regression statistics for signal predicting target.
+
+    Runs ordinary least squares regression: target ~ signal
+
+    Parameters
+    ----------
+    signal : pd.Series
+        Independent variable (predictor).
+    target : pd.Series
+        Dependent variable (response).
+
+    Returns
+    -------
+    dict[str, float]
+        Dictionary with keys:
+        - 'beta': regression coefficient
+        - 't_stat': t-statistic for beta
+        - 'p_value': p-value for beta
+        - 'r_squared': coefficient of determination
+
+    Notes
+    -----
+    Uses statsmodels OLS with constant term (intercept).
+    Returns zeros if regression fails due to insufficient data or numerical issues.
+
+    Examples
+    --------
+    >>> signal = pd.Series([1, 2, 3, 4, 5])
+    >>> target = pd.Series([2, 4, 6, 8, 10])
+    >>> stats = compute_regression_stats(signal, target)
+    >>> stats['beta']
+    2.0
+    """
+    if len(signal) < 3 or len(target) < 3:
+        logger.warning(
+            "Insufficient observations for regression (n=%d), returning zeros",
+            len(signal),
+        )
+        return {"beta": 0.0, "t_stat": 0.0, "p_value": 1.0, "r_squared": 0.0}
+
+    try:
+        # Add constant for intercept
+        X = sm.add_constant(signal.values)
+        y = target.values
+
+        # Fit OLS model
+        model = sm.OLS(y, X).fit()
+
+        # Extract statistics for signal coefficient (index 1, after constant)
+        beta = float(model.params[1])
+        t_stat = float(model.tvalues[1])
+        p_value = float(model.pvalues[1])
+        r_squared = float(model.rsquared)
+
+        logger.debug(
+            "Regression: beta=%.4f, t=%.4f, p=%.4f, R²=%.4f",
+            beta,
+            t_stat,
+            p_value,
+            r_squared,
+        )
+
+        return {
+            "beta": beta,
+            "t_stat": t_stat,
+            "p_value": p_value,
+            "r_squared": r_squared,
+        }
+
+    except Exception as e:
+        logger.warning("Regression failed: %s, returning zeros", e)
+        return {"beta": 0.0, "t_stat": 0.0, "p_value": 1.0, "r_squared": 0.0}
+
+
+def compute_rolling_betas(
+    signal: pd.Series,
+    target: pd.Series,
+    window: int,
+) -> pd.Series:
+    """
+    Compute rolling regression betas using sliding window.
+
+    Parameters
+    ----------
+    signal : pd.Series
+        Signal time series with DatetimeIndex.
+    target : pd.Series
+        Target time series with DatetimeIndex (aligned with signal).
+    window : int
+        Rolling window size in observations (e.g., 252 for ~1 year daily data).
+
+    Returns
+    -------
+    pd.Series
+        Time series of rolling beta coefficients.
+        Index matches input series; first (window-1) values are NaN.
+
+    Notes
+    -----
+    Uses OLS regression in each window: target ~ signal + constant.
+    Minimum window size is 50 observations for reliable estimation.
+
+    Implementation uses rolling window with apply to compute regression
+    beta coefficient in each window.
+
+    Examples
+    --------
+    >>> signal = pd.Series([...], index=date_range)
+    >>> target = pd.Series([...], index=date_range)
+    >>> rolling_betas = compute_rolling_betas(signal, target, window=252)
+    >>> rolling_betas.mean()  # Average beta across all windows
+    """
+    if len(signal) < window:
+        logger.warning(
+            "Insufficient data for rolling window (n=%d < window=%d), returning empty series",
+            len(signal),
+            window,
+        )
+        return pd.Series([], dtype=float, index=signal.index[:0])
+
+    # Preallocate result array
+    betas = np.full(len(signal), np.nan)
+
+    # Compute beta for each window
+    for i in range(window - 1, len(signal)):
+        window_signal = signal.iloc[i - window + 1 : i + 1]
+        window_target = target.iloc[i - window + 1 : i + 1]
+
+        if len(window_signal) < 3:
+            continue
+
+        try:
+            X = sm.add_constant(window_signal.values)
+            y = window_target.values
+            model = sm.OLS(y, X).fit()
+            betas[i] = float(model.params[1])
+        except Exception:
+            pass  # Keep as NaN
+
+    rolling_betas = pd.Series(betas, index=signal.index, name=signal.name)
+
+    logger.debug(
+        "Computed %d rolling betas (window=%d, valid=%d)",
+        len(rolling_betas),
+        window,
+        rolling_betas.notna().sum(),
+    )
+
+    return rolling_betas
+
+
+def compute_stability_metrics(
+    rolling_betas: pd.Series,
+    aggregate_beta: float,
+) -> dict[str, float]:
+    """
+    Compute stability metrics from rolling beta coefficients.
+
+    Parameters
+    ----------
+    rolling_betas : pd.Series
+        Time series of rolling beta coefficients from compute_rolling_betas().
+    aggregate_beta : float
+        Overall beta coefficient from full-sample regression.
+        Used as reference for sign consistency check.
+
+    Returns
+    -------
+    dict[str, float]
+        Dictionary with keys:
+        - 'sign_consistency_ratio': Proportion of windows matching aggregate sign
+        - 'beta_cv': Coefficient of variation (std / |mean|)
+        - 'n_windows': Number of valid rolling windows
+
+    Notes
+    -----
+    Sign consistency ratio ≥ 0.8 indicates stable directional relationship.
+    Beta CV < 0.5 indicates low magnitude variation (stable effect size).
+
+    Windows with beta ≈ 0 (|beta| < 0.01) are excluded from sign consistency
+    to avoid spurious sign flips in noise.
+
+    Examples
+    --------
+    >>> rolling_betas = pd.Series([1.5, 1.8, 1.6, 1.7, 1.9])
+    >>> aggregate_beta = 1.7
+    >>> metrics = compute_stability_metrics(rolling_betas, aggregate_beta)
+    >>> metrics['sign_consistency_ratio']
+    1.0  # All same sign
+    >>> metrics['beta_cv']
+    0.08  # Low variation
+    """
+    # Remove NaN values
+    valid_betas = rolling_betas.dropna()
+
+    if len(valid_betas) == 0:
+        logger.warning("No valid rolling betas, returning zero metrics")
+        return {
+            "sign_consistency_ratio": 0.0,
+            "beta_cv": 0.0,
+            "n_windows": 0,
+        }
+
+    # Sign consistency: proportion of windows with same sign as aggregate
+    aggregate_sign = np.sign(aggregate_beta)
+
+    # Filter out near-zero betas (|beta| < 0.01) to avoid noise
+    non_zero_mask = np.abs(valid_betas) >= 0.01
+    if non_zero_mask.sum() == 0:
+        sign_consistency_ratio = 0.0
+    else:
+        same_sign = (np.sign(valid_betas[non_zero_mask]) == aggregate_sign).sum()
+        sign_consistency_ratio = float(same_sign / non_zero_mask.sum())
+
+    # Coefficient of variation: std / |mean|
+    beta_mean = valid_betas.mean()
+    beta_std = valid_betas.std()
+
+    if abs(beta_mean) < 1e-10:
+        beta_cv = 0.0
+    else:
+        beta_cv = float(beta_std / abs(beta_mean))
+
+    logger.debug(
+        "Stability metrics: sign_ratio=%.3f, CV=%.3f, n_windows=%d",
+        sign_consistency_ratio,
+        beta_cv,
+        len(valid_betas),
+    )
+
+    return {
+        "sign_consistency_ratio": sign_consistency_ratio,
+        "beta_cv": beta_cv,
+        "n_windows": len(valid_betas),
+    }

aponyx/examples/01_generate_synthetic_data.py

@@ -0,0 +1,53 @@
+"""
+Generate synthetic market data for all instruments.
+
+Prerequisites
+-------------
+None — this is the first step in the workflow.
+
+Outputs
+-------
+Raw synthetic data files in data/raw/synthetic/:
+- cdx_ig_5y_{hash}.parquet (CDX spread data)
+- cdx_ig_10y_{hash}.parquet (CDX spread data)
+- cdx_hy_5y_{hash}.parquet (CDX spread data)
+- itrx_xover_5y_{hash}.parquet (CDX spread data)
+- itrx_eur_5y_{hash}.parquet (CDX spread data)
+- vix_{hash}.parquet (VIX volatility index)
+- hyg_{hash}.parquet (High yield ETF spreads)
+- lqd_{hash}.parquet (Investment grade ETF spreads)
+
+Each file includes metadata JSON with generation parameters.
+
+Examples
+--------
+Run from project root:
+    python -m aponyx.examples.01_generate_synthetic_data
+
+Expected output: 8 parquet files with 5 years of daily data (~1260 rows each).
+"""
+
+from aponyx.config import RAW_DIR
+from aponyx.data.sample_data import generate_for_fetch_interface
+
+
+def main() -> None:
+    """
+    Generate synthetic market data for testing and demonstrations.
+
+    Creates realistic time series data for all instruments defined in
+    bloomberg_securities.json, using hash-based naming compatible with
+    the data fetch interface.
+    """
+    output_dir = RAW_DIR / "synthetic"
+
+    generate_for_fetch_interface(
+        output_dir=output_dir,
+        start_date="2020-01-01",
+        end_date="2025-01-01",
+        seed=42,
+    )
+
+
+if __name__ == "__main__":
+    main()