MuMDIA command-line reference

GENERATED FILE. Do not edit. ci/gen_cli_reference.py writes it from the mumdia binary's own --help output, so the interface described here is the interface the binary actually has. The source of truth is the clap derive in rust/mumdia/crates/mumdia/src/main.rs: change the flag or its doc comment there, rebuild, and regenerate. An edit made to this file is lost on the next run.

python ci/gen_cli_reference.py            # regenerate
python ci/gen_cli_reference.py --check    # fail if this file is stale

For what each stage does with these arguments, read docs/README.md and the per-stage documents it routes to. For the configuration file passed with --config, read docs/24_config_reference.md.

How to read this document

Every block below is the binary's own help text, right-stripped and with the program name normalized to mumdia (a Windows build reports mumdia.exe). Nothing is paraphrased. Two mechanical edits are applied:

the 6 flags clap marks global = true, and -h, --help, are removed from the per-subcommand blocks and documented once under "Global flags" below, because clap repeats them in every subcommand;
mumdia help gets a table row but no section, because mumdia help --help reprints the top-level help unchanged.

Top-level help

MuMDIA DIA search engine (Rust MVP)

Usage: mumdia [OPTIONS] <COMMAND>

Commands:
  convert          Read an mzML run into the normalized spectra artifact set
  digest           Tryptic or non-specific digest (`digest.enzyme`) + decoy pairing -> peptides.parquet
  peptidoforms     Fixed+variable modification and charge enumeration -> peptidoforms.parquet
  predict-frag     Spectral library: b/y m/z + predicted intensity + iRT -> fragment_library
  prescan          Sequence-tag prescan: keep only modification-bearing candidates whose anchored trimers are observed in this run -> prescan_survivors.parquet. Label-blind by construction, so it prunes search space without touching target-decoy exchangeability
  prescreen        Fragment-rarity prescreen: score every candidate on its own window's spectra and keep those above a label-blind calibration quantile -> survivors in the prescan_survivors contract, for `extract --restrict-candidates` (docs/34_prescreen.md)
  search-seed      Native broad DIA seed search over the fragment index -> seed_psms.parquet
  rt-im-train      Per-run RT calibration + windows -> run_windows.parquet, cal.json
  sub-library      Subset a library to a set of candidates (a first pass's survivors, or prescan's), renumbered to the contiguous 0..n the fragment index requires
  extract          Targeted 3D extraction (peak-major cascade) -> psms_extracted, chromatograms
  retrace          Rebuild a diaPASEF run's chromatograms from the raw timsTOF events, and patch its psms_extracted (docs/35_diapasef.md section 6). `run` and `run-experiment` do this after extract under `retrace.enabled`; standalone it takes the same inputs by path. The configuration's `retrace` section applies, `enabled` aside
  localise         Site probabilities of a localised modification on one run's scored rows (experimental; docs/36_ptm_localisation.md) -> localisation.parquet; with --experiment-dir, on every run of a finished run-experiment at one temperature, and the runs combined -> localisation_experiment.parquet. Reporting only: nothing upstream changes
  mobilogram       The 1/K0 profile (mobilogram) of candidates' fragment and MS1 ions, read from the raw events of a diaPASEF `.d` (docs/35_diapasef.md section 17). Read-only
  features         Compute the minimal feature set -> features.parquet + PIN
  pool             Pool a grouped run's band artifacts into the run-level tables
  compete          Keep the best candidate per competition group -> psms_competed.parquet
  rescore          Rescore + native target-decoy q-values -> psms_scored.parquet
  quant            Quantify identified peptides + roll up to protein groups
  quant-lfq        Combine per-run quant tables into a protein-by-run matrix (cross-run LFQ)
  quant-normalise  Cross-run normalisation of per-run precursor quantities -> peptide_quant_normalised
  run              Orchestrate the full pipeline on one run and write a manifest. Given several --mzml, the files are searched as ONE pooled experiment (`run-experiment`: one combined rescore, per-run quant, cross-run LFQ), which is the default treatment of a multi-file input; use `run-experiment` directly for run names
  run-experiment   Experiment-wide orchestrator: run the per-file search chain over N runs, then one combined rescore, optional rescuable MBR transfer, per-run quant, and cross-run LFQ. Pass --mzml once per run (>= 2)
  build-library    Build the spectral library of a FASTA search without spectra: digest -> peptidoforms -> predict-frag, restored from or stored into `predict_frag.library_cache` under the key a `run --fasta` uses. Writes the two library tables, manifest.json and library.json (counts, models, cache key and the commands that search with it) into --out-dir
  align            Cross-run RT alignment (experiment-level) -> alignment.parquet
  mbr              Match-between-runs identification transfer (Stage D3) -> transferred.parquet
  inspect          Print schema, head sample, and row count for any artifact
  peak-census      Peaks per MS2 spectrum for an mzML or a diaPASEF `.d`, as JSON: percentiles plus what each candidate `--top-peaks-ms2` cap would discard
  audit            Candidate audit: reconstruct per-candidate stage flags + earliest rejection reason across the artifact chain and write candidate_audit.parquet (sensitivity program, P0.3/P0.4). Non-destructive; reruns no compute
  report           Write peptides.tsv + proteins.tsv from a scored PSM table, or the experiment-wide pair for a `run-experiment` output directory
  cache            Show, trim or clear the engine's caches: FASTA-built libraries and DeepLC's trunk projection (docs/14, "The engine's caches")
  doctor           Check that the configured Python sidecar environments are usable
  help             Print this message or the help of the given subcommand(s)

Options:
      --threads <N>
          Worker threads of the engine's thread pools. Default: every core.

          Sets the engine's rayon pool to N threads and the parquet codec pool to min(N, 8) threads, serial at N = 1 (docs/03_io_layer.md, "Parallel column codec"). The codec pool encodes and decodes artifacts for writer and loader threads that run beside the rayon pool, so up to N + min(N, 8) threads can be busy at once; add `MUMDIA_PARQUET_THREADS=1` to keep the parquet codec serial and the run near N threads. N is also forwarded to the Python sidecars as `MUMDIA_NN_THREADS` and `OMP_NUM_THREADS` unless those are already set. Without this there was no way to bound MuMDIA at all except the undocumented `RAYON_NUM_THREADS`, which the engine never read and which does not reach the sidecars; on a shared machine that made a run antisocial. Note the NN rescore worker measured FASTER on 8 threads than on 32 (docs/13_sidecars.md).

      --log-level <LEVEL>
          Log level: `error`, `warn`, `info` (default), `debug`, or `trace`. Accepts any `RUST_LOG` filter, so `mumdia=debug,extract=trace` also works

  -v, --verbose...
          More detail: `-v` for debug, `-vv` for trace. Overridden by --log-level

  -q, --quiet
          Warnings and errors only. Overridden by --log-level

      --cache-dir <DIR>
          Root of the engine's caches (FASTA-built libraries, DeepLC projections), or `off`.

          Wins over `MUMDIA_CACHE_DIR`, which wins over the per-user cache directory. A relative path is resolved against the working directory. A root that cannot be written switches the default caches off for the run with one warning (docs/14_build_test_deploy_gotchas.md, "Where MuMDIA writes").

      --temp-dir <DIR>
          Temporary directory of the engine and of every process it starts.

          Wins over `MUMDIA_TEMP_DIR`. It becomes `TMP`, `TEMP` and `TMPDIR` for the engine and its Python workers, and `MPLCONFIGDIR` goes under it unless set. Created if needed; one that cannot be written is an error. Default: the system's.

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Global flags

These 6 options are declared global = true, so they are accepted on EITHER side of the subcommand: mumdia --threads 8 extract ... and mumdia extract --threads 8 ... are equivalent and reach the same value. They are removed from the per-subcommand blocks below to keep this document readable, as is -h, --help, which every subcommand also accepts.

