mass-spectrometry-molecular-formula-handling
Summary
Assign molecular formulas to detected m/z peaks in high-resolution FT-ICR MS data and filter results by mass accuracy and isotopic consistency. This is a foundational preprocessing step that converts raw peak lists into chemically interpretable, annotated peak tables suitable for downstream analysis.
When to use
You have raw or processed FT-ICR MS spectra with detected peaks (m/z values) and need to: (1) assign elemental compositions to each peak, (2) filter assignments by mass error tolerance and isotopic presence, or (3) prepare a peak table with molecular formula annotations for chemodiversity analysis, transformation network generation, or multivariate statistics. This skill is essential before any biochemical interpretation of the data.
When NOT to use
- Input already contains pre-assigned, validated molecular formulas from a peer-reviewed database (e.g., HMDB); use direct lookup instead.
- Data is low-resolution MS (e.g., TOF or Orbitrap without sub-ppm accuracy); mass error tolerance cannot reliably differentiate isomers.
- Peak list includes already-normalized relative abundances without raw intensity values; isotopic filtering and compound class assignment may be unreliable.
- Samples are from a biological matrix where signal suppression or ion-pairing effects are uncharacterized; formula assignment error may be non-random.
Inputs
- CSV file with detected m/z values and peak abundances per sample
- Raw FT-ICR MS spectra (optional; formula assignment may require full spectral data)
- User-defined filtering parameters: mass error threshold (ppm), minimum sample presence count
Outputs
- Peak abundance matrix with assigned molecular formulas and compound classes
- Filtered peak list (CSV) containing m/z, molecular formula, compound class, and normalized abundance per sample
- Filtering summary report (number of peaks retained/removed at each filter step)
- Elemental composition table (H, C, N, O, S, P counts per peak)
How to apply
Load the detected peak list (CSV with m/z values) into a formula assignment tool (e.g., Formularity, CoreMS, or MetaboDirect's integrated assignment module). Apply mass error filtering at ≤0.5 ppm against theoretical formula masses to retain only high-confidence assignments. Remove isotopic peaks (e.g., 13C peaks) to avoid redundant counting. Filter peaks based on a user-defined minimum presence threshold (number of samples in which the peak must appear) to exclude noise. Classify each formula-assigned peak into a molecular compound class (e.g., lipid, carbohydrate, aromatic, aliphatic) based on elemental composition ratios (H/C, O/C, N/C). Output a normalized, filtered peak abundance matrix (rows = peaks with formula and compound class; columns = samples) suitable for downstream analysis.
Related tools
- MetaboDirect (Integrated pipeline for molecular formula assignment, filtering, and output of normalized peak tables with compound class annotations) — https://github.com/Coayala/MetaboDirect
- Formularity (Open-source software for molecular formula assignment to high-resolution MS peaks)
- CoreMS (Comprehensive software framework providing formula assignment and spectral processing for FT-ICR MS data)
- KEGG database (Optional reference database for validation and mapping of assigned formulas to known metabolites)
Examples
metabodirect --input peaks_abundance.csv --formula-error 0.5 --min-presence 2 --output-dir ./results
Evaluation signals
- All assigned formulas have mass error ≤0.5 ppm against theoretical m/z values; verify by calculating |theoretical m/z − observed m/z| / theoretical m/z × 1e6.
- Isotopic peaks (13C, 18O, 34S) are identified and removed; check that 1.003 Da mass shifts and expected intensity ratios are absent in filtered peak list.
- Elemental composition ratios (H/C, O/C, N/C) fall within biologically plausible ranges (e.g., H/C 0.3–2.5, O/C 0–1.5 for natural organic matter); plot Van Krevelen diagram to verify distribution.
- Peak retention rate after filtering aligns with article benchmarks: e.g., bacterium-phage model system retained
495 assigned formulas from ~1025 detected peaks (48%).
- Output CSV contains no missing values in formula or compound class columns; row count matches expected sample size and presence threshold.
Limitations
- Mass error filtering at 0.5 ppm assumes instrument calibration is stable and accurately mass-calibrated; drift or poor calibration will increase false-negative formula assignments.
- Formula assignment is non-unique at high m/z; multiple distinct molecular formulas may match the same observed m/z within error tolerance. Rank by chemical likelihood (e.g., nitrogen rule, hydrogen deficiency index) but acknowledge ambiguity.
- Isotopic filtering assumes natural isotope abundances; enriched samples (e.g., 13C-labeled, 15N-labeled) will be incorrectly removed as noise.
- Signal suppression and ion-pairing in direct injection (DI) MS can produce non-stoichiometric peak intensities and false formula assignments; the article notes DI MS 'drawbacks include … signal suppression or enhancement that can confound downstream data analysis'.
- Compound class assignment is coarse and based on bulk H/C, O/C ratios; isomers and structurally distinct molecules with identical elemental composition cannot be resolved.
Evidence
- [intro] MetaboDirect pipeline accepts peak abundance and assigned molecular formula data produced after an initial processing of raw FT-ICR MS spectra or any other high-resolution MS technique.: "The pipeline accepts peak abundance and assigned molecular formula data produced after an initial processing of raw FT-ICR MS spectra or any other high-resolution MS technique"
- [methods] Peaks are filtered by m/z values, isotopic presence, formula assignment error, and sample presence count; compound classes are then determined.: "detected peaks are filtered by their m/z values, isotopic presence (13C peaks), error in formula assignment (0.5 ppm), and based on the number of samples that they are present in (threshold"
- [intro] Signal processing and molecular formula assignment steps produce large data matrices with elemental composition and measured abundance of peaks in each sample.: "Signal processing and molecular formula assignment steps will ultimately produce large data matrices containing the elemental composition and measured abundance of the peaks present in each sample"
- [results] Bacterium-phage dataset example: average of 1025 peaks detected, average of 495 peaks assigned molecular formula (~48% retention).: "The data set had an average of 1025 peaks detected across the whole data set (n = 36 samples) and an average of 495 peaks that got assigned a molecular formula"
- [intro] Direct injection MS drawbacks include inability to separate isomers, lack of fine resolving power, and signal suppression that can confound downstream analysis.: "drawbacks are its inability to separate chemical isomers, lack of fine resolving power, and most importantly signal suppression or enhancement that can confound downstream data analysis"
- [methods] MetaboDirect does not provide raw spectra data preprocessing; it assumes molecular formula assignment has been completed prior to input.: "MetaboDirect does not provide raw spectra data preprocessing"
1---2name: mass-spectrometry-molecular-formula-handling3description: Use when you have raw or processed FT-ICR MS spectra with detected peaks (m/z values) and need to: (1) assign elemental compositions to each peak, (2) filter assignments by mass error tolerance and isotopic presence, or (3) prepare a peak table with molecular formula annotations for chemodiversity.4license: CC-BY-4.05---67# mass-spectrometry-molecular-formula-handling89## Summary1011Assign molecular formulas to detected m/z peaks in high-resolution FT-ICR MS data and filter results by mass accuracy and isotopic consistency. This is a foundational preprocessing step that converts raw peak lists into chemically interpretable, annotated peak tables suitable for downstream analysis.1213## When to use1415You have raw or processed FT-ICR MS spectra with detected peaks (m/z values) and need to: (1) assign elemental compositions to each peak, (2) filter assignments by mass error tolerance and isotopic presence, or (3) prepare a peak table with molecular formula annotations for chemodiversity analysis, transformation network generation, or multivariate statistics. This skill is essential before any biochemical interpretation of the data.1617## When NOT to use1819- Input already contains pre-assigned, validated molecular formulas from a peer-reviewed database (e.g., HMDB); use direct lookup instead.20- Data is low-resolution MS (e.g., TOF or Orbitrap without sub-ppm accuracy); mass error tolerance cannot reliably differentiate isomers.21- Peak list includes already-normalized relative abundances without raw intensity values; isotopic filtering and compound class assignment may be unreliable.22- Samples are from a biological matrix where signal suppression or ion-pairing effects are uncharacterized; formula assignment error may be non-random.2324## Inputs2526- CSV file with detected m/z values and peak abundances per sample27- Raw FT-ICR MS spectra (optional; formula assignment may require full spectral data)28- User-defined filtering parameters: mass error threshold (ppm), minimum sample presence count2930## Outputs3132- Peak abundance matrix with assigned molecular formulas and compound classes33- Filtered peak list (CSV) containing m/z, molecular formula, compound class, and normalized abundance per sample34- Filtering summary report (number of peaks retained/removed at each filter step)35- Elemental composition table (H, C, N, O, S, P counts per peak)3637## How to apply3839Load the detected peak list (CSV with m/z values) into a formula assignment tool (e.g., Formularity, CoreMS, or MetaboDirect's integrated assignment module). Apply mass error filtering at ≤0.5 ppm against theoretical formula masses to retain only high-confidence assignments. Remove isotopic peaks (e.g., 13C peaks) to avoid redundant counting. Filter peaks based on a user-defined minimum presence threshold (number of samples in which the peak must appear) to exclude noise. Classify each formula-assigned peak into a molecular compound class (e.g., lipid, carbohydrate, aromatic, aliphatic) based on elemental composition ratios (H/C, O/C, N/C). Output a normalized, filtered peak abundance matrix (rows = peaks with formula and compound class; columns = samples) suitable for downstream analysis.4041## Related tools4243- **MetaboDirect** (Integrated pipeline for molecular formula assignment, filtering, and output of normalized peak tables with compound class annotations) — https://github.com/Coayala/MetaboDirect44- **Formularity** (Open-source software for molecular formula assignment to high-resolution MS peaks)45- **CoreMS** (Comprehensive software framework providing formula assignment and spectral processing for FT-ICR MS data)46- **KEGG database** (Optional reference database for validation and mapping of assigned formulas to known metabolites)4748## Examples4950```51metabodirect --input peaks_abundance.csv --formula-error 0.5 --min-presence 2 --output-dir ./results52```5354## Evaluation signals5556- All assigned formulas have mass error ≤0.5 ppm against theoretical m/z values; verify by calculating |theoretical m/z − observed m/z| / theoretical m/z × 1e6.57- Isotopic peaks (13C, 18O, 34S) are identified and removed; check that 1.003 Da mass shifts and expected intensity ratios are absent in filtered peak list.58- Elemental composition ratios (H/C, O/C, N/C) fall within biologically plausible ranges (e.g., H/C 0.3–2.5, O/C 0–1.5 for natural organic matter); plot Van Krevelen diagram to verify distribution.59- Peak retention rate after filtering aligns with article benchmarks: e.g., bacterium-phage model system retained ~495 assigned formulas from ~1025 detected peaks (~48%).60- Output CSV contains no missing values in formula or compound class columns; row count matches expected sample size and presence threshold.6162## Limitations6364- Mass error filtering at 0.5 ppm assumes instrument calibration is stable and accurately mass-calibrated; drift or poor calibration will increase false-negative formula assignments.65- Formula assignment is non-unique at high m/z; multiple distinct molecular formulas may match the same observed m/z within error tolerance. Rank by chemical likelihood (e.g., nitrogen rule, hydrogen deficiency index) but acknowledge ambiguity.66- Isotopic filtering assumes natural isotope abundances; enriched samples (e.g., 13C-labeled, 15N-labeled) will be incorrectly removed as noise.67- Signal suppression and ion-pairing in direct injection (DI) MS can produce non-stoichiometric peak intensities and false formula assignments; the article notes DI MS 'drawbacks include … signal suppression or enhancement that can confound downstream data analysis'.68- Compound class assignment is coarse and based on bulk H/C, O/C ratios; isomers and structurally distinct molecules with identical elemental composition cannot be resolved.6970## Evidence7172- [intro] MetaboDirect pipeline accepts peak abundance and assigned molecular formula data produced after an initial processing of raw FT-ICR MS spectra or any other high-resolution MS technique.: "The pipeline accepts peak abundance and assigned molecular formula data produced after an initial processing of raw FT-ICR MS spectra or any other high-resolution MS technique"73- [methods] Peaks are filtered by m/z values, isotopic presence, formula assignment error, and sample presence count; compound classes are then determined.: "detected peaks are filtered by their m/z values, isotopic presence (13C peaks), error in formula assignment (0.5 ppm), and based on the number of samples that they are present in (threshold"74- [intro] Signal processing and molecular formula assignment steps produce large data matrices with elemental composition and measured abundance of peaks in each sample.: "Signal processing and molecular formula assignment steps will ultimately produce large data matrices containing the elemental composition and measured abundance of the peaks present in each sample"75- [results] Bacterium-phage dataset example: average of 1025 peaks detected, average of 495 peaks assigned molecular formula (~48% retention).: "The data set had an average of 1025 peaks detected across the whole data set (n = 36 samples) and an average of 495 peaks that got assigned a molecular formula"76- [intro] Direct injection MS drawbacks include inability to separate isomers, lack of fine resolving power, and signal suppression that can confound downstream analysis.: "drawbacks are its inability to separate chemical isomers, lack of fine resolving power, and most importantly signal suppression or enhancement that can confound downstream data analysis"77- [methods] MetaboDirect does not provide raw spectra data preprocessing; it assumes molecular formula assignment has been completed prior to input.: "MetaboDirect does not provide raw spectra data preprocessing"
HolobiomicsLab