docs: Add results/ directory README for storage documentation

- Created results/README.md with comprehensive documentation
- Documented directory structure (backtests/, db/, factors/, runs/, logs/)
- Added Python and SQL query examples
- Added cleanup instructions
- All results stored in /home/nico/Predix/results/ (in .gitignore)
- Backtest metrics, database, reports all in centralized location

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: TPTBusiness

results/README.md

@@ -1,246 +1,152 @@
-# Predix Results Documentation
+# Predix Results Directory
 
-Dieser Ordner enthält alle Backtesting-Ergebnisse, Faktor-Analysen und Performance-Daten.
+This directory stores all backtesting results, databases, and reports.
 
-## ⚠️ WICHTIG
-
-**Dieser Ordner ist in `.gitignore` aufgenommen!**
-
-- Ergebnisse werden **NICHT** zu Git hinzugefügt
-- Jeder Entwickler hat lokale Ergebnisse
-- Sensible Performance-Daten bleiben privat
+**⚠️ IMPORTANT:** This directory is in `.gitignore` and will NOT be committed to GitHub.
 
 ---
 
-## 📁 Ordner-Struktur
+## 📁 Directory Structure
 
 ```
 results/
-├── backtests/          # Einzelne Backtest-Ergebnisse (JSON, CSV)
-│   ├── FactorName_20240402_120000.json
-│   ├── FactorName_20240402_120000_returns.csv
-│   └── FactorName_20240402_120000_equity.csv
+├── backtests/              # Individual factor backtest results (JSON, CSV)
+│   ├── FactorName_20260402_120000.json
+│   ├── FactorName_20260402_120000_returns.csv
+│   └── FactorName_20260402_120000_equity.csv
 │
-├── factors/            # Faktor-spezifische Analysen
+├── db/                     # SQLite database for all results
+│   └── backtest_results.db
+│
+├── factors/                # Factor-specific analysis
 │   ├── factor_performance.json
 │   └── ic_history.csv
 │
-├── runs/               # Komplette Run-Ergebnisse
-│   ├── risk_report_20240402_120000.json
-│   └── portfolio_weights_20240402.json
-│
-├── logs/               # Backtesting-Logs
-│   └── backtest_20240402.log
+├── runs/                   # Complete run results & risk reports
+│   ├── risk_report_20260402_120000.json
+│   └── portfolio_weights_20260402.json
 │
-└── db/                 # SQLite-Datenbank
-    ├── backtest_results.db
-    └── test_export.json
+└── logs/                   # Backtest logs
+    └── backtest_20260402.log
 ```
 
 ---
 
-## 📊 Gespeicherte Daten
+## 📊 What Gets Stored
 
 ### Backtests (`backtests/`)
 
-Für jeden Faktor werden gespeichert:
-
-| Datei | Inhalt |
-|-------|--------|
-| `{Factor}_{Timestamp}.json` | Alle Metriken (IC, Sharpe, Drawdown, etc.) |
-| `{Factor}_{Timestamp}_returns.csv` | Tägliche Returns |
-| `{Factor}_{Timestamp}_equity.csv` | Equity Curve |
-
-**Metriken pro Faktor:**
-- IC (Information Coefficient)
-- ICIR (IC Information Ratio)
-- Sharpe Ratio
-- Sortino Ratio
-- Calmar Ratio
-- Annualized Return
-- Max Drawdown
-- Win Rate
-- Total Trades
-
----
-
-### Datenbank (`db/backtest_results.db`)
-
-**Tabellen:**
-
-| Tabelle | Inhalt |
-|---------|--------|
-| `factors` | Alle generierten Faktoren |
-| `backtest_runs` | Backtest-Durchläufe |
-| `backtest_metrics` | Performance-Metriken pro Run |
-| `daily_returns` | Tägliche Returns pro Run |
-| `loop_results` | Loop-Zusammenfassungen |
-| `factor_correlations` | Korrelationen zwischen Faktoren |
-
-**Abfragen:**
-
-```python
-from rdagent.components.backtesting import ResultsDatabase
-
-db = ResultsDatabase()
-
-# Top 20 Faktoren nach Sharpe Ratio
-top_factors = db.get_top_factors('sharpe_ratio', limit=20)
-
-# Performance-Historie für Faktor
-perf = db.get_factor_performance('Momentum_8Bar')
-
-# Loop-Zusammenfassung
-loops = db.get_loop_summary()
-
-# Aggregierte Statistiken
-stats = db.get_aggregate_stats()
+For each factor backtest:
+- **JSON file**: All metrics (IC, Sharpe, Drawdown, Win Rate, etc.)
+- **Returns CSV**: Daily returns time series
+- **Equity CSV**: Equity curve
+
+**Example JSON:**
+```json
+{
+  "factor_name": "Momentum_8Bar",
+  "ic": 0.045,
+  "sharpe_ratio": 1.85,
+  "max_drawdown": -0.08,
+  "win_rate": 0.58,
+  "total_trades": 252,
+  "timestamp": "2026-04-02T12:00:00"
+}
 ```
 
----
+### Database (`db/backtest_results.db`)
+
+SQLite database with tables:
+- `factors` - All generated factors
+- `backtest_runs` - Backtest results with metrics
+- `backtest_metrics` - Detailed metrics per run
+- `daily_returns` - Daily returns time series
+- `loop_results` - Loop execution summaries
 
 ### Risk Reports (`runs/`)
 
-**Inhalt:**
-- Portfolio-Volatilität
+- Portfolio volatility
 - Sharpe Ratio
-- Diversifikations-Ratio
+- Diversification Ratio
 - Max Drawdown
-- Limit-Checks (Position Size, Leverage, Drawdown)
-- Korrelationsmatrix
+- Limit Checks (Position Size, Leverage, Drawdown)
+- Correlation Matrix
 
 ---
 
-## 🔧 Verwendung
+## 🔍 Querying Results
 
-### 1. Backtest durchführen
+### Python Example
 
 ```python
