docs: add README and install guide

- README.md: full feature overview, install steps, file structure, format support - MT5_Tools_Install_Guide.docx: 8-section Word doc covering install, all pages, config reference and troubleshooting
2026-04-14 10:59:55 +10:00
parent d1add02390
commit 831c0dcef1
1 changed files with 155 additions and 32 deletions
@@ -1,48 +1,171 @@
 # MT5 Tools

-Standalone Streamlit dashboard for MT5 trade analysis and comparison.
+A standalone Streamlit dashboard for MetaTrader 5 trade analysis, batch backtesting, portfolio construction and EA settings comparison.

-## Setup
+> **Windows only** — the Batch Backtest feature requires MetaTrader 5 and Windows. All other pages run on any OS.

-```powershell
-cd C:\Users\pc\MT5Tools
+---
+
+## Features
+
+### 📊 Trade Analysis
+Import and analyse trade history from multiple formats:
+- MT5 account history reports (`.htm`)
+- MT5 backtest reports (`.htm`)
+- Quant Analyzer CSV exports
+- **IC Markets** position history XLSX — multi-account support with account selector
+
+Analysis modes: Overall · By Strategy · By Symbol · By Day of Week  
+Filters: date range, symbol, strategy/EA, day of week, trade type  
+Stats: net profit, win rate, profit factor, R:R, expectancy, max DD, consecutive wins/losses, duration  
+Charts: equity curve, P&L by day of week, P&L by hour of day
+
+---
+
+### 📈 Portfolio Builder
+Load multiple backtest files and view them as a combined portfolio.
+
+- Tabs: Overview · Trades · Equity Chart · Strategies · What-If · Portfolios
+- Equity curve with peak drawdown panel and daily P&L bars
+- What-If: scale all stats by a target lot size
+- Create and name custom sub-portfolios from loaded strategies
+
+---
+
+### 🏆 Portfolio Master
+Automated portfolio construction — searches combinations of loaded strategies and ranks them by a composite score.
+
+**Composite scoring (0–1000):**
+- Ret/DD · Stability (R²) · Stagnation · Win Rate · Growth Quality · Diversity
+- Six weight sliders — normalised automatically
+
+**Search modes:**
+| Mode | Description |
+|------|-------------|
+| Exhaustive | Every combination — count and estimated time shown before run |
+| Greedy (fast) | Incremental build from each strategy seed |
+| Monte Carlo | Random sampling with configurable sample count |
+| Greedy + Monte Carlo | Both combined, deduplicated |
+
+Cancel button stops the search mid-run and returns results found so far.
+
+**Correlation:**
+- Pairwise correlation filter (max threshold slider)
+- Average portfolio correlation as output metric
+- Conditional correlation (drawdown days only) — how strategies co-move during losses
+- Per-result correlation heatmaps in detail expanders
+
+---
+
+### 🔀 Trade Compare
+Compare two trade history files to measure slippage and profit variance — typically a backtest vs live account run of the same EA.
+
+- Match tolerance: 1–24 hours
+- Slippage summary: avg entry slip, exit slip, profit variance, time difference
+- Charts: equity overlay, profit variance bar chart per trade
+- CSV export
+
+---
+
+### ⚙️ EA Settings Comparator
+Upload 2–10 MT5 `.set` files and compare parameters side-by-side.
+
+- Percentage variation highlighting
+- Show differences only toggle
+- Inline editing
+- Export single file or all as ZIP
+
+---
+
+### 📋 Batch Backtest *(Windows only)*
+Streamlit UI wrapper around the CLI batch runner. Runs MT5 backtests sequentially for a folder of `.set` files.
+
+- Reads config from `mt5_batch_config.json`
+- Lot size modes: as-is · manual fixed lots · lots per balance
+- Report naming: `{Strategy}_{Symbol}_{Period}_{Model}_{Instance}.htm`
+  - `.set` filename stem becomes the instance letter (e.g. `A.set` → `_A`)
+- Instrument and timeframe: one for all files or auto-detect from filename
+- Editable preview table before running
+- Live progress bar — cancel mid-run
+- Optimisation files excluded automatically (any spelling/case of `optimiz`/`optimis`)
+- **Windows check** — shows a clear warning and exits if not running on Windows
+
+---
+
+## Requirements
+
+- Windows 10 / 11
+- Python 3.11+
+- MetaTrader 5 (for Batch Backtest)
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/alphapapi-ctrl/mt5-tools.git
+cd mt5-tools
+python -m venv .venv
+.venv\Scripts\activate
 pip install -r requirements.txt
-```
-
-## Launch
-
-```powershell
 streamlit run app.py
 ```

