Skip to content

quant: wire verbs

The facts on this page are the same facts mzLibRust and mzLibR publish, because all three render them from one spec per wire verb. The parameter, result, error and caveat tables are generated; edit the spec, not this page. How the reference facts are generated explains the mechanism. For the Python signatures and result classes, see the API reference. For worked examples, see the FlashLFQ guide.

Python's keywords are mzLib's parameter names. The wire abbreviates FlashLFQ's settings (ppm, mbr, mbr-q, threads); pymzlib.flashlfq.quantify() spells them as mzLib's FlashLfqEngine does (ppm_tolerance, match_between_runs, mbr_q_value_threshold, max_threads), so a call reads like the C# it runs. The runs travel on stdin, rendered from spectra=; for median polish, the design is rendered from design=.

median_polish() returns the protein list only. The wire's envelope also carries the peptide file, the samples in fit order, the peptide count and the output directory; Python does not project those.

quantify

Quantify a search's peptides and proteins across mzML runs with FlashLFQ, returning per-run peptide and protein intensities and every chromatographic peak.

Wire verb quant flashlfq · Python pymzlib.flashlfq.quantify

Wraps

Parameters

Parameter Type Default Unit Range Meaning
psms path required — — A quantifiable PSM result file mzLib can read: a MetaMorpheus .psmtsv/.osmtsv, an MSFragger psm.tsv (retention time converted to minutes by the reader since mzLib#1116), or a DIA-NN report.tsv (FileReader.ReadQuantifiableResultFile at the pin). MSFragger combined results (MsFraggerCombinedResults) implement IQuantifiableResultFile but are not reachable: the path must be a file, and GetResultFileType never maps to that class. Every run the file names must have an mzML on stdin, matched by base file name.
stdin string[] required — >= 1 line The mzML runs, one per line, tab-separated: path[TAB condition[TAB biorep[TAB techrep[TAB fraction]]]]. Blank lines are ignored. Omitted fields default as MetaMorpheus does with no design: condition "", biorep = the line's 0-based index, techrep 0, fraction 0. Replicate and fraction numbers are non-negative integers. Base names must be unique.
normalize flag false — — Normalize intensities across runs (FlashLFQ Normalize).
ppm float 10.0 ppm > 0 Mass tolerance for MS1 peak-finding (PpmTolerance), in ppm.
isotope_ppm (wire --isotope-ppm) float 5.0 ppm > 0 Mass tolerance for isotope-envelope matching (IsotopePpmTolerance), in ppm.
integrate flag false — — Integrate peak area instead of taking the apex intensity (Integrate). FlashLFQ recommends off.
mbr flag false — — Match-between-runs: quantify a peptide in a run where it was not identified by transferring the identification (MatchBetweenRuns). Needs a complete, balanced design.
mbr_ppm (wire --mbr-ppm) float 10.0 ppm > 0 Mass tolerance for MBR transfers (MbrPpmTolerance), in ppm.
mbr_q (wire --mbr-q) float 0.05 q-value 0 to 1 q-value below which an MBR transfer is accepted (MbrQValueThreshold).
shared_peptides (wire --shared-peptides) flag false — — Let peptides shared between protein groups contribute to protein quant (UseSharedPeptidesForProteinQuant).
bayesian flag false — — Also run FlashLFQ's Bayesian protein fold-change engine (BayesianProteinQuant). Its results are not on the wire; they reach only out's BayesianProteinQuant.tsv.
use_pep_q (wire --use-pep-q) flag false — — Store each identification's PEP q-value as its q-value instead of its q-value (MakeIdentifications usePepQValue). It filters nothing here: it changes the value FlashLFQ's own q-value thresholds (e.g. MBR donor selection) later read. For a DIA-NN report the stored value is the raw PEP, not a q-value.
threads int -1 threads any integer; -1 means one fewer than the logical cores FlashLFQ MaxThreads. mzLib resolves it in the engine constructor: -1, or any value >= the core count, becomes (cores - 1); anything that leaves <= 0 becomes 1. parameters.max_threads echoes the RESOLVED value, so it depends on the machine. See caveats for what the thread count does to answers at this pin.
out path absent — — Directory (created if absent) where FlashLFQ also writes QuantifiedPeaks.tsv, QuantifiedPeptides.tsv, QuantifiedProteins.tsv and, with bayesian, BayesianProteinQuant.tsv. Absent or blank writes nothing.

Returns

Top-level fields:

Field Type Unit Null? Meaning
psm_file string — never Absolute path of the PSM file.
identification_count int identifications never Identifications FlashLFQ was given: every record in the PSM file, unfiltered. MakeIdentifications applies no q-value filter; it skips only records whose run was not supplied, which the bridge rejects up front. Decoys are included (with useForProteinQuant false).
parameters object — never The FlashLFQ parameters used, by mzLib name: normalize, ppm_tolerance (ppm), isotope_ppm_tolerance (ppm), integrate, match_between_runs, mbr_ppm_tolerance (ppm), mbr_q_value_threshold (q-value), use_shared_peptides_for_protein_quant, bayesian_protein_quant, max_threads (the resolved thread count).
spectra_files object[] — never One per stdin line, in stdin order; fields under result.tables.spectra_files.
peptide_count int peptides never Entries in peptides: distinct modified sequences quantified.
protein_count int protein groups never Entries in proteins.
peptides object[] — never One per modified sequence, mirroring QuantifiedPeptides.tsv; fields under result.tables.peptides.
proteins object[] — never One per protein group, mirroring QuantifiedProteins.tsv; fields under result.tables.proteins.
peaks object[] — never Every chromatographic peak, run by run in stdin order, mirroring QuantifiedPeaks.tsv; fields under result.tables.peaks. The complete surface for match-between-runs.
output_directory string — yes: out was not given (or was blank): no files were written Absolute path of out.

Fields of spectra_files:

Field Type Unit Null? Meaning
file_name string — never Run base name (no directory or extension): the key of every intensities map.
full_path string — never The mzML path as given on stdin.
condition string — never Sample-group label; "" when none was given.
biological_replicate int — never 0-based.
technical_replicate int — never 0-based.
fraction int — never 0-based.
peak_count int peaks never Chromatographic peaks quantified in this run.
mbr_peak_count int peaks never Of those, peaks with detection type MBR (transferred into this run). 0 unless mbr.

Fields of peptides:

Field Type Unit Null? Meaning
sequence string — never Full modified sequence as FlashLFQ renders it: the quantified identity.
base_sequence string — never Bare residues.
protein_groups string — never Protein group names, ';'-joined, distinct.
intensities map<string,float> intensity (instrument units) never Run base name -> intensity; 0 means not quantified in that run. A value is null only if FlashLFQ produced a non-finite number (the bindings read it as 0). Where a peptide has several peaks in a run this is ONE of them, not their sum.
detection_types map<string,string> — never Run base name -> FlashLFQ DetectionType name: MSMS, MBR, MSMSIdentifiedButNotQuantified, MSMSAmbiguousPeakfinding, NotDetected, ...

Fields of proteins:

Field Type Unit Null? Meaning
protein_group string — never Protein group name.
gene_name string — never As the PSM file gave it; may be "".
organism string — never As the PSM file gave it; may be "".
intensities map<string,float> intensity (instrument units) never Run base name -> protein intensity. A value is null when median polish could not resolve one (NaN: a degenerate peptide matrix, e.g. too few peptides per run); 0 means not measured. Keyed per run even when a design groups runs into samples.

Fields of peaks:

Field Type Unit Null? Meaning
file_name string — never Run base name.
base_sequence string — never Of the peak's first identification; "" if it has none.
sequence string — never Modified sequence of the first identification; "" if none.
intensity float intensity (instrument units) yes: FlashLFQ produced a non-finite intensity for the peak Apex intensity, or the integrated area under integrate.
detection_type string — never DetectionType name; MBR marks a transferred peak.
retention_time float min yes: the peak has no apex (or its time is non-finite) Apex retention time.
num_identifications int identifications never Identifications that explain the peak; > 1 means ambiguous.
protein_groups string — never Protein groups of all its identifications, ';'-joined, distinct.

Errors

Kind pyMzLib raises When
usage UsageError psms missing or blank; the PSM file not found; nothing on stdin; a stdin line with no path; a run that is not .mzML; an mzML not found; two runs sharing a base name; a design field that is not a non-negative integer
usage UsageError the PSM file names runs with no mzML on stdin (checked before any spectra are read; the message lists up to five); ppm, isotope-ppm, mbr-ppm or mbr-q not a number; threads not an integer
correctness BridgeError the PSM file is of a type mzLib cannot read as quantifiable results (MzLibException), or is malformed; an mzML fails to parse; the FlashLFQ engine fails
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • THREADS AT THIS PIN: mzLib#1111 (peptide roll-up nondeterministically dropping MBR intensities at MaxThreads -1, flipping protein groups between null and a number) is fixed by mzLib#1155, which is in the pin: PEP training rows are now built in a fixed order, and its commit reports identical peptides and proteins across runs. The bindings' 'set threads to 1 to reproduce' warnings predate the fix. The bridge project has not re-measured the K562 case at -1 on this pin; until it does, 1 remains the conservative choice for published numbers.
  • mzML only: .raw and .d are rejected up front; convert them first.
  • For match-between-runs read peaks, not peptides: the peptide roll-up (as in QuantifiedPeptides.tsv) reports far fewer MBR transfers than happened (K562 pair: 140 MBR peaks, 52 MBR peptide entries).
  • Peptide intensity 0 means not quantified; protein intensity null means unquantifiable. Neither is a measured zero.
  • Only FlashLFQ settings listed here are reachable; the rest (isotopes required, MBR RT window, donor criterion, IsoTracker, Bayesian sampling) run at mzLib's defaults.
  • stdout carries only the envelope: the engine's console output is redirected to stderr for the run.

Example

result = pymzlib.flashlfq.quantify('AllPSMs.psmtsv', ['run_3.mzML', 'run_4.mzML'], match_between_runs=True, max_threads=1)

Recorded from the live bridge as flashlfq_small.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.flashlfq.quantify mzlib::flashlfq::quantify_with with QuantifyOptions flashlfq_quantify

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • Re-measure the K562 MBR pair at threads -1 on the 23c2490e bridge (G-flashlfq-stale-caveats) before any binding deletes its #1111 warning; the caveat above states what mzLib#1155 claims, not a bridge measurement. pyMzLib main already dropped its warning (#67, unreleased) ahead of the re-measure.
  • Default divergence: the wire and pyMzLib and mzLibRust default threads to -1, mzLibR defaults max_threads to 1 and warns on anything else. The spec states the wire default; whether the bindings should agree is a cross-binding decision.
  • flashlfq_small.json is hand-shaped (paths '/abs/...', 4 identifications), not recorded from a live bridge; a live recording would make the example executable against real files.
  • ppm tolerances and mbr-q are not range-checked by the bridge (a negative or zero tolerance reaches FlashLFQ); the ranges above are FlashLFQ's meaningful ones, not enforced ones. An option given with no value is silently defaulted by the Arguments parser.
  • A PSM file of an unsupported or non-quantifiable type crosses as correctness (mzLib's MzLibException from FileReader.ReadQuantifiableResultFile), though it is arguably the caller's mistake.
  • Most wire params project under FlashLFQ names in every binding (psms, stdin -> spectra, ppm -> ppm_tolerance, isotope-ppm -> isotope_ppm_tolerance, mbr -> match_between_runs, mbr-ppm -> mbr_ppm_tolerance, mbr-q -> mbr_q_value_threshold, shared-peptides -> use_shared_peptides_for_protein_quant, bayesian -> bayesian_protein_quant, use-pep-q -> use_pep_q_value, threads -> max_threads, out -> output_directory); pyMzLib's spec lint will need PYTHON_DEVIATIONS entries for them.

median_polish

Roll a FlashLFQ QuantifiedPeptides.tsv up to protein intensities per sample with FlashLFQ's median polish, under a new experimental design, without re-reading any spectra.

Wire verb quant median-polish · Python pymzlib.flashlfq.median_polish

Wraps

Parameters

Parameter Type Default Unit Range Meaning
peptides path required — — A FlashLFQ QuantifiedPeptides.tsv. Columns are found by header name: Sequence, Base Sequence and Protein Groups are required; Gene Names (or Gene Name) and Organism are optional; one Intensity_ per run, each optionally with a Detection Type_. A blank intensity cell is 0 (not measured).
stdin string[] absent — none, or exactly one line per Intensity_ run The experimental design, one run per line, tab-separated: run_name[TAB condition[TAB biorep[TAB techrep[TAB fraction]]]], run_name matching an Intensity_ column (a name, never opened as a file). Omitted fields: condition "", biorep = the line's 0-based index, techrep 0, fraction 0. With no lines at all, every Intensity_ column is its own biological replicate with a blank condition, as FlashLFQ assumes with no design file. Median polish groups runs by condition and biological replicate, so this is how a caller says which runs are replicates of which sample.
shared_peptides (wire --shared-peptides) flag false — — Let peptides shared between protein groups contribute (UseSharedPeptidesForProteinQuant). Off: a group with only shared peptides quantifies to 0.
out path absent — — Directory (created if absent) where FlashLFQ also writes QuantifiedProteins.tsv. Absent or blank writes nothing.

Returns

Top-level fields:

Field Type Unit Null? Meaning
peptides_file string — never Absolute path of the peptide table.
parameters object — never {use_shared_peptides_for_protein_quant}.
samples object[] — never One per (condition, biological replicate), ordered by condition (ordinal) then biorep. This is NOT the order of the TSV that out writes: mzLib groups conditions there in first-appearance order (see caveats); fields under result.tables.samples. Their labels are the keys of every protein's intensities.
peptide_count int peptides never Distinct sequences read from the table (rows with a Sequence).
protein_count int protein groups never Entries in proteins.
proteins object[] — never One per protein group, ordered by protein_group (ordinal); fields under result.columns.
output_directory string — yes: out was not given (or was blank): nothing was written Absolute path of out.

Per-row fields (one value per record, in columns or each list entry):

Field Type Unit Null? Meaning
protein_group string — never Protein group name; a ';'-joined Protein Groups cell is split into one group per name.
gene_name string — never From the table's gene column, paired to the group by position when the counts match, else the whole ';'-joined cell; "" when the table has no gene column.
organism string — never As gene_name, from the Organism column.
intensities map<string,float> intensity (instrument units) never Sample label -> protein intensity. A value is null when median polish could not resolve one (NaN: a degenerate peptide matrix); 0 means not measured in that sample. A sample of several runs (fractions, technical replicates) reports their sum, as FlashLFQ's own output does, EXCEPT when labels are run names (no design and one fraction): then the bridge reads the first run of the sample only.

Fields of samples:

Field Type Unit Null? Meaning
label string — never The run name when no design groups runs (every condition blank or Default, and one fraction); otherwise '_', e.g. control_1.
condition string — never The sample's condition; "" with no design.
biological_replicate int — never 0-based (the label adds 1).

Errors

Kind pyMzLib raises When
usage UsageError peptides missing or blank, or not found; the file empty; a required column (Sequence, Base Sequence, Protein Groups) missing; no Intensity_ columns; a sequence on two rows; an intensity cell that is not a number; a Detection Type_ cell that is not a FlashLFQ DetectionType name
usage UsageError a design line with no run name, a run named twice, or a replicate/fraction that is not a non-negative integer; design runs with no Intensity_ column; Intensity_ runs the design does not mention (a design must name every run and only those)
correctness BridgeError FlashLFQ's reconstruction or median polish fails
service_unavailable ServiceUnavailableError never raised by this verb

Caveats

  • Detection types: where the table has no Detection Type_ column for a run (or the cell is blank), a positive intensity is treated as MSMS and 0 as NotDetected. That is this verb's only inference; a present but unrecognised value is an error, not a guess.
  • Protein intensity null means unquantifiable, 0 means not measured; neither is a measured zero.
  • Runs are names, not files: nothing but the peptide table is opened, and peak-level information (MBR peaks, retention times) is not available here. Use quant flashlfq for those.
  • With out, QuantifiedProteins.tsv labels its columns by the same rule as samples[].label at this pin (mzLib#1129 is in 23c2490e). Before #1129 the file's rule was inverted for unfractionated data; the values always agreed.
  • Column order can differ from samples[]: QuantifiedProteins.tsv groups conditions in first-appearance order (ProteinGroup.TabSeparatedHeader has no OrderBy), while samples[] sorts them ordinally. Join on the label, never on position.

Example

proteins = pymzlib.flashlfq.median_polish('QuantifiedPeptides.tsv', design=[{'file_name': 'run_3', 'condition': 'control', 'biological_replicate': 0}, {'file_name': 'run_4', 'condition': 'treated', 'biological_replicate': 0}])

Recorded from the live bridge as median_polish_small.json. The doctests in the API reference replay these recordings in CI.

Same verb in other bindings

Python (pyMzLib) Rust (mzLibRust) R (mzLibR)
pymzlib.flashlfq.median_polish mzlib::flashlfq::median_polish_with with MedianPolishOptions flashlfq_median_polish

References

Since

Wire protocol pyMzLib mzLibRust mzLibR
1 0.1.0 0.1.0 0.1.0

Not yet verified

  • The bridge's own comment in MedianPolishToWire and pyMzLib's median_polish docstring still say the TSV labels disagree until mzLib#1129 lands; it is in the pin, so both are stale (confirmed by pyMzLib 005; removed on pyMzLib main by #67, unreleased after 0.2.0). The agreement stated in the caveat is from reading ProteinGroup.cs at 23c2490e, not from a recorded --out run.
  • median_polish_small.json is hand-shaped ('/abs/...'), not a live recording.
  • When labels are run names, the bridge reads only a sample's first run; whether the engine zeroes that sample's other runs (so the reading loses nothing) was not traced. It matters only if several runs share a biorep with no design.
  • The design's techrep and fraction are parsed but only fraction feeds the label rule; how FlashLFQ's median polish uses techrep is mzLib's and was not traced.
  • The wire params peptides/shared-peptides/out project as peptides/use_shared_peptides/output_directory in pyMzLib; the spec lint will need PYTHON_DEVIATIONS entries (stdin -> design, shared-peptides -> use_shared_peptides, out -> output_directory).