Reference

CLI Reference

Every script the pipeline runs, with its complete argument list, defaults, inputs, outputs and exit behaviour. All paths are relative to the repository root and every script is launched with that root as its working directory.

ℹ

These are the scripts, not the app The GUI runs exactly these commands. Anything here can be run by hand, and the app will pick up the resulting artefacts on its next refresh.

Common conventions

Working directory

The repository root. Scripts insert their own directory into sys.path so sibling imports work.

Default data file

data/<SYMBOL>_<TF>.csv

Default output root

strategies_lr_<tf> for XAUUSD, else strategies_<symbol>_<tf>

Default cores

os.cpu_count() or 4 — the GUI passes cpu_count − 2

Encoding

Stdout is UTF-8, unbuffered, so progress lines arrive live

Data

`check_ohlc_csv.py`

Validates an OHLC CSV before the pipeline trusts it.

Argument	Required	Default	Controls
`paths`	yes	—	One or more CSV paths. Parses symbol and TF from the filename.
`--quiet`	no	off	Suppress informational `ok` notes; print only errors and warnings.

Reads

Whatever paths are given. No repo-relative default.

Writes

Nothing — stdout report only.

Exit codes

0 = no errors (warnings allowed). 1 = at least one error.

check_ohlc_csv.py data/XAUUSD_M5.csv
check_ohlc_csv.py data/*.csv --quiet

Full validator details →

`download_ohlc_all.py`

Fetches the last N bars through the MetaTrader5 Python API. Needs a Windows Python.

Argument	Default	Controls
`--symbol`	`XAUUSD`	Symbol to download. Must exist on the server.
`--bars`	`10000`	Number of most recent bars per timeframe.
`--offset`	`3.0`	Server-time offset in hours added to the API's UTC timestamps. `0` keeps UTC.
`--tf`	`M1 M2 M5 M10 M15 H1`	One or more timeframes (`nargs="+"`), restricted to the supported set.
`--out`	`<cwd>/data`	Output folder — not a file.
`--login`	—	MT5 account login.
`--password`	—	Account password.
`--server`	—	Broker server name.

Reads

The live terminal. Must be running and logged in.

Writes

<out>/<SYMBOL>_<TF>.csv — one per timeframe, in pipeline format.

Exit codes

2 if the MetaTrader5 module is missing; 1 if the terminal will not initialise or the symbol is not on the server.

⚠

Files are named after the raw --symbol Passing the broker's decorated symbol writes a decorated filename — XAUUSDb_M5.csv. Every later stage looks for the clean XAUUSD_M5.csv. The GUI passes a folder and renames the result afterwards.

ℹ

A single timeframe returning no data prints FAILED and continues — it does not exit non-zero. Check the output list rather than the exit code when downloading several timeframes at once.

Optimisation

`feature_search.py`

The two-stage grid search. The CPU-heavy stage.

Argument	Required	Default	Controls
`--engine`	no	`lr`	Only `lr` is valid.
`--symbol`	no	`XAUUSD`	Drives the default data path, output root and lot multiplier.
`--tf`	yes	—	Timeframe, used for naming and the magic-number offset.
`--set`	no	`all`	A single set name, or the literal `all`. Anything else is a hard error.
`--data`	no	`data/<SYMBOL>_<TF>.csv`	The CSV to search over.
`--out`	no	`strategies_lr_<tf>`	Output root.
`--cores`	no	`cpu_count`	`ProcessPoolExecutor` worker count.

Reads

data/<SYMBOL>_<TF>.csv — twice, once per worker and once in the parent to derive max_spread.

Writes

<out>/<set>/{summary.json, configs.json, slots.txt, equity_<magic>.csv}

Exit codes

1 if the data file is missing or the set name is unknown. A calibration mismatch raises SystemExit.

# all 11 sets, one process
feature_search.py --engine lr --symbol XAUUSD --tf M5 --set all --cores 14

# one set
feature_search.py --engine lr --symbol XAUUSD --tf M5 --set base9 --cores 14

Full detail →

`build_allstar.py`

Combines per-set winners into a portfolio.

Argument	Default	Controls
`--engine`	`lr`	Only `lr` is valid.
`--symbol`	`XAUUSD`	Default data path and output root.
`--tf`	required	Timeframe.
`--all6`	off	Build the `all6` folder — six slots.
`--all9`	off	Build the `all9` folder — the canonical nine.
`--sets`	—	An explicit set list (`nargs="*"`). Overrides the mode flags; folder becomes `custom`.
`--topN`	—	The N best-scoring sets on disk; folder becomes `topN`.
`--exclude`	—	Drop the named sets; folder becomes `best5`.
`--data`	`data/<SYMBOL>_<TF>.csv`	Data CSV (only its bar count is read).
`--out`	`strategies_lr_<tf>`	Output root.
`--cores`	`cpu_count`	Worker count.

⚠

With no mode flag, the default is allstar Not all6. Resolution order: --topN → --sets → --exclude → --all9 → --all6 → else allstar (5 slots, at most one per set).

Reads

Each participating set's summary.json and configs.json, plus the data CSV for its bar count.

Writes

<out>/<folder>/{summary.json, configs.json, equity_combined.csv, equity_<magic>.csv}

Exit codes

1 if the data file is missing, if no per-set outputs exist, or if nothing could be selected.

A set with missing outputs prints skip <set> and continues — non-fatal, but note the shortened book.

`best_hours.py`

Finds each set's best contiguous server-hour window.

Argument	Default	Controls
`--engine`	`lr`	Label stored in the JSON only.
`--symbol`	`XAUUSD`	Data path and output root.
`--tf`	required	Timeframe.
`--data`	`data/<SYMBOL>_<TF>.csv`	Data CSV.
`--out`	`strategies_lr_<tf>`	Root to read summaries from and write `best_hours.json` to.
`--cores`	`cpu_count`	Accepted but not used in the current implementation.

Reads

Every <root>/<set>/summary.json, plus the data CSV.

Writes

<root>/best_hours.json and <root>/<set>/trades.csv per set.

Exit codes

No explicit non-zero exits. Missing per-set summaries are skipped; a missing data CSV produces an uncaught pandas exception.

Full detail →

Evaluation

`holdout_tail.py`

Re-simulates frozen configurations on the last N bars.

Argument	Default	Controls
`--symbol`	`XAUUSD`	Symbol.
`--tf`	`M5`	Timeframe.
`--folder`	`all6`	The portfolio folder to read — `all9`, `all6`, `top6`, etc.
`--tail`	`2500`	Number of trailing bars forming the unseen tail.
`--mode`	`warm`	`warm` or `cold`.
`--cores`	`cpu_count`	Worker count.
`--out`	`strategies_lr_<tf>`	Root to read the portfolio from.
`--data`	from the summary	Data CSV override.
`--full`	off	Also re-run the whole window and print the original numbers. Only when there are 4 or fewer slots.

Reads

<root>/<folder>/summary.json and the data CSV named inside it.

Writes

<root>/<folder>/tail<tail>_<mode>/{tail_report.json, equity_combined_tail.csv, trades_<magic>.csv}

Exit codes

1 if the portfolio summary.json is missing, or if tail_start would fall below 1000 bars.

holdout_tail.py --symbol XAUUSD --tf M5 --folder all9 --mode warm --tail 2500 --cores 14
holdout_tail.py --symbol XAUUSD --tf M5 --folder all9 --mode cold --tail 2500 --cores 14

Full detail →

Generation

`gen_ea.py`

Emits MQL5 source that mirrors the Python engine.

Argument	Default	Controls
`--engine`	`lr`	`lr` (binary sigmoid) or `softmax` (3-class).
`--symbol`	`XAUUSD`	Output root, EA header and filename suffix.
`--tf`	`M5`	Timeframe baked into the EA.
`--set`	—	A set name, or `all` for every per-set EA.
`--out`	`strategies_lr_<tf>`	Output root — also sets where `best_hours.json` is looked for.
`--all6`	off	Emit the `all6` portfolio EA.
`--all9`	off	Emit the `all9` portfolio EA.
`--per-set`	off	Emit one EA per feature set.
`--no-hours`	off	Force `InpSlot<N>Hours = ""` on every slot. Precedes `best_hours.json` and the fallback table.
`--tag`	—	Build tag inserted before the TF suffix, e.g. `24X`.
`--prefix`	—	Literal filename and header prefix identifying a dataset, e.g. `FU_`.

Reads

Portfolio and per-set summary.json + configs.json, and best_hours.json.

Writes

…/FxMath_AST_allstar_ALL9_M5.mq5 (portfolio) or …/FxMath_BAS_base9_LR_M5.mq5 (per set).

Exit codes

None. Missing inputs are skipped with a message; if nothing was emitted it prints Nothing generated. and returns successfully.

⚠

No non-zero exit is possible gen_ea.py never calls sys.exit. A run that produced nothing still looks successful. Always confirm the .mq5 file exists.

Full detail →

Reports

`report_m5.py`

Argument	Default	Controls
`--symbol`	`XAUUSD`	Symbol.
`--tf`	`M5`	Timeframe.
`--port`	auto	Portfolio folder to feature in the headline. Auto order: `all9` → `all6` → `allstar`.
`--out`	`strategies_lr_<tf>`	Output root.
`--data`	from the summary	Data CSV to describe.

Writes: <root>/report.html

`report_tail.py`

Argument	Default	Controls
`--symbol`	`XAUUSD`	Symbol.
`--tf`	`M5`	Timeframe.
`--tail`	`2500`	Which tail folder to read.
`--out`	`strategies_lr_<tf>`	Output root.
`--label`	—	Dataset label for the title and filename, e.g. `FU`. Produces `tail_holdout_report_FU.html`.

Writes: <root>/tail_holdout_report.html

`broker_run_report.py`

Argument	Default	Controls
`--symbol`	`XAUUSD`	Symbol.
`--tf`	`M5`	Timeframe; also names the output file.
`--tail`	`2500`	Which tail result to include.
`--json`	—	Also write the statistics as JSON to this path.

Writes: <root>/report_<tf>_performance.html — for M5, report_m5_performance.html. Prints the output path and the summary statistics to stdout.

Full detail →

Supporting modules

Not normally invoked directly, but useful to know about.

Module	Role
`backtest_lr.py`	The simulation engine. Imported by the search, the portfolio build, the hours search and the holdout. Provides `LRBacktester` and the `_stats` metric computation.
`feature_sets.py`	The 11 feature-set definitions, the primitive library (`compute_primitives`), the MQL5 expression mirrors, `parse_hours`, and `build_feature_matrix`.
`lr_hours_engine.py`	Exact hour-subset replay without re-running the model. Has a `__main__` self-validation that compares replay against real hour-filtered backtests and prints `EXACT MATCH` or `* MISMATCH — do not use *`.
`ml_models.py`	Alternative model implementations used by the comparison studies.
`ExportOHLC_MQL5.mq5`	The broker-side OHLC exporter. Compiled and attached to a chart inside MetaTrader; writes a pipeline-compatible CSV plus a `.summary.txt` sidecar.

Study scripts

The repository also contains a set of analysis scripts that are not part of the main chain. They answer secondary questions and are not driven by the GUI.

Script	Question
`hour_window_report.py`	Is a tight ~2-hour entry window a real risk reduction?
`hours_vs_24h_report.py`	24 hours versus the compiled windows, full metrics.
`best_hours_report.py`	Exhaustive best-N-hour search with profit, drawdown and a nested out-of-sample.
`best_single_hour.py`	If only one hour may be traded per timeframe, which hour, and is it real?
`best_hour_per_slot.py`	Is the best hour portfolio-wide, or does each slot want its own?
`one_hour_ea_report.py`	One-hour-per-slot EA: built, compiled and judged against 24h.
`mixed9_ea_report.py`	Can nine slots picked across M5/M10/M15 beat one timeframe's book?
`compare_models.py`, `compare_symbols_report.py`, `compare_tf_report.py`	Head-to-head comparisons of models, symbols and timeframes.
`select_slots.py`, `compare_slot_corr.py`	Slot selection and correlation diagnostics.
`sizing_report.py`	Lot sizing for a drawdown limit.
`cold_subset_check.py`	Validates the cold-mode subset behaviour.
`sim_dayguard.py`, `ea_hourly_profit_report.py`	Day-of-week guard simulation and per-hour profit for generated EAs.

The app's own CLI

# resolve the environment and print a full report
run_studio.bat --check
py FxMath_LR_Studio\run.py --check
py -m FxMath_LR_Studio --check

# override the repo for one run
py FxMath_LR_Studio\run.py --repo C:\LR-EA

# start on a given target
py FxMath_LR_Studio\run.py --symbol XAUUSD --tf M5

# the frozen exe takes the same flags
"FxMath LR Studio.exe" --check

--check, --self-test

Resolve and print everything, open no window.

--repo

Override the repository path for this run.

--symbol

Start on a given symbol.

--tf

Start on a given timeframe.

Exit codes

0 when a valid repo was resolved, 2 otherwise — so --check can gate a build script.

Because a windowed executable has no console, --check on the frozen exe writes fxmath_lr_studio_check.txt beside the executable and shows the report in a dialog.

The bundled runner

FxMathLRStudioRunner.exe accepts the same argv shape as python.exe, which is what lets the GUI invoke it as a drop-in interpreter. It is also usable directly, for reproducing exactly what the GUI ran.

FxMathLRStudioRunner.exe scripts\feature_search.py --engine lr --symbol XAUUSD --tf M5 --set all
FxMathLRStudioRunner.exe -c "import numpy, pandas; print(numpy.__version__)"
FxMathLRStudioRunner.exe
# ^ with no arguments, prints its own usage

ℹ

It is windowed, so it has no visible stdout The runner is built with console=False so a console window does not flash on every pipeline stage. Its output is only visible when the GUI pipes it. To inspect it directly, redirect to a file from a shell — FxMathLRStudioRunner.exe -c "..." > out.txt — or have the code write its result to a file.