MGF (Mascot generic format)
MGF is the plain-text peak-list format of Matrix Science’s Mascot search engine, and the most common way to pass MS/MS spectra between tools: ProteoWizard msConvert, OpenMS, MZmine, GNPS, MassIVE-KB, PRIDE and many search engines write it. An MGF file holds processed peak lists (usually centroided), not raw scans. OpenReadout returns every spectrum with its precursor, retention time, charge and peaks. Derived from Matrix Science’s public description of the format (https://www.matrixscience.com/help/data_file_help.html), with pyteomics (Apache-2.0) as the reference reader. Provenance: docs/provenance/mgf.md.
Format id mgf, extensions .mgf and .mgf.gz. It is read by the openreadout-mzml crate (MgfReader), next to mzML and mzXML, and shares their spectrum model.
Layout
The file is text, one item per line. Blank lines may appear anywhere.
- File parameters. Lines
KEY=valuebefore the first block apply to the whole file (Mascot search settings such asCOM,CLE,DB,MODS,ITOL,TOL,CHARGE,FORMAT). Keys are case-insensitive; the reader upper-cases them. A file-levelCHARGEis the charge of every spectrum that names none. - Comments. Lines starting with
#,;,!or/outside blocks are comments (counted invendor.comment_lines). - Blocks.
BEGIN IONS…END IONSholds one MS/MS spectrum: its ownKEY=valuelines first, then one peak per line,m/z intensity [charge], separated by white space; anything after the third value is ignored (some writers annotate peaks,72.04 101 # b1). - Peptide-mass-fingerprint lines. A number outside a block is a peptide-mass-fingerprint query. These are counted (
extra.pmf_queries), not read as spectra.
Detection: within the first 64 KiB, a BEGIN IONS line preceded only by blank lines, comments and KEY=value lines (definite). A .mgf name without that is an extension-only match. Gzip-compressed files are read through the same container as .mzML.gz (docs/formats/mzml.md § Containers).
MGF has no index. open reads the file once, line by line, and keeps the byte range and the parameters of each block; peaks are counted then and parsed only when a spectrum is read. A file that ends inside a block is truncated: the incomplete block is left out, info says so in notes, and check reports truncated.
Block → Spectrum
| parameter | field |
|---|---|
PEPMASS=mz [intensity] [charge] |
precursor_mz, precursor_intensity; a charge printed here is that precursor’s charge and is used before the block’s CHARGE. Several PEPMASS lines (chimeric spectra): the first is precursor_mz, all are in extra.precursors |
CHARGE (2+, 3-, 2, 2+ and 3+, 2+,3+) |
precursor_charge when it names one charge and the first PEPMASS line names none; several are in extra.charges |
RTINSECONDS (95.3, or a range 95-97) |
rt_s (the start of a range; the range is extra.rt_range_s). A value that is not a number is kept as extra.rt_unparsed |
SCANS |
scan_number when it is one whole number, else the position from 1; the text is extra.scans (1278,1280-1284, F1:2478) |
TITLE |
extra.title; a ProteoWizard title (... NativeID:"controllerType=0 controllerNumber=1 scan=17") also gives native_id |
MSLEVEL (library and feature exports) |
ms_level; without it 2, as MGF holds MS/MS queries |
IONMODE, ION_MODE (positive, negative) |
polarity; without one unknown |
| every parameter of the block | extra.params, keys upper-cased, values as written |
| peak lines | mz and intensity in file order (intensities as 32-bit floats, like every spectrum); the optional third value is extra.peak_charges (null where a peak has none) |
centroided is true: Mascot accepts centroided peak lists only, and the format has no way to say otherwise.
Run summary (info → spectra[0])
| key | meaning |
|---|---|
scan_count, ms_levels, rt_range_s |
spectra, MS levels, retention-time range over the blocks that give one |
extra.ms_level_counts |
spectra per MS level |
extra.charge_states |
spectra per precursor charge (none, several when a block names more than one) |
extra.total_points |
peak lines in all blocks |
extra.spectra_with_rt |
blocks with a usable RTINSECONDS |
extra.chimeric_spectra |
blocks with more than one PEPMASS line |
extra.block_parameters |
how many blocks use each parameter key |
extra.file_parameters |
the file parameters |
extra.pmf_queries |
peptide-mass-fingerprint lines outside blocks |
extra.polarities |
polarities named by the blocks |
extra.dialect, extra.writer |
see below |
name |
the file name in the first block’s RAWFILE, when there is one |
Dialects
Writers use different optional parameters, which decides how titles, scan numbers, charges and polarity are read. extra.dialect names the one the parameters show (inferred from the corpus):
| dialect | recognised by |
|---|---|
spectral library (GNPS) |
the first block has SPECTRUMID or an ORGANISM starting with GNPS |
feature export (FEATURE_ID) |
the first block has FEATURE_ID (OpenMS GNPSExport, MZmine) |
search submission (file parameters) |
file parameters such as SEARCH, DB, CLE, MODS or COM |
annotated peptide spectra (SEQ) |
the first block has SEQ |
peak list |
none of these |
extra.writer names the software when the file says: OpenMS (a COM or USERNAME file parameter that names it), GNPS (a library record: SPECTRUMID CCMSLIB… or a GNPS- collection), ProteoWizard (titles with NativeID:"…").
check
check --headers-only: truncation, structure problems (a BEGIN IONS before the previous block’s END IONS, an END IONS without a block, lines that are neither parameters nor peaks), blocks without a usable PEPMASS (no_pepmass). check also parses every peak line (bad_peak: a peak line without a finite m/z and intensity) and compares the count with the scan at open (peak_count).
Vocabulary
| identifier | meaning |
|---|---|
MgfReader |
the MGF FormatReader |
MGF_FORMAT_ID |
mgf |
MgfDataset |
an open MGF file; spectrum(i) reads block i with its peaks |
spectrum |
read one spectrum with its peaks |
pmf_queries, comment_lines, file_parameters, blocks |
vendor keys: peptide-mass-fingerprint lines, comment lines, file parameters, block count |
title, scans, charges, precursors, params, peak_charges, rt_range_s, rt_unparsed |
spectrum extra keys (table above) |
ms_level_counts, charge_states, total_points, spectra_with_rt, chimeric_spectra, block_parameters, polarities, dialect, writer |
run extra keys (table above) |
truncated, structure, no_pepmass, bad_peak, peak_count |
check finding codes |
How this reader was derived, file by file: provenance log.