Flag	Purpose
`--cache-dir <DIR>`	Root of the engine's caches (FASTA-built libraries, DeepLC projections), or `off`. Wins over `MUMDIA_CACHE_DIR`, which wins over the per-user cache directory. A relative path is resolved against the working directory. A root that cannot be written switches the default caches off for the run with one warning (docs/14_build_test_deploy_gotchas.md, "Where MuMDIA writes").
`--log-level <LEVEL>`	Log level: `error`, `warn`, `info` (default), `debug`, or `trace`. Accepts any `RUST_LOG` filter, so `mumdia=debug,extract=trace` also works
`-q, --quiet`	Warnings and errors only. Overridden by --log-level
`--temp-dir <DIR>`	Temporary directory of the engine and of every process it starts. Wins over `MUMDIA_TEMP_DIR`. It becomes `TMP`, `TEMP` and `TMPDIR` for the engine and its Python workers, and `MPLCONFIGDIR` goes under it unless set. Created if needed; one that cannot be written is an error. Default: the system's.
`--threads <N>`	Worker threads of the engine's thread pools. Default: every core. Sets the engine's rayon pool to N threads and the parquet codec pool to min(N, 8) threads, serial at N = 1 (docs/03_io_layer.md, "Parallel column codec"). The codec pool encodes and decodes artifacts for writer and loader threads that run beside the rayon pool, so up to N + min(N, 8) threads can be busy at once; add `MUMDIA_PARQUET_THREADS=1` to keep the parquet codec serial and the run near N threads. N is also forwarded to the Python sidecars as `MUMDIA_NN_THREADS` and `OMP_NUM_THREADS` unless those are already set. Without this there was no way to bound MuMDIA at all except the undocumented `RAYON_NUM_THREADS`, which the engine never read and which does not reach the sidecars; on a shared machine that made a run antisocial. Note the NN rescore worker measured FASTER on 8 threads than on 32 (docs/13_sidecars.md).
`-v, --verbose...`	More detail: `-v` for debug, `-vv` for trace. Overridden by --log-level
`-h, --help`	Print help (see a summary with '-h')

The same text as the binary prints it:

Options:
      --cache-dir <DIR>
          Root of the engine's caches (FASTA-built libraries, DeepLC projections), or `off`.

          Wins over `MUMDIA_CACHE_DIR`, which wins over the per-user cache directory. A relative path is resolved against the working directory. A root that cannot be written switches the default caches off for the run with one warning (docs/14_build_test_deploy_gotchas.md, "Where MuMDIA writes").

      --log-level <LEVEL>
          Log level: `error`, `warn`, `info` (default), `debug`, or `trace`. Accepts any `RUST_LOG` filter, so `mumdia=debug,extract=trace` also works

  -q, --quiet
          Warnings and errors only. Overridden by --log-level

      --temp-dir <DIR>
          Temporary directory of the engine and of every process it starts.

          Wins over `MUMDIA_TEMP_DIR`. It becomes `TMP`, `TEMP` and `TMPDIR` for the engine and its Python workers, and `MPLCONFIGDIR` goes under it unless set. Created if needed; one that cannot be written is an error. Default: the system's.

      --threads <N>
          Worker threads of the engine's thread pools. Default: every core.

          Sets the engine's rayon pool to N threads and the parquet codec pool to min(N, 8) threads, serial at N = 1 (docs/03_io_layer.md, "Parallel column codec"). The codec pool encodes and decodes artifacts for writer and loader threads that run beside the rayon pool, so up to N + min(N, 8) threads can be busy at once; add `MUMDIA_PARQUET_THREADS=1` to keep the parquet codec serial and the run near N threads. N is also forwarded to the Python sidecars as `MUMDIA_NN_THREADS` and `OMP_NUM_THREADS` unless those are already set. Without this there was no way to bound MuMDIA at all except the undocumented `RAYON_NUM_THREADS`, which the engine never read and which does not reach the sidecars; on a shared machine that made a run antisocial. Note the NN rescore worker measured FASTER on 8 threads than on 32 (docs/13_sidecars.md).

  -v, --verbose...
          More detail: `-v` for debug, `-vv` for trace. Overridden by --log-level

  -h, --help
          Print help (see a summary with '-h')

Subcommands

One row per subcommand. --config says whether the subcommand reads a JSON config file (see docs/24_config_reference.md); the purpose column is the first sentence of the description, with the full text in the section below.

