📊 Quant Strategy Performance & Risk Analytics

An Open-Source Automated Engine for Quantitative Trading Strategy Reports & Interactive Analytics


🌐 🚀 Open Live Interactive Report (raw.githack)  |  🖥️ GitHub Pages Demo  |  📄 assets/report_final.html

---

QUANTITATIVE TRADING STRATEGY REPORT & PERFORMANCE ANALYTICS

Quantitative Strategy Performance & Risk Analytics Report

Báo cáo phân tích hiệu năng backtest, chẩn đoán rủi ro, phân phối giao dịch và đánh giá độ vững chắc trên tập In-Sample (Train) & Out-of-Sample (Test).

TÁC GIẢ Quant Research Team

CHIẾN LƯỢC Quantitative Trading Strategy

THỊ TRƯỜNG ETHUSDT Perpetual

GIAI ĐOẠN 2 Jan, 2020 – 30 Dec, 2024

TÓM TẮT ĐIỀU HÀNH (AI INTERPRETATION)
Báo cáo trình bày chi tiết kết quả backtest của chiến lược giao dịch định lượng, đối chiếu với các chỉ tiêu hiệu năng cốt lõi (CAGR, Max Drawdown, Profit Factor, Sharpe Ratio), kết hợp bộ biểu đồ tương tác ECharts và phân tích nhận định chuyên sâu từ dữ liệu giao dịch thực tế.

1.3 Headline KPIs — Đối chiếu với Ngưỡng Kỳ Vọng

CAGR 45.83% ✅ ĐẠT yêu cầu ~20%/năm

MAX DRAWDOWN 11.44% ✅ ĐẠT yêu cầu < 20%

PROFIT FACTOR 1.56 ✅ ĐẠT yêu cầu > 1.5

NHÓM CHỈ SỐ	METRIC	IN-SAMPLE (TRAIN)	OUT-OF-SAMPLE (TEST)
Lợi nhuận	Cumulative Return (toàn kỳ)	559.48%	182.35%
	Best Year	82.07%	41.20%
	Worst Year	11.01%	5.12%
	CAGR (%/năm)	45.83%	28.40%
Rủi ro	Volatility (ann.)	20.94%	24.15%
	Max Drawdown (%)	-11.44%	-14.20%
	Profit Factor	1.56	1.38
Risk-Adjusted	Sharpe Ratio	1.91	1.42

1.2 Ý tưởng Cốt lõi & Nguyên lý Tín hiệu (Click to Toggle)

Phần lớn tín hiệu động lượng trong crypto đối mặt một đánh đổi cố hữu: vi phân trực tiếp để đo tốc độ đổi hướng sẽ khuếch đại nhiễu tần số cao; còn làm mượt theo kiểu tích luỹ quá khứ (như EMA) lại tạo độ trễ pha, khiến tín hiệu đến sau khi cơ hội đã trôi qua.

Cách tiếp cận của chiến lược là chuyển bài toán từ "làm mượt chuỗi thời gian" sang "khớp hình học cục bộ": thay vì đo độ dốc trên từng cặp nến, ta lấy một cửa sổ gần nhất, dựng một mô hình đa thức bậc thấp đại diện cho lõi chuyển động, rồi đọc đạo hàm ngay tại biên phải của cửa sổ.

1.4 In-Sample Performance Analytics — Train Set (ECharts Suite & QuantStats Vector Charts)

Bộ biểu đồ bao gồm 9 ECharts tương tác (Standalone Equity 520px, Price Action & Trade Signal Overlay, Long vs Short Breakdown, MAE/MFE Excursion Scatter, Account Margin Utilization, 2D Density Heatmap) và 12 biểu đồ QuantStats Vector SVG gốc.

---

💡 Why Quant Interpretation Platform?

When backtesting algorithmic trading strategies, raw backtest logs or static metrics are often difficult for non-technical stakeholders, peers, or fund investors to digest.

This platform automatically extracts raw backtest runs (QuantStats HTML & trade logs), renders interactive TradingView-style Apache ECharts, builds a 2-tier dual-set report (In-Sample & Out-of-Sample), and enriches the final output with free AI model insights (Google Gemini / Groq).

---

✨ Key Features

• 📊 TradingView-Style ECharts Analytics Suite:

  • Standalone Equity Curve: 520px high equity curve with drawdown waterfall below.
  • Continuous Price Action Overlay: Execution price line with BUY (▲) and SELL (▼) fill markers and dataZoom timeline sliders.
  • MAE / MFE Risk Distribution: Maximum Adverse vs Favorable Excursion scatter plots.
  • Account Margin Utilization: Equity vs Free Margin over time from account_report.csv.
  • Long vs Short Breakdown, 30-Trade Rolling Win Rate, Return Distribution, and 2D Density Heatmap.

• 🛡️ 2-Tier Dual-Set Architecture (Train & Test):

  • Tier 1 (Primary View): Always-expanded interactive ECharts suites generated from backtest data.
  • Tier 2 (Secondary View): Full 12 QuantStats vector SVG charts enclosed in collapsible accordions (<details class="qs-toggle">).

• 🤖 Free AI Qualitative Strategy Diagnosis:

  • Zero-dependency REST adapter supporting Google Gemini API (gemini-2.5-flash) and Groq API (llama-3.3-70b).
  • Automatically loads keys from .env or --api-key CLI flag.
  • Generates Executive Summaries, Regime Vulnerability Diagnosis, and In-Sample vs Out-of-Sample Overfitting Ratings.

• 🏆 Dynamic KPI Threshold Badging:

  • Automatically evaluates CAGR, Max Drawdown, Profit Factor, and Sharpe Ratio against target benchmarks with visual status badges (✅ ĐẠT, ⚠️ SÁT NGƯỠNG, ❌ CHƯA ĐẠT).

• 🎨 Publication-Grade Paper Theme:

  • Styled with classic typography (Newsreader serif, IBM Plex Sans, IBM Plex Mono) and dark paper palette (#F6F5F0, #1C3D3A, #B8790A).

---

🚀 Quick Start

Prerequisites

• Python 3.8+
• Dependencies: beautifulsoup4, lxml, pillow, pytest

1. Installation

# Clone the repository
git clone https://github.com/BobbyAxerol/awesome-quant-interpretation.git
cd awesome-quant-interpretation

# Set up virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install package and development dependencies
pip install -e ".[dev]"

2. Environment Configuration (.env)

Copy .env.example to .env and add your free Google Gemini or Groq API key:

cp .env.example .env

Edit .env:

GEMINI_API_KEY=your_google_gemini_api_key_here
GROQ_API_KEY=your_groq_api_key_here

3. Generate Strategy Report

Generate a report combining Train Set (In-Sample) and Test Set (Out-of-Sample) data:

python main.py \
    --train-dir data/report_ToTheMoon-Trainset \
    --test-dir data/report_ToTheMoon-Testnset \
    --out report_final.html \
    --sanity-check

Open report_final.html in your web browser!

---

⚙️ CLI Command Line Options

Parameter	Required	Description
--train-dir	❌	Directory containing Train Set backtest outputs (trade_log.csv, quantstats_daily.html, etc.).
--test-dir	❌	Directory containing Test Set backtest outputs.
--quantstats	❌	Explicit path to Train Set QuantStats HTML file.
--quantstats-test	❌	Explicit path to Test Set QuantStats HTML file.
--template	❌	HTML template path (default: template.html).
--out	❌	Output report path (default: report_final.html).
--api-key	❌	Optional AI API key (Google Gemini or Groq). Reads from .env automatically if omitted.
--sanity-check	❌	Generates contact-sheet preview image (report_final.html.sanity_check.png).

---

🏗️ Project Architecture

awesome-quant-interpretation/
├── quant_bot/                  # Core v2 Object-Oriented Package
│   ├── domain/                 # Domain models (Trade, Fill, EquityPoint, ReportDataset)
│   ├── extractors/             # HTML & CSV extractors (QuantStats, TradeLog, AccountHistory)
│   ├── analyzers/              # Performance & Trade Analyzers (badges, win rate, MAE/MFE)
│   ├── charts/                 # EChartsBuilder & SVG Chart Generators
│   ├── interpreters/           # AI Strategy Interpreter (Gemini / Groq) & Rule Interpreter
│   └── renderers/              # HTMLReportRenderer & SanityChecker
├── data/                       # Backtest dataset folders (Train & Test sets)
├── tests/                      # Pytest unit testing suite
├── assets/                     # README landing page marketing screenshots & assets
├── template.html               # Main report HTML paper theme template
├── main.py                     # Primary CLI entrypoint & .env loader
├── .env.example                # Template for environment configuration
└── pyproject.toml              # Package dependencies & configuration

---

🧪 Testing & Verification

Run the test suite via pytest:

.venv/bin/pytest

---

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a Pull Request.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'feat: add AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

_{Built with ❤️ for Quantitative Researchers & Algorithmic Traders.}