---

name: spread-analysis-calculator description: Calculates price spreads, MoM% changes, and rolling z-scores for pair trading analysis. Implements statistical normalization with configurable parameters.

Skill: Spread Analysis Calculator

Purpose

Perform statistical analysis on price spreads between two financial instruments (e.g., WTI-Brent, gold-silver). Calculate spread values, month-over-month percentage changes, and rolling z-scores for pair trading strategies.

Core Workflow

1. Data Collection & Preparation

• Input: Two time-series datasets (e.g., WTI and Brent monthly closes)
• Action: Fetch data from specified sources (Yahoo Finance, CSV files, APIs)
• Output: Aligned, cleaned datasets with consistent timestamps

2. Spread Calculation

• Formula: Spread = Instrument_B - Instrument_A
• Precision: Round to 4 decimal places for prices, 2 decimal places for percentages

3. MoM% Calculation

• Formula: MoM% = (Current_Value / Previous_Value - 1) × 100%
• Handling: First month has null/None MoM value
• Apply to: Both individual instruments and the spread

4. Z-Score Calculation (Rolling Window)

• Window: Configurable (default: 6 periods)
• Statistics:
  • Mean: μ = Σx / n
  • Sample Std Dev: σ = √[Σ(x - μ)² / (n - 1)] (ddof=1)
  • Z-Score: z = (x - μ) / σ
• Edge Cases:
  • Return z = 0 if window has < 4 samples
  • Return z = 0 if standard deviation = 0
  • Clip z-scores to range [-3, 3]
• Output: Z-score for current period based on rolling window

5. Signal Generation (Optional)

• Thresholds: Configurable (default: ±1)
  • z ≤ -threshold: LONG_SPREAD (Long B + Short A)
  • z ≥ +threshold: SHORT_SPREAD (Short B + Long A)
  • Otherwise: FLAT
• Regime Classification:
  • z ≥ +threshold: HIGH
  • z ≤ -threshold: LOW
  • Otherwise: NEUTRAL

6. Backtest Implementation (Optional)

When backtesting is requested:

• Position Rules:
  • Signals generated at period-end
  • Held for 1 period, closed at next period-end
  • Only one position at a time
  • Equal weight on both legs
• Return Calculation:
  • For LONG_SPREAD: Return = 0.5 × (B_return) + 0.5 × (-A_return)
  • For SHORT_SPREAD: Return = 0.5 × (-B_return) + 0.5 × (A_return)
  • Include transaction costs (configurable, default: 0.40% round-trip)
• Performance Metrics:
  • Total Return (compounded)
  • Annualized Return
  • Sharpe Ratio (annualized)
  • Win Rate
  • Maximum Drawdown

Output Structure

Generate analysis results in this format:

1. Summary Table: Period, Instrument A Close, Instrument B Close, Spread, MoM%, Z-Score, Signal, Regime
2. Trade Log (if backtesting): Entry/Exit dates, signals, spreads, returns, PnL
3. Performance Metrics (if backtesting): Total return, Sharpe, win rate, max drawdown

Error Handling

• Validate data alignment (same timestamps, no missing periods)
• Handle division by zero in MoM% calculations
• Gracefully handle insufficient data for z-score windows
• Log warnings for edge cases

Configuration Parameters

• window_size: Rolling window for z-score (default: 6)
• z_threshold: Signal threshold (default: 1.0)
• clip_range: Z-score clipping range (default: [-3, 3])
• min_samples: Minimum samples for z-score (default: 4)
• transaction_cost: Round-trip cost for backtest (default: 0.40%)
• ddof: Degrees of freedom for std dev (default: 1)

Integration Notes

• Use scripts/calculate_spread.py for core calculations
• Refer to references/calculation_methodology.md for detailed formulas
• Customize output format based on destination (Notion, CSV, JSON, etc.)