Setup & File Tools

LEAF includes utility commands for installation checks, input preflight, starter folders, result inspection, updates, and RAW conversion. They are useful before a web UI run and in scripts where invalid inputs should fail before processing starts.

Command summary

Command	Purpose
leaf doctor	Check the installed LEAF package, Python version, native extensions, reader backend availability (SEED and .NET RawFileReader), optional Web UI assets.
leaf validate	Validate a metabolite CSV and optionally confirm that a data file or folder contains supported RAW / mzML inputs.
leaf init	Create a starter run folder with raw/, results/, metabolites.csv, and a tracing example.
leaf inspect	Print a compact summary of a saved .msd archive or supported acquisition file.
leaf update	Upgrade LEAF inside the currently active Python environment, with a dry-run mode for checking the exact command first.
leaf convert	Convert a folder of Thermo RAW files to mzML through the bundled reader workflow.

Check an installation

leaf doctor

Use strict mode in setup scripts when optional components should also be treated as required:

leaf doctor --strict

leaf doctor reports warnings for optional pieces such as the Web UI bundle, SEED reader, or .NET RawFileReader, and fails when core requirements such as the leaf package or Python 3.12 are missing. Reader backend rows show the detected version (e.g. reader:rust ok 0.10.2) or a reason when unavailable (e.g. .NET 8 runtime is not installed).

Validate inputs before a run

leaf validate ./compounds.csv ./raw

This checks that the compound list can be parsed and that the data path contains .raw or .mzml inputs. Add --strict if warnings should stop the run:

leaf validate ./compounds.csv ./raw --strict

Start a new run folder

leaf init ./leaf-run

The starter folder includes:

• raw/ — LC-MS input files
• results/ — suggested output folder
• metabolites.csv — small primary-metabolism example list
• tracing-labels.json — example tracing label config
• README.md — minimal command-line recipe

If starter files already exist, LEAF skips them unless --force is passed.

Inspect saved results

leaf inspect ./results/example.msd

For .msd files, the summary includes sample count, compound count, RT points, result table presence, quality scores, MS² spectra, and MS² matches. For acquisition files (.raw, .mzml, .mzml.gz, .lcd), leaf inspect reports available metadata when the corresponding reader is available.

Update LEAF

By default, leaf update resolves the latest compatible wheel from GitHub Releases, matching the current platform and Python version:

leaf update

Preview the resolved wheel without installing:

leaf update --dry-run

For local release wheels or a specific release tag:

leaf update --package ./leaf-0.5.7-*.whl
leaf update --github-release v0.5.7

Option	Effect
--dry-run	Print the resolved wheel and install command without running it.
--package PATH_OR_URL	Skip GitHub resolution; install this wheel directly.
--github-release TAG	Pin to a specific release tag (default: latest).
--github-repo OWNER/NAME	Resolve from a different repo (default: MorscherLab/LEAF).
--github-token TOKEN	Authenticate for private releases. Also reads LEAF_UPDATE_GITHUB_TOKEN, GITHUB_TOKEN, or GH_TOKEN from the environment.
--force-reinstall	Reinstall even if the resolved version matches the installed one.

Convert RAW to mzML

Requires .NET

leaf convert uses the .NET RawFileReader backend. It requires .NET 8 runtime and is available only on Windows x64 (or other x64 systems with .NET installed). LEAF validates backend availability before starting and exits with an error if .NET is missing.

leaf convert ./raw ./mzml

Common options:

Option	Effect
--include-ms2	Include MS² spectra in the mzML output.
--filter-threshold INT	Drop peaks below an intensity threshold.
--include-blank	Include files whose names contain "blank".
--workers INT	Set the number of parallel conversion workers.

Next

→ leaf targeted — run targeted extraction without the browser