adduct-and-fragment-neutral-mass-calculation
Summary
Calculate neutral mass candidates from observed LC-MS peak m/z values by applying precomputed adduct and in-source fragment transformations from a reference table. This is the foundational step in mWISE's matching stage that enables annotation of peaks against the KEGG database.
When to use
You have an LC-MS peak-intensity matrix with observed m/z values (from negative or positive mode ionization) and need to map each peak to candidate neutral masses in KEGG. Use this skill when you have a curated Cpd.Add reference table (built from CAMERA, cliqueMS, and literature sources) and want to systematically explore all plausible neutral mass interpretations before KEGG compound matching.
When NOT to use
- Your peaks are already assigned to KEGG compounds or metabolite identities; this skill is for candidate generation, not refinement.
- You lack a polarity specification (negative or positive mode) or the ionization mode is unknown or mixed.
- You have no curated adduct/fragment reference table and cannot construct or download one from CAMERA, cliqueMS, or literature sources.
Inputs
- Peak.List: peak-intensity matrix (rows = peaks, columns include m/z values)
- Cpd.Add table: reference table of KEGG compounds with precomputed adducts and fragments (mass deltas, ionization modes)
- polarity: ionization mode setting (negative or positive)
Outputs
- Peak.Cpd candidate table: matrix where each row is a detected peak and columns contain matched KEGG identifiers with scoring metrics
- Peak.List: original peak-intensity matrix (preserved in output list)
How to apply
Load the Peak.List (peak-intensity matrix with m/z column) and the Cpd.Add table containing adducts and fragments with their mass deltas and ionization modes. For each observed m/z, apply the inverse transformation of each applicable adduct/fragment (e.g., subtract the adduct mass delta or add back the fragment mass loss) to recover candidate neutral masses. Filter adducts/fragments by polarity setting (negative or positive mode) to avoid incorrect candidates. The matchingStage function in mWISE automates this process: it tests all possible neutral mass candidates derived from the Cpd.Add adducts and fragments for each observed peak, then returns an annotated Peak.Cpd table mapping each peak to KEGG identifiers with associated scoring metrics.
Related tools
- mWISE (Implements matchingStage function that orchestrates neutral mass calculation and KEGG candidate matching) — https://dev.b2s.club/b2slab/mWISE
- CAMERA (Source of default adduct and fragment definitions used to build the Cpd.Add reference table)
- cliqueMS (Contributes adduct and fragment information to the Cpd.Add reference table)
- R (Execution environment for mWISE and the matchingStage function)
- KEGG database (Source of compound identifiers and exact masses matched against calculated neutral mass candidates)
Examples
data(sample.dataset); data(Cpd.Add); result <- matchingStage(Peak.List = sample.dataset$Peak.List, Cpd.Add = Cpd.Add, polarity = 'negative')
Evaluation signals
- The output Peak.Cpd table has one row per input peak and includes valid KEGG identifiers in matched candidate columns.
- No negative or null neutral masses are produced; all calculated masses are physically plausible (typically 50–2000 Da for small metabolites).
- Adduct/fragment filtering by polarity is correct: negative-mode peaks are matched only against adducts/fragments appropriate for negative ionization, and vice versa.
- A spot-check of 3–5 peaks confirms that at least one calculated neutral mass per peak falls within expected mass tolerance (typically ±5 ppm) of a known KEGG compound.
- The Peak.Cpd output is a matrix or data frame with consistent schema (peak identifiers, KEGG IDs, scores) matching the mWISE Peak.Cpd specification.
Limitations
- Accuracy depends on completeness and correctness of the Cpd.Add table; missing or incorrectly parameterized adducts/fragments will produce incomplete or incorrect candidates.
- Multiple neutral masses from a single observed m/z may be equally plausible within mass tolerance, leading to ambiguous candidate lists; downstream filtering (clustering, network diffusion) is required to prioritize.
- In-source fragmentation patterns are heuristic and may not capture all adduct/fragment possibilities for complex matrices or unusual ionization conditions.
- No integration of retention time, isotope patterns, or spectral similarity at this stage; those signals are used only in later mWISE stages (diffusion prioritization).
Evidence
- [intro] matching mass-to-charge ratio values to KEGG database using adducts and in-source fragments: "matching mass-to-charge ratio values to KEGG database using adducts and in-source fragments"
- [intro] The matchingStage function accepts a Peak.List (peak-intensity matrix), a Cpd.Add table of KEGG compounds with adducts/fragments, and a polarity setting, and returns a list containing the original Peak.List and an annotated Peak.Cpd table mapping peaks to KEGG candidate compounds.: "The matchingStage function accepts a Peak.List (peak-intensity matrix), a Cpd.Add table of KEGG compounds with adducts/fragments, and a polarity setting, and returns a list containing the original"
- [intro] the matchingStage function from mWISE to match each observed m/z value against the KEGG database by testing all possible neutral mass candidates derived from the Cpd.Add adducts and fragments.: "the matchingStage function from mWISE to match each observed m/z value against the KEGG database by testing all possible neutral mass candidates derived from the Cpd.Add adducts and fragments."
- [intro] The default table of adducts and fragments is built using information from CAMERA R package: "The default table of adducts and fragments is built using information from CAMERA R package"
- [intro] mWISE (metabolomics Wise Inference of Speck Entities) is an R package that provides tools for context-based annotation of untargeted LC-MS data.: "mWISE (metabolomics Wise Inference of Speck Entities) is an R package that provides tools for context-based annotation of untargeted LC-MS data."
1---2name: adduct-and-fragment-neutral-mass-calculation3description: Use when you have an LC-MS peak-intensity matrix with observed m/z values (from negative or positive mode ionization) and need to map each peak to candidate neutral masses in KEGG. Use this skill when you have a curated Cpd.4license: CC-BY-4.05---67# adduct-and-fragment-neutral-mass-calculation89## Summary1011Calculate neutral mass candidates from observed LC-MS peak m/z values by applying precomputed adduct and in-source fragment transformations from a reference table. This is the foundational step in mWISE's matching stage that enables annotation of peaks against the KEGG database.1213## When to use1415You have an LC-MS peak-intensity matrix with observed m/z values (from negative or positive mode ionization) and need to map each peak to candidate neutral masses in KEGG. Use this skill when you have a curated Cpd.Add reference table (built from CAMERA, cliqueMS, and literature sources) and want to systematically explore all plausible neutral mass interpretations before KEGG compound matching.1617## When NOT to use1819- Your peaks are already assigned to KEGG compounds or metabolite identities; this skill is for candidate generation, not refinement.20- You lack a polarity specification (negative or positive mode) or the ionization mode is unknown or mixed.21- You have no curated adduct/fragment reference table and cannot construct or download one from CAMERA, cliqueMS, or literature sources.2223## Inputs2425- Peak.List: peak-intensity matrix (rows = peaks, columns include m/z values)26- Cpd.Add table: reference table of KEGG compounds with precomputed adducts and fragments (mass deltas, ionization modes)27- polarity: ionization mode setting (negative or positive)2829## Outputs3031- Peak.Cpd candidate table: matrix where each row is a detected peak and columns contain matched KEGG identifiers with scoring metrics32- Peak.List: original peak-intensity matrix (preserved in output list)3334## How to apply3536Load the Peak.List (peak-intensity matrix with m/z column) and the Cpd.Add table containing adducts and fragments with their mass deltas and ionization modes. For each observed m/z, apply the inverse transformation of each applicable adduct/fragment (e.g., subtract the adduct mass delta or add back the fragment mass loss) to recover candidate neutral masses. Filter adducts/fragments by polarity setting (negative or positive mode) to avoid incorrect candidates. The matchingStage function in mWISE automates this process: it tests all possible neutral mass candidates derived from the Cpd.Add adducts and fragments for each observed peak, then returns an annotated Peak.Cpd table mapping each peak to KEGG identifiers with associated scoring metrics.3738## Related tools3940- **mWISE** (Implements matchingStage function that orchestrates neutral mass calculation and KEGG candidate matching) — https://dev.b2s.club/b2slab/mWISE41- **CAMERA** (Source of default adduct and fragment definitions used to build the Cpd.Add reference table)42- **cliqueMS** (Contributes adduct and fragment information to the Cpd.Add reference table)43- **R** (Execution environment for mWISE and the matchingStage function)44- **KEGG database** (Source of compound identifiers and exact masses matched against calculated neutral mass candidates)4546## Examples4748```49data(sample.dataset); data(Cpd.Add); result <- matchingStage(Peak.List = sample.dataset$Peak.List, Cpd.Add = Cpd.Add, polarity = 'negative')50```5152## Evaluation signals5354- The output Peak.Cpd table has one row per input peak and includes valid KEGG identifiers in matched candidate columns.55- No negative or null neutral masses are produced; all calculated masses are physically plausible (typically 50–2000 Da for small metabolites).56- Adduct/fragment filtering by polarity is correct: negative-mode peaks are matched only against adducts/fragments appropriate for negative ionization, and vice versa.57- A spot-check of 3–5 peaks confirms that at least one calculated neutral mass per peak falls within expected mass tolerance (typically ±5 ppm) of a known KEGG compound.58- The Peak.Cpd output is a matrix or data frame with consistent schema (peak identifiers, KEGG IDs, scores) matching the mWISE Peak.Cpd specification.5960## Limitations6162- Accuracy depends on completeness and correctness of the Cpd.Add table; missing or incorrectly parameterized adducts/fragments will produce incomplete or incorrect candidates.63- Multiple neutral masses from a single observed m/z may be equally plausible within mass tolerance, leading to ambiguous candidate lists; downstream filtering (clustering, network diffusion) is required to prioritize.64- In-source fragmentation patterns are heuristic and may not capture all adduct/fragment possibilities for complex matrices or unusual ionization conditions.65- No integration of retention time, isotope patterns, or spectral similarity at this stage; those signals are used only in later mWISE stages (diffusion prioritization).6667## Evidence6869- [intro] matching mass-to-charge ratio values to KEGG database using adducts and in-source fragments: "matching mass-to-charge ratio values to KEGG database using adducts and in-source fragments"70- [intro] The matchingStage function accepts a Peak.List (peak-intensity matrix), a Cpd.Add table of KEGG compounds with adducts/fragments, and a polarity setting, and returns a list containing the original Peak.List and an annotated Peak.Cpd table mapping peaks to KEGG candidate compounds.: "The matchingStage function accepts a Peak.List (peak-intensity matrix), a Cpd.Add table of KEGG compounds with adducts/fragments, and a polarity setting, and returns a list containing the original"71- [intro] the matchingStage function from mWISE to match each observed m/z value against the KEGG database by testing all possible neutral mass candidates derived from the Cpd.Add adducts and fragments.: "the matchingStage function from mWISE to match each observed m/z value against the KEGG database by testing all possible neutral mass candidates derived from the Cpd.Add adducts and fragments."72- [intro] The default table of adducts and fragments is built using information from CAMERA R package: "The default table of adducts and fragments is built using information from CAMERA R package"73- [intro] mWISE (metabolomics Wise Inference of Speck Entities) is an R package that provides tools for context-based annotation of untargeted LC-MS data.: "mWISE (metabolomics Wise Inference of Speck Entities) is an R package that provides tools for context-based annotation of untargeted LC-MS data."