-## Files
+### Batch Backtest — first-run setup
+
+Run the CLI script once to create `mt5_batch_config.json`:
+
+```bash
+python mt5_batch_backtest.py
+```
+
+Follow the prompts to configure your MT5 terminal path, tester folder, EA, dates, deposit and suffix. Config is saved locally and gitignored.
+
+---
+
+## Supported File Formats
+
+| Format | Source |
+|--------|--------|
+| MT5 account history HTM | MetaTrader 5 → File → Save As Report |
+| MT5 backtest HTM | Strategy Tester report tab |
+| Quant Analyzer CSV | Trade List → Export CSV |
+| IC Markets XLSX | IC Markets portal → Reports → MT5 Position History → Export |
+
+---
+
+## Project Structure

 ```
-MT5Tools\
-├── app.py                  ← main Streamlit app
-├── mt5_parser.py           ← parsers for all 3 formats + stats
-├── mt5_batch_backtest.py   ← batch backtest runner (copy from ea\)
-├── set_comparator.py       ← EA set file comparator (copy from ea\)
+mt5-tools/
+├── app.py                    # Main app — navigation and routing
+├── mt5_parser.py             # MT5 HTM + Quant Analyzer CSV parsers
+├── icmarkets_parser.py       # IC Markets XLSX parser
+├── mt5_batch_backtest.py     # CLI batch backtest runner
+├── set_comparator.py         # EA .set file comparison logic
+├── view_trade_analysis.py    # Trade Analysis page
+├── view_trade_compare.py     # Trade Compare page
+├── view_portfolio_builder.py # Portfolio Builder page
+├── view_portfolio_master.py  # Portfolio Master page
+├── view_set_comparator.py    # EA Settings Comparator page
+├── view_batch_backtest.py    # Batch Backtest page (Streamlit UI)
+├── view_settings.py          # Settings page
 ├── requirements.txt
-├── mt5_batch_config.json   ← gitignored, created on first run
-└── pages\
-    ├── trade_analysis.py   ← single report analysis
-    ├── trade_compare.py    ← side-by-side comparison
-    └── settings.py
-
+└── mt5_batch_config.json     # Created on first run (gitignored)
 ```

-## Supported Formats
+---

-| Format | Extension | Notes |
-|---|---|---|
-| MT5 Account History | `.htm` / `.html` | Export from MT5 → Account History → Save as Report |
-| MT5 Backtest Report | `.htm` / `.html` | Generated by batch backtest runner or manual tester |
-| Quant Analyzer CSV | `.csv` | Export listOfTrades from Quant Analyzer |
+## Notes

-## .gitignore
+- `mt5_batch_config.json` is gitignored — create it by running `mt5_batch_backtest.py` once
+- `set_comparator.py` may need to be copied from your EA project folder if not included
+- MT5 `.set` files are UTF-16 LE encoded — handled automatically
+- Streamlit's `pages/` folder name is reserved — view files sit at root level prefixed with `view_`
+- `git config core.autocrlf true` suppresses LF/CRLF warnings on Windows

-Add the following to `.gitignore`:
-```
-mt5_batch_config.json
-```
+---
+
+## License
+
+MIT