Elemental composition parsing

elemental-composition-parsing

Summary

Extract and structure elemental composition (C, H, O, N, S, P counts) from assigned molecular formulas in FT-ICR MS peak data. This is a prerequisite step that prepares composition data for downstream thermodynamic index calculation and molecular characterization.

When to use

When you have FT-ICR MS peak data with assigned molecular formulas (e.g., from CoreMS, Formularity, or similar formula assignment tools) and need to compute thermodynamic indices (DBE, GFE, AImod, NOSC) or classify peaks by elemental composition. Apply this skill immediately after molecular formula assignment and filtering but before index calculation.

When NOT to use

• Peak data lacks assigned molecular formulas or formula assignment confidence is below acceptable thresholds (e.g., mass error > 0.5 ppm tolerance)
• Input is already a pre-computed feature table with derived indices; parsing is redundant
• Elemental composition data is incomplete or partially missing for significant portions of peaks

Inputs

• CSV file containing filtered FT-ICR MS peaks with assigned molecular formulas
• Elemental composition counts (C, H, O, N, S, P) per peak from formula assignment

Outputs

• Structured table (CSV or DataFrame) with columns: m/z, molecular_formula, C_count, H_count, O_count, N_count, S_count, P_count, peak_intensity

How to apply

Load the filtered peak data CSV output containing assigned molecular formulas and their elemental composition from the MetaboDirect pre-processing step. Parse each row's molecular formula string to extract or verify the count of C, H, O, N, S, and P atoms. Store these counts in a structured format (e.g., dictionary or DataFrame columns) alongside m/z and formula identifiers. Ensure all peaks with valid molecular formulas have complete elemental counts with no missing or NaN values. This parsed composition forms the input for subsequent thermodynamic index calculations using the equations in Supplementary Table 2.

Related tools

• pandas (Load, parse, and structure CSV data containing molecular formulas and elemental counts into DataFrames for index calculation)
• NumPy (Vectorize elemental count extraction and validation across multiple peaks)
• CoreMS (Upstream tool: assigns molecular formulas and provides initial elemental composition data to this skill)
• Formularity (Upstream tool: alternative formula assignment software that provides the molecular formulas and elemental counts as input)

Examples

import pandas as pd; peaks = pd.read_csv('filtered_peaks.csv'); peaks[['C','H','O','N','S','P']] = peaks['molecular_formula'].str.extract(r'C(\d+)H(\d+)O(\d+)N(\d+)S(\d+)P(\d+)', expand=True).fillna(0).astype(int); peaks.to_csv('elemental_composition.csv', index=False)

Evaluation signals

• All peaks with valid molecular formulas contain non-null C, H, O, N, S, P counts in output table
• Elemental counts match the molecular formula string (e.g., C6H12O6 has C_count=6, H_count=12, O_count=6)
• No NaN or missing values in elemental composition columns for successfully assigned formulas
• Output row count equals input peak count (no unexpected filtering or loss of records)
• Elemental counts fall within expected biological ranges (e.g., C: 3–100, H: 4–200 for typical organic metabolites)

Limitations

• Cannot parse or recover elemental counts from unassigned peaks or those with failed formula assignment
• Requires upstream mass error filtering (≤0.5 ppm recommended per article) to ensure formula assignments are reliable; elemental counts inherit errors from upstream formula assignment
• FT-ICR MS has inherent inability to separate chemical isomers; different structural arrangements yield identical elemental compositions, so parsed counts alone do not distinguish isomers
• Isotopic peaks (e.g., 13C) must be filtered out before parsing to avoid double-counting; MetaboDirect removes these during pre-processing

Evidence

• [other] Load filtered peak data with assigned molecular formulas and elemental composition (C, H, O, N, S, P counts) from the pre-processing step output as CSV.: "Load filtered peak data with assigned molecular formulas and elemental composition (C, H, O, N, S, P counts) from the pre-processing step output as CSV."
• [other] MetaboDirect calculates thermodynamic indices including double-bond equivalent (DBE), Gibbs free energy (GFE), aromaticity index (AI), and nominal oxidation state of carbon (NOSC) from the elemental composition of assigned molecular formulas to characterize metabolite properties such as saturation, lability, and degree of oxidation.: "MetaboDirect calculates thermodynamic indices including double-bond equivalent (DBE), Gibbs free energy (GFE), aromaticity index (AI), and nominal oxidation state of carbon (NOSC) from the elemental"
• [other] For each peak's elemental composition, calculate the nominal oxidation state of carbon (NOSC) using the elemental composition equation from Supplementary Table 2.: "For each peak's elemental composition, calculate the nominal oxidation state of carbon (NOSC) using the elemental composition equation"
• [other] all peaks with valid molecular formulas receive four index values; no missing or NaN values in output; indices fall within expected biological ranges for organic matter.: "all peaks with valid molecular formulas receive four index values; no missing or NaN values in output"
• [methods] detected peaks are filtered by their m/z values (based on the user's input), isotopic presence (13C peaks), and error in formula assignment (0.5 ppm): "detected peaks are filtered by their m/z values (based on the user's input), isotopic presence (13C peaks), and error in formula assignment (0.5 ppm)"