Add correlation analysis engine for sentiment vs price/volume metrics

[feromoneth]

Summary

• Adds CorrelationEngine class in src/analytics/correlation_engine.py that calculates Pearson correlation between social sentiment and on-chain metrics (price/volume)
• Produces correlation scores bounded between -1 and 1 with statistical significance (p-value)
• Returns scatter plot data points for frontend visualization
• Exposes two new API endpoints: /correlation/analyze and /correlation/lag-analysis

Root Cause

The platform lacked a mechanism to determine whether sentiment is a leading indicator for Stellar on-chain activity. Users needed statistical evidence of the relationship between social sentiment spikes and subsequent price/volume changes.

Implementation

• Created CorrelationEngine with methods for:
  • calculate_correlation(): Single correlation calculation between sentiment and a metric
  • analyze_with_lags(): Multi-lag analysis to find optimal prediction window
  • full_analysis(): Combined price and volume correlation analysis
• Uses pandas built-in correlation (Pearson) with p-value calculation
• Time-series alignment via hourly aggregation to match sentiment timestamps with metric timestamps
• Added DataPoint and CorrelationResult dataclasses for structured output

Testing Performed

• Verified all files pass Python syntax validation (py_compile)
• Created unit tests covering:
  • Positive/negative correlation detection
  • Correlation score bounds (-1 to 1)
  • Empty and insufficient data handling
  • Scatter data generation
  • Lag analysis functionality
  • Result serialization

CI Confirmation

All syntax checks pass. Tests require virtual environment with pandas/numpy installed.

Closes #452

[drips-wave]

@feromoneth Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits