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 4 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          Fully-tryptic digest + 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
  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
  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)
  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)
  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, 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
  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>
          Maximum worker threads. Default: every core.

          Bounds the engine's rayon pool and is 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

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

  -V, --version
          Print version

Global flags

These 4 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
`--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
`--threads <N>`	Maximum worker threads. Default: every core. Bounds the engine's rayon pool and is 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:
      --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

      --threads <N>
          Maximum worker threads. Default: every core.

          Bounds the engine's rayon pool and is 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	Fully-tryptic digest + 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.
`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
`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)
`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.
`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, 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
`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)

20 of the 24 documented subcommands accept --config: align, compete, convert, digest, doctor, extract, features, mbr, peak-census, peptidoforms, predict-frag, prescan, quant, report, rescore, 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.