peak-picking-parameter-configuration
Summary
Configure noise thresholds and peak-scoring parameters to convert experimental MS/MS spectra into scored fragment ion entries for metabolite library generation. This skill controls which peaks are retained during library entry creation and how their abundance is ranked relative to noise.
When to use
When reconstructing a metabolite fragment library entry from raw MS/MS spectral data (e.g., from MassBank or local acquisition), you need to define peak-picking thresholds to separate true fragment ions from baseline noise and assign occurrence scores. Apply this skill before exporting the processed library entry as a structured record (CSV, msp, or database entry).
When NOT to use
- Input is already a processed feature table from xcms or RamClustR — you need raw spectral data, not pre-clustered features.
- Spectrum data is in profile (continuous) mode rather than centroid mode — genFragEntry expects centroid peaks.
- You are performing feature-level annotation on already-detected features; use annotateRC instead to match features against libraries.
Inputs
- Centroid-mode MS/MS spectrum (vector of m/z and intensity pairs)
- Metabolite name (string)
- Adduct name (string, e.g. '[M+H]+')
- Accurate adduct m/z (float)
- Output filename (string path)
Outputs
- Metabolite library entry (CSV file with columns: metabolite_id, fragment_m/z, occurrence_score, peak_intensity)
- Scored fragment ion list (R data frame or table object)
How to apply
Invoke the genFragEntry function with explicit specification of four peak-picking parameters: (1) noise — baseline noise level (default 0.005), used to filter low-intensity peaks; (2) mpeaksThres — relative intensity threshold for peak inclusion (default 0.1, meaning peaks must exceed 10% of max intensity); (3) mpeaksScore — threshold for attributing occurrence scores to retained peaks (default 0.9, meaning only peaks with normalized intensity ≥ 0.9 are scored); (4) mzTol — mass tolerance for peak matching (default 0.01 m/z units). Supply the metabolite name, adduct name (e.g., '[M+H]+'), accurate adduct m/z value, and centroid-mode spectrum data. The function ranks fragment ions by scored abundance and exports the result as a CSV file annotated with metabolite identifier, fragment masses, and occurrence scores. Parameter selection should reflect the signal-to-noise ratio and dynamic range of your instrument; higher thresholds exclude minor fragments but reduce false positives from chemical noise.
Related tools
- MetaboAnnotatoR (R package providing the genFragEntry function for converting MS/MS spectra into scored library entries) — https://github.com/gggraca/MetaboAnnotatoR
- R (Language runtime for executing genFragEntry and parameter-setting commands (version 4.5.0 or higher))
- MassBank (Public database providing reference MS/MS spectra (e.g., MSBNK-RIKEN-PR100295) to demonstrate parameter tuning)
Examples
genFragEntry(spectrum_data, metabolite_name='D-Pantothenic Acid', adduct_name='[M+H]+', adduct_mz=220.1201, output_file='pantothenic_lib.csv', noise=0.005, mpeaksThres=0.1, mpeaksScore=0.9, mzTol=0.01)
Evaluation signals
- Verify that output CSV contains only peaks with m/z values ≥ noise threshold and normalized intensity ≥ mpeaksThres.
- Check that occurrence scores are assigned only to peaks meeting mpeaksScore threshold (default 0.9), with unscored peaks marked as NA or 0.
- Confirm that the number of retained fragments is consistent with expected fragmentation complexity for the metabolite class (lipids typically show fewer major fragments than amino acids).
- Validate that m/z differences between related fragment ions fall within mzTol tolerance for potential isotope or neutral-loss annotation.
- Cross-check occurrence scores against raw spectrum intensity values to ensure monotonic ranking (highest m/z abundance → highest score).
Limitations
- Default parameters (noise=0.005, mpeaksThres=0.1, mpeaksScore=0.9, mzTol=0.01) are tuned for typical LC-MS AIF data but may require adjustment for low-abundance metabolites, high-background samples, or instruments with different resolving power.
- Peak-picking is sensitive to baseline calibration; miscalibrated or drifting baseline can inflate noise threshold and exclude true low-intensity fragments.
- The function requires centroid-mode spectra; profile-mode data must be converted first using external tools (e.g., xcms centWave).
- Occurrence scores do not account for biological prior knowledge or fragmentation chemistry; parameter tuning must be validated against known MS/MS spectra from the same instrument and sample matrix.
Evidence
- [other] Default parameters controlling peak-picking thresholds: "default parameters: noise=0.005, mpeaksScore=0.9, mpeaksThres=0.1, and mzTol=0.01"
- [other] Function converts spectra into library entries via peak occurrence scoring: "The genFragEntry function converts MS/MS spectra into library entries by attributing occurrence scores to peaks above the mpeaksThres threshold and noise level"
- [other] Required metabolite and adduct specification for library entry generation: "with metabolite name, adduct name, accurate adduct m/z, and output filename explicitly specified"
- [readme] Package designed for centroid-mode LC-MS data: "It requires raw LC-MS AIF chromatograms acquired/transformed in centroid mode."
- [readme] Library generation from experimental spectra is a distinct vignette topic: "Generation of Metabolite fragment database entry from MS/MS experimental spectra."
1---2name: peak-picking-parameter-configuration3description: Use when when reconstructing a metabolite fragment library entry from raw MS/MS spectral data (e.g., from MassBank or local acquisition), you need to define peak-picking thresholds to separate true fragment ions from baseline noise and assign occurrence scores.4license: CC-BY-4.05---67# peak-picking-parameter-configuration89## Summary1011Configure noise thresholds and peak-scoring parameters to convert experimental MS/MS spectra into scored fragment ion entries for metabolite library generation. This skill controls which peaks are retained during library entry creation and how their abundance is ranked relative to noise.1213## When to use1415When reconstructing a metabolite fragment library entry from raw MS/MS spectral data (e.g., from MassBank or local acquisition), you need to define peak-picking thresholds to separate true fragment ions from baseline noise and assign occurrence scores. Apply this skill before exporting the processed library entry as a structured record (CSV, msp, or database entry).1617## When NOT to use1819- Input is already a processed feature table from xcms or RamClustR — you need raw spectral data, not pre-clustered features.20- Spectrum data is in profile (continuous) mode rather than centroid mode — genFragEntry expects centroid peaks.21- You are performing feature-level annotation on already-detected features; use annotateRC instead to match features against libraries.2223## Inputs2425- Centroid-mode MS/MS spectrum (vector of m/z and intensity pairs)26- Metabolite name (string)27- Adduct name (string, e.g. '[M+H]+')28- Accurate adduct m/z (float)29- Output filename (string path)3031## Outputs3233- Metabolite library entry (CSV file with columns: metabolite_id, fragment_m/z, occurrence_score, peak_intensity)34- Scored fragment ion list (R data frame or table object)3536## How to apply3738Invoke the genFragEntry function with explicit specification of four peak-picking parameters: (1) noise — baseline noise level (default 0.005), used to filter low-intensity peaks; (2) mpeaksThres — relative intensity threshold for peak inclusion (default 0.1, meaning peaks must exceed 10% of max intensity); (3) mpeaksScore — threshold for attributing occurrence scores to retained peaks (default 0.9, meaning only peaks with normalized intensity ≥ 0.9 are scored); (4) mzTol — mass tolerance for peak matching (default 0.01 m/z units). Supply the metabolite name, adduct name (e.g., '[M+H]+'), accurate adduct m/z value, and centroid-mode spectrum data. The function ranks fragment ions by scored abundance and exports the result as a CSV file annotated with metabolite identifier, fragment masses, and occurrence scores. Parameter selection should reflect the signal-to-noise ratio and dynamic range of your instrument; higher thresholds exclude minor fragments but reduce false positives from chemical noise.3940## Related tools4142- **MetaboAnnotatoR** (R package providing the genFragEntry function for converting MS/MS spectra into scored library entries) — https://github.com/gggraca/MetaboAnnotatoR43- **R** (Language runtime for executing genFragEntry and parameter-setting commands (version 4.5.0 or higher))44- **MassBank** (Public database providing reference MS/MS spectra (e.g., MSBNK-RIKEN-PR100295) to demonstrate parameter tuning)4546## Examples4748```49genFragEntry(spectrum_data, metabolite_name='D-Pantothenic Acid', adduct_name='[M+H]+', adduct_mz=220.1201, output_file='pantothenic_lib.csv', noise=0.005, mpeaksThres=0.1, mpeaksScore=0.9, mzTol=0.01)50```5152## Evaluation signals5354- Verify that output CSV contains only peaks with m/z values ≥ noise threshold and normalized intensity ≥ mpeaksThres.55- Check that occurrence scores are assigned only to peaks meeting mpeaksScore threshold (default 0.9), with unscored peaks marked as NA or 0.56- Confirm that the number of retained fragments is consistent with expected fragmentation complexity for the metabolite class (lipids typically show fewer major fragments than amino acids).57- Validate that m/z differences between related fragment ions fall within mzTol tolerance for potential isotope or neutral-loss annotation.58- Cross-check occurrence scores against raw spectrum intensity values to ensure monotonic ranking (highest m/z abundance → highest score).5960## Limitations6162- Default parameters (noise=0.005, mpeaksThres=0.1, mpeaksScore=0.9, mzTol=0.01) are tuned for typical LC-MS AIF data but may require adjustment for low-abundance metabolites, high-background samples, or instruments with different resolving power.63- Peak-picking is sensitive to baseline calibration; miscalibrated or drifting baseline can inflate noise threshold and exclude true low-intensity fragments.64- The function requires centroid-mode spectra; profile-mode data must be converted first using external tools (e.g., xcms centWave).65- Occurrence scores do not account for biological prior knowledge or fragmentation chemistry; parameter tuning must be validated against known MS/MS spectra from the same instrument and sample matrix.6667## Evidence6869- [other] Default parameters controlling peak-picking thresholds: "default parameters: noise=0.005, mpeaksScore=0.9, mpeaksThres=0.1, and mzTol=0.01"70- [other] Function converts spectra into library entries via peak occurrence scoring: "The genFragEntry function converts MS/MS spectra into library entries by attributing occurrence scores to peaks above the mpeaksThres threshold and noise level"71- [other] Required metabolite and adduct specification for library entry generation: "with metabolite name, adduct name, accurate adduct m/z, and output filename explicitly specified"72- [readme] Package designed for centroid-mode LC-MS data: "It requires raw LC-MS AIF chromatograms acquired/transformed in centroid mode."73- [readme] Library generation from experimental spectra is a distinct vignette topic: "Generation of Metabolite fragment database entry from MS/MS experimental spectra."
HolobiomicsLab