Isotope Adduct Anchor Identification

isotope-adduct-anchor-identification

Summary

Identify anchor mass tracks within individual LC-MS samples by detecting characteristic m/z differences corresponding to 13C/12C isotope patterns or common adducts (e.g., Na/H). These anchors serve as high-confidence reference points for cross-sample mass track alignment into a unified MassGrid.

When to use

When you have extracted mass tracks (EICs) from individual LC-MS samples and need to establish reliable landmarks for subsequent pairwise or global alignment across a cohort. This skill is essential before attempting to construct a MassGrid, especially when systematic m/z drift or sample-to-sample m/z variation is suspected. Use it when you have high mass resolution data (0.001 amu binning tolerance or better) and want to leverage isotope/adduct relationships to prioritize alignment accuracy.

When NOT to use

• Input is already a feature table or composite map (anchors must be identified on raw mass tracks before alignment).
• Mass resolution is insufficient to resolve isotope shifts reliably (e.g., low-resolution TOF or Orbitrap at <5 ppm accuracy).
• Sample cohort contains <2 samples, making cross-sample alignment unnecessary.

Inputs

• mass tracks (EICs) extracted per sample from mzML files
• binned m/z values at 0.001 amu or finer resolution
• full retention time chromatogram data for each mass track
• sample metadata (sample identifiers, optional reference sample designation)

Outputs

• anchor mass track identifiers and m/z values per sample
• isotope/adduct relationship annotations (delta m/z, type)
• reference sample ID and its anchor track set
• m/z recalibration parameters (if drift > 1 ppm detected)
• sample-wise anchor track counts and quality metrics

How to apply

For each sample, scan all extracted mass tracks for pairs or clusters that exhibit m/z differences matching known isotope shifts (e.g., 13C-12C = 1.00335 amu, or Na-H adducts = 21.98194 amu) within the specified mass resolution tolerance (typically 0.001 amu or 1 ppm). Use nearest-neighbor clustering by m/z seeds to group co-eluting or overlapping tracks, then apply pattern matching (e.g., chromatograms.extract_single_track_fullrt_length) to identify isotope ladders or adduct families. Retain only those anchor mass tracks that meet a minimum signal-to-noise and peak shape criterion (SNR and Gaussian fit quality). The reference sample is selected as the one with the highest count of anchor mass tracks (unless user-specified), and its anchor tracks are used as calibration reference for downstream m/z recalibration if systematic drift exceeds 1 ppm across the cohort.

Related tools

• chromatograms.extract_single_track_fullrt_length (Detects isotope and adduct m/z differences within a single sample's mass tracks) — https://github.com/shuzhao-li/asari
• mass_functions.nn_cluster_by_mz_seeds (Clusters overlapping m/z values by nearest-neighbor seeding to resolve co-eluting isotope/adduct families) — https://github.com/shuzhao-li/asari
• chromatograms.get_thousandth_bins (Bins and merges m/z values at 0.001 amu resolution for precise isotope/adduct detection) — https://github.com/shuzhao-li/asari
• ext_Experiment.get_reference_sample_id (Selects the reference sample based on highest count of anchor mass tracks) — https://github.com/shuzhao-li/asari
• mass2chem (Provides chemical formula utilities and adduct/isotope mass pattern lookup tables) — https://github.com/shuzhao-li/mass2chem

Examples

from asari import chromatograms, mass_functions; anchors = chromatograms.extract_single_track_fullrt_length(mass_tracks, mz_tolerance=0.001, isotope_patterns=['13C', 'Na_H'])

Evaluation signals

• Anchor track count per sample is >= 1 and consistent with expected compound complexity (typically 5–50 for metabolomics samples).
• Reference sample is correctly identified as the one with the maximum anchor track count, or matches user specification.
• All detected isotope/adduct m/z differences fall within expected ranges: 13C-12C ≈ 1.00335 ± tolerance, Na-H ≈ 21.98194 ± tolerance.
• m/z recalibration (if applied) reduces systematic drift below 1 ppm threshold across the sample cohort.
• Anchor tracks show high SNR and Gaussian-like peak shape (audit_mass_track metrics pass), indicating reliable signal.

Limitations

• Requires high mass resolution (≥ 0.001 amu precision) to reliably distinguish isotope and adduct shifts; lower-resolution instruments may produce spurious or missed anchors.
• Assumes sufficient adduct/isotope diversity in the sample; samples with few compounds or minimal isotope enrichment may yield fewer or no anchors, weakening cross-sample calibration.
• m/z recalibration is triggered only if drift exceeds 1 ppm; systematic offsets < 1 ppm are not corrected and may accumulate in larger cohorts.
• Anchor identification is deterministic and depends on predefined m/z patterns; novel adducts or post-translational modifications not in the pattern library will be missed.
• Reference sample selection by anchor count alone may not be optimal if a sample has high anchor count but poor chromatographic separation or high background noise.

Evidence

• [other] Identify anchor mass tracks by detecting m/z differences matching 13C/12C isotopes or Na/H adducts within each sample: "Identify anchor mass tracks by detecting m/z differences matching 13C/12C isotopes or Na/H adducts within each sample (chromatograms.extract_single_track_fullrt_length)."
• [other] Bin m/z values at 0.001 amu resolution, applying nearest-neighbor clustering by m/z seeds to resolve overlapping m/z values: "Extract mass tracks from each sample using pymzml and bin m/z values at 0.001 amu resolution, merging adjacent bins within tolerance and applying nearest-neighbor clustering by m/z seeds to resolve"
• [other] Select reference sample as the one with highest number of anchor mass tracks unless user-specified: "Select the reference sample as the one with the highest number of anchor mass tracks unless user-specified (ext_Experiment.get_reference_sample_id)."
• [other] Recalibrate all m/z values if systematic drift exceeds 1 ppm: "recalibrating all m/z values if systematic drift exceeds 1 ppm, then aligning remaining mass tracks (MassGrid.build_grid_sample_wise, MassGrid.add_sample)."
• [intro] High mass resolution leveraged to prioritize mass separation and alignment: "Taking advantage of high mass resolution to prioritize mass separation and alignment"
• [intro] Reproducible tracking and backtracking between features and mass tracks (EICs): "Reproducible, track and backtrack between features and mass tracks (EICs)"