Mass spectrum scan parsing

mass-spectrum-scan-parsing

Summary

Parse and extract mass spectrometry scan data from raw instrument files (Thermo .raw, .FT1/.FT2, mzML, MGF) into structured peak lists with m/z, intensity, and charge state information. This is the foundational step for annotating fragment ions and validating peptide-spectrum matches in stable isotope labeling experiments.

When to use

You have raw mass spectrometry data files from a Thermo instrument (e.g., Orbitrap or IonTrap) or already-converted open formats (mzML, MGF) and need to extract individual MS1 or MS2 scans with their observed peak m/z values, intensities, and charge states before matching them against theoretical isotopic envelopes or fragment ion predictions. Particularly critical when working with heavily labeled samples (e.g., 52% 13C incorporation) where charge and isotope information must be preserved.

When NOT to use

• Input data are already peak-picked and tabulated in a feature table (use directly for matching instead)
• You require raw ion current time-series data without peak centroiding; use native Thermo libraries instead of Raxport/ThermoRawFileParser
• Working with non-Thermo instruments (e.g., Bruker, Waters, ABSciex) without prior conversion to mzML or MGF; Raxport is Thermo-specific

Inputs

• Thermo .raw file from mass spectrometer (Orbitrap or IonTrap)
• mzML or indexed mzML file (from ThermoRawFileParser or similar)
• MGF file (mascot generic format)
• Raxport-processed .FT1 or .FT2 file
• Scan number (integer identifier)
• Isolation window width (e.g., 5.0 Da for MS2)

Outputs

• Structured peak list with m/z, intensity, and charge state per scan
• Precursor m/z and charge state (for MS2 scans)
• Scan metadata (retention time, MS level, scan number)
• Total ion current (TIC) chromatogram for quality control

How to apply

Convert Thermo .raw files to intermediate .FT1 or .FT2 files using Raxport, extracting charge information (Orbitrap only) and MS1/MS2 scans. Alternatively, use ThermoRawFileParser to convert directly to mzML or MGF. Load the resulting file into Aerith using mzR (mzML/MGF) or Raxport-compatible parsers (FT2), specifying the scan number and isolation window width (e.g., 5.0 Da for MS2). Extract observed peak data (m/z, intensity) and precursor m/z with charge state. Verify data quality by inspecting TIC (total ion current) and scan frequency before proceeding to peak matching. Apply consistent parameter selection across replicate samples to ensure reproducibility.

Related tools

• Raxport (Extract scans from Thermo .raw files with charge information (Orbitrap only) into .FT1/.FT2 intermediate format compatible with Aerith) — https://github.com/xyz1396/Raxport.net
• ThermoRawFileParser (Convert Thermo .raw files to open formats (mzML, indexed mzML, MGF, Parquet) on all platforms; alternative to Raxport for cross-platform compatibility) — https://github.com/CompOmics/ThermoRawFileParser
• Aerith (Read and parse mass spectrum scans from mzML, MGF, Raxport .FT2, pepXML, PIN, and Sipros TSV files; visualize TIC and prepare peaks for theoretical isotopic matching) — https://github.com/xyz1396/Aerith
• mzR (Bioconductor R package integrated into Aerith for direct parsing of mzML and MGF files within R environment)
• MSnbase (Bioconductor R package for parsing pepXML files and handling parsed mass spectrum objects in downstream R workflows)

Examples

# Extract scans from Thermo .raw using Raxport
./Raxport.exe -i input.raw -o output.FT2

# Or convert to mzML using ThermoRawFileParser
ThermoRawFileParser -i=input.raw -f=1 -o=output_dir/

# Then load in R/Aerith
library(Aerith)
spectrum <- readMS2Spectrum('output.FT2', scanNumber=2596, isolationWindowWidth=5.0)

Evaluation signals

• Verify TIC (total ion current) shows expected chromatographic profile and scan frequency is consistent with acquisition method
• Inspect a sample MS2 scan: precursor m/z matches expected peptide mass (within isolation window width, e.g., ±2.5 Da for 5.0 Da window); observed peaks have m/z, intensity, and charge state populated
• Charge state information is non-null for Orbitrap data (if using Raxport); will be null for IonTrap
• Peak m/z values are numeric and sorted in ascending order; intensities are positive and scale appropriately across replicates
• No missing or malformed scan entries; total number of parsed MS2 scans matches expected count from acquisition metadata

Limitations

• Raxport extracts charge information only from Orbitrap scans; IonTrap scans will not include charge state and must be inferred downstream
• ThermoRawFileParser requires .NET Core 8 runtime on Linux/macOS; legacy versions require Mono (pre-1.5.0)
• mzML and MGF formats discard some native Thermo metadata (e.g., instrument resolution tuning); use .FT2 if full fidelity required
• Peak picking algorithms (native Thermo vs. disable with -p flag in ThermoRawFileParser) can affect observed peak positions and intensities; consistent parameter selection is critical for cross-sample comparison
• Aerith's mzR integration is limited to Bioconductor ecosystems; non-R workflows require alternative parsers (e.g., pymzML, mzLib)

Evidence

• [readme] Aerith is an R package that provides interfaces to read and write mass spectrum scans: "Aerith is an R package that provides interfaces to read and write mass spectrum scans"
• [readme] Raxport extracts scans from Thermo raw files; charge information only in Orbitrap: "Raxport is a simple program which extracts scans from raw files generated by mass spectrometers from ThermoFisher. It supports both Orbitrap and IonTrap scans. However, the generated .FT1 or .FT2"
• [readme] ThermoRawFileParser converts to multiple output formats on cross-platform: "A tool allowing reading Thermo RAW mass spectrometer files and converting to common open formats on all platforms supporting .NET Core. Supported formats: * MGF * mzML and indexed mzML * Apache"
• [intro] Aerith accepts multiple spectral data file formats: "Aerith accepts spectral data files in multiple formats, including Raxport-processed FT2, mzML, and MGF files, as well as pepXML and PIN files (Percolator outputs), and TSV files from the Sipros"
• [intro] mzR integration for parsing mzML and MGF in Aerith: "Integration with the mzR package from Bioconductor allows direct parsing of mzML and MGF files"
• [abstract] Verify data quality using TIC and scan frequency analysis: "Always verify data quality using TIC and scan frequency analysis"
• [other] Concrete task workflow specifies isolation window and parameters: "annotatePSM accepts observed peak data (m/z, intensity, charge), peptide sequence (HYAHVDCPGHADYVK), charge states (1:2), isotope atom (C13), incorporation probability (0.52), precursor m/z, and"