From 831c0dcef111bdd071cb596ec8010c7ccb49e63f Mon Sep 17 00:00:00 2001 From: unknown Date: Tue, 14 Apr 2026 10:59:55 +1000 Subject: [PATCH] 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 --- README.md | 187 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 155 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index fbef15f..54ee9ed 100644 --- a/README.md +++ b/README.md @@ -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 \ No newline at end of file