`analytics/README.md`

214 lines
# Omega Watch Analytics System

Advanced data science analytics for Omega watch price predictions and investment analysis.

## Quick Start

### Run All Analytics

```bash
cd /root/Projects/watches/analytics
python3 run_all_analytics.py
```

This executes all 4 analytics modules in sequence:
1. Price Prediction & Forecasting
2. Market Analysis & Clustering
3. Statistical Insights & Risk Analysis
4. Comprehensive Report Generation

**Execution Time**: ~1 second
**Output**: 5 JSON files + 2 markdown reports

### Run Individual Modules

```bash
# Price predictions only
python3 price_prediction.py

# Market analysis only
python3 market_analysis.py

# Statistical insights only
python3 statistical_insights.py

# Generate reports
python3 report_generator.py
```

## API Access

All analytics are exposed via REST API:

```bash
# Investment opportunities
curl http://45.61.58.125:7600/api/analytics/investment-opportunities

# Risk metrics
curl http://45.61.58.125:7600/api/analytics/risk-metrics

# Full market analysis
curl http://45.61.58.125:7600/api/analytics/market

# Price predictions
curl http://45.61.58.125:7600/api/analytics/predictions

# Statistical insights
curl http://45.61.58.125:7600/api/analytics/statistics

# Comprehensive report
curl http://45.61.58.125:7600/api/analytics/report
```

## Generated Files

- `price_predictions.json` - Forecasts, anomalies, correlations
- `market_analysis.json` - Clusters, opportunities, volatility
- `statistical_insights.json` - Risk metrics, moving averages, hypothesis tests
- `comprehensive_report.json` - Executive summary
- `INVESTMENT_REPORT.md` - Human-readable investment guide
- `ANALYTICS_SUMMARY.md` - Complete system documentation

## Key Features

### Price Prediction
- Linear, Ridge, Polynomial regression models
- 5, 10, 20-year price forecasts
- 95% confidence intervals
- CAGR calculations
- Anomaly detection

### Market Analysis
- K-means clustering (4 clusters)
- Value watch identification
- Investment opportunity scoring
- Collection performance analysis
- Decade-by-decade trends
- Volatility analysis

### Statistical Insights
- Moving averages (5, 10, 20-year)
- Hypothesis testing (t-tests)
- Percentile rankings
- Risk-adjusted returns
- Sharpe/Sortino/Calmar ratios
- Correlation matrices

### Investment Intelligence
- Top opportunities ranked
- Risk profiles
- Portfolio recommendations
- Value scores
- Growth forecasts

## Dependencies

```bash
pip3 install pandas numpy scipy scikit-learn matplotlib seaborn
```

All dependencies are already installed on the server.

## Architecture

```
analytics/
├── price_prediction.py      # Forecasting models
├── market_analysis.py        # Clustering & segmentation
├── statistical_insights.py   # Risk & statistics
├── report_generator.py       # Report compilation
├── run_all_analytics.py      # Master runner
├── utils.py                  # Helper functions
├── *.json                    # Generated data
└── *.md                      # Generated reports
```

## Data Source

- Input: `/root/Projects/watches/data/watches.json`
- 32 Omega watches
- 196 historical price points
- 1947-2024 time range

## Technical Details

**Models**: Linear Regression (R²=0.75), Ridge, Polynomial
**Clustering**: K-means (n=4, silhouette score optimization)
**Statistics**: SciPy, NumPy, Pandas
**Risk Metrics**: Sharpe, Sortino, Calmar, Max Drawdown
**Confidence**: 95% intervals on all predictions

## Use Cases

1. **Investment Research**: Identify undervalued watches
2. **Portfolio Management**: Risk-adjusted selection
3. **Price Forecasting**: 5-20 year projections
4. **Market Intelligence**: Trend analysis
5. **Collection Strategy**: Value vs growth optimization

## Examples

### Find Best Opportunities

```python
from market_analysis import WatchMarketAnalyzer

analyzer = WatchMarketAnalyzer('/root/Projects/watches/data/watches.json')
analyzer.load_data()
opportunities = analyzer.identify_investment_opportunities()

# Top 5 by opportunity score
for opp in opportunities[:5]:
    print(f"{opp['model']}: Score {opp['opportunity_score']}")
```

### Get Price Prediction

```python
from price_prediction import WatchPricePredictor

predictor = WatchPricePredictor('/root/Projects/watches/data/watches.json')
predictor.load_data()
prediction = predictor.predict_future_prices('speedmaster-moonwatch-1957', years_ahead=[5, 10])

print(f"5-year forecast: ${prediction['predictions']['5_year']['predicted_price']:,.0f}")
```

### Calculate Risk Metrics

```python
from statistical_insights import StatisticalAnalyzer

analyzer = StatisticalAnalyzer('/root/Projects/watches/data/watches.json')
analyzer.load_data()
risk_metrics = analyzer.calculate_risk_metrics()

# Best risk-adjusted returns
top_sharpe = sorted(risk_metrics, key=lambda x: x['risk_adjusted_ranking'], reverse=True)[:5]
for watch in top_sharpe:
    print(f"{watch['model']}: Sharpe {watch['risk_metrics']['sharpe_ratio']:.2f}")
```

## Performance

- **Execution Time**: < 1 second total
- **Memory Usage**: < 100 MB
- **CPU**: Single-threaded
- **Scalability**: Can handle 1000+ watches

## Maintenance

Analytics should be re-run:
- When new price data is added
- Monthly for updated forecasts
- After significant market events
- When model parameters are tuned

## Support

For issues or questions:
- Check logs: `/root/Projects/watches/analytics/*.log`
- API status: `curl http://45.61.58.125:7600/api/health`
- Server logs: `pm2 logs omega-watches`