Subcommand	`--config`	Purpose
`convert`	yes	Read an mzML run into the normalized spectra artifact set
`digest`	yes	Tryptic or non-specific digest (`digest.enzyme`) + decoy pairing -> peptides.parquet
`peptidoforms`	yes	Fixed+variable modification and charge enumeration -> peptidoforms.parquet
`predict-frag`	yes	Spectral library: b/y m/z + predicted intensity + iRT -> fragment_library
`prescan`	yes	Sequence-tag prescan: keep only modification-bearing candidates whose anchored trimers are observed in this run -> prescan_survivors.parquet.
`prescreen`	yes	Fragment-rarity prescreen: score every candidate on its own window's spectra and keep those above a label-blind calibration quantile -> survivors in the prescan_survivors contract, for `extract --restrict-candidates` (docs/34_prescreen.md)
`search-seed`	yes	Native broad DIA seed search over the fragment index -> seed_psms.parquet
`rt-im-train`	yes	Per-run RT calibration + windows -> run_windows.parquet, cal.json
`sub-library`	yes	Subset a library to a set of candidates (a first pass's survivors, or prescan's), renumbered to the contiguous 0..n the fragment index requires
`extract`	yes	Targeted 3D extraction (peak-major cascade) -> psms_extracted, chromatograms
`retrace`	yes	Rebuild a diaPASEF run's chromatograms from the raw timsTOF events, and patch its psms_extracted (docs/35_diapasef.md section 6). `run` and `run-experiment` do this after extract under `retrace.enabled`; standalone it takes the same inputs by path.
`localise`	yes	Site probabilities of a localised modification on one run's scored rows (experimental; docs/36_ptm_localisation.md) -> localisation.parquet; with --experiment-dir, on every run of a finished run-experiment at one temperature, and the runs combined -> localisation_experiment.parquet.
`mobilogram`	yes	The 1/K0 profile (mobilogram) of candidates' fragment and MS1 ions, read from the raw events of a diaPASEF `.d` (docs/35_diapasef.md section 17).
`features`	yes	Compute the minimal feature set -> features.parquet + PIN
`pool`	no	Pool a grouped run's band artifacts into the run-level tables
`compete`	yes	Keep the best candidate per competition group -> psms_competed.parquet
`rescore`	yes	Rescore + native target-decoy q-values -> psms_scored.parquet
`quant`	yes	Quantify identified peptides + roll up to protein groups
`quant-lfq`	no	Combine per-run quant tables into a protein-by-run matrix (cross-run LFQ)
`quant-normalise`	yes	Cross-run normalisation of per-run precursor quantities -> peptide_quant_normalised
`run`	yes	Orchestrate the full pipeline on one run and write a manifest.
`run-experiment`	yes	Experiment-wide orchestrator: run the per-file search chain over N runs, then one combined rescore, optional rescuable MBR transfer, per-run quant, and cross-run LFQ.
`build-library`	yes	Build the spectral library of a FASTA search without spectra: digest -> peptidoforms -> predict-frag, restored from or stored into `predict_frag.library_cache` under the key a `run --fasta` uses.
`align`	yes	Cross-run RT alignment (experiment-level) -> alignment.parquet
`mbr`	yes	Match-between-runs identification transfer (Stage D3) -> transferred.parquet
`inspect`	no	Print schema, head sample, and row count for any artifact
`peak-census`	yes	Peaks per MS2 spectrum for an mzML or a diaPASEF `.d`, as JSON: percentiles plus what each candidate `--top-peaks-ms2` cap would discard
`audit`	no	Candidate audit: reconstruct per-candidate stage flags + earliest rejection reason across the artifact chain and write candidate_audit.parquet (sensitivity program, P0.3/P0.4).
`report`	yes	Write peptides.tsv + proteins.tsv from a scored PSM table, or the experiment-wide pair for a `run-experiment` output directory
`cache`	yes	Show, trim or clear the engine's caches: FASTA-built libraries and DeepLC's trunk projection (docs/14, "The engine's caches")
`doctor`	yes	Check that the configured Python sidecar environments are usable
`help`	n/a	Print this message or the help of the given subcommand(s)

27 of the 31 documented subcommands accept --config: align, build-library, cache, compete, convert, digest, doctor, extract, features, localise, mbr, mobilogram, peak-census, peptidoforms, predict-frag, prescan, prescreen, quant, quant-normalise, report, rescore, retrace, rt-im-train, run, run-experiment, search-seed, sub-library.

4 do not, so every setting they use comes from their own flags: audit, inspect, pool, quant-lfq.