-from rdagent.components.backtesting import FactorBacktester, ResultsDatabase
+from rdagent.components.backtesting import ResultsDatabase
 
-# Backtester initialisieren
-backtester = FactorBacktester()
+# Connect to database
 db = ResultsDatabase()
 
-# Faktor-Daten laden
-factor_values = pd.Series(...)  # Faktorwerte
-forward_returns = pd.Series(...)  # Forward Returns
-
-# Backtest durchführen
-metrics = backtester.run_backtest(
-    factor_values=factor_values,
-    forward_returns=forward_returns,
-    factor_name="MyFactor"
-)
-
-# In Datenbank speichern
-db.add_backtest_run(
-    factor_name="MyFactor",
-    metrics=metrics,
-    returns=...,
-    equity_curve=...
-)
-```
-
-### 2. Portfolio-Optimierung
-
-```python
-from rdagent.components.backtesting import PortfolioOptimizer, CorrelationAnalyzer
-
-# Korrelationsmatrix
-corr_analyzer = CorrelationAnalyzer()
-corr_matrix = corr_analyzer.calculate_correlation_matrix(factor_returns)
-
-# Optimierung
-optimizer = PortfolioOptimizer()
-weights = optimizer.mean_variance_optimization(
-    expected_returns=expected_returns,
-    cov_matrix=cov_matrix
-)
-
-# Speichern
-optimizer.save_optimization_results(weights, factor_names, 'mean_variance')
-```
-
-### 3. Risiko-Bericht
-
-```python
-from rdagent.components.backtesting import AdvancedRiskManager
-
-risk_manager = AdvancedRiskManager()
+# Get top 20 factors by Sharpe Ratio
+top_factors = db.get_top_factors('sharpe_ratio', limit=20)
+print(top_factors)
 
-report = risk_manager.generate_risk_report(
-    factor_returns=factor_returns,
-    portfolio_weights=weights
-)
+# Get aggregate statistics
+stats = db.get_aggregate_stats()
+print(f"Total factors: {stats['total_factors']}")
+print(f"Average IC: {stats['avg_ic']}")
+print(f"Max Sharpe: {stats['max_sharpe']}")
 
-print(f"Sharpe: {report['sharpe_ratio']:.2f}")
-print(f"Alle Limits OK: {report['all_limits_ok']}")
+# Close connection
+db.close()
 ```
 
----
+### SQL Example
 
-## 📈 Export
+```bash
+# Open database
+sqlite3 results/db/backtest_results.db
 
-### JSON Export
+# Query top factors
+SELECT factor_name, sharpe, ic, win_rate 
+FROM backtest_runs 
+ORDER BY sharpe DESC 
+LIMIT 10;
 
-```python
-db.export_to_json("results/db/full_export.json")
+# Get aggregate stats
+SELECT COUNT(*) as total_factors,
+       AVG(ic) as avg_ic,
+       MAX(sharpe) as max_sharpe
+FROM backtest_runs;
 ```
 
-**Inhalt:**
-- Aggregierte Statistiken
-- Top-Faktoren
-- Loop-Zusammenfassung
-- Export-Datum
-
 ---
 
-## 🎯 Ziel-Metriken
+## 🧹 Cleanup
 
-| Metrik | Ziel | Minimum |
-|--------|------|---------|
-| **IC** | > 0.05 | > 0.02 |
-| **ICIR** | > 2.0 | > 1.0 |
-| **Sharpe Ratio** | > 2.0 | > 1.0 |
-| **Max Drawdown** | < 15% | < 25% |
-| **Win Rate** | > 55% | > 45% |
-| **Annualized Return** | > 10% | > 5% |
+To clean up old results:
 
----
-
-## 📝 Dokumentation
-
-Jeder Backtest wird automatisch dokumentiert mit:
-- Timestamp
-- Faktor-Name
-- Alle Metriken
-- Returns & Equity Curve
-- Konfigurierte Parameter (Transaction Costs, etc.)
+```bash
+# Remove all results
+rm -rf results/*
 
-**Manuelle Notizen:**
-- Erstelle `results/logs/notes_YYYYMMDD.md` für manuelle Notizen
-- Dokumentiere besondere Ereignisse (Markt-Crashes, etc.)
+# Remove only backtests
+rm -rf results/backtests/*
 
----
-
-## 🔒 Datenschutz
+# Remove database
+rm -f results/db/backtest_results.db
 
-- Ergebnisse sind **lokal** (nicht in Git)
-- Datenbank ist **lokal** (SQLite)
-- Bei Team-Nutzung: Ergebnisse manuell teilen oder zentrale DB verwenden
+# Keep logs but remove everything else
+find results/ -type f ! -path "*/logs/*" -delete
+```
 
 ---
 
-## 🚀 Nächste Schritte
+## 📝 Notes
 
-1. **Backtesting für alle 110 Faktoren durchführen**
-2. **Top-20 Faktoren nach IC/Sharpe auswählen**
-3. **Portfolio-Optimierung durchführen**
-4. **4 Wochen Paper-Trading**
-5. **Live-Performance dokumentieren**
+- Results are stored locally and never committed to Git
+- Database is automatically created on first run
+- JSON files are human-readable for quick inspection
+- Use SQLite database for programmatic access
+- Logs are stored separately for debugging
 
 ---
 
-**Stand:** April 2026
-**Version:** 1.0
+**For detailed usage guidelines, see [README.md](../README.md)**