Mass To Charge Matching Tolerance Tuning

---
name: mass-to-charge-matching-tolerance-tuning
description: Use when you are preparing to align two or more nontargeted LCMS datasets from the same analytical method using Eclipse and need to determine the m/z tolerance window.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3633
  edam_topics:
  - http://edamontology.org/topic_3172
  - http://edamontology.org/topic_0091
  tools:
  - bmxp
  - Python
  - Eclipse
  techniques:
  - LC-MS
derived_from:
- doi: 10.1093/bioinformatics/btaf290/8128335
  title: Eclipse
evidence_spans:
- pip install bmxp
- They are written in Python and C
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_eclipse_cq
    doi: 10.1093/bioinformatics/btaf290/8128335
    title: Eclipse
  dedup_kept_from: coll_eclipse_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1093/bioinformatics/btaf290/8128335
  all_source_dois:
  - 10.1093/bioinformatics/btaf290/8128335
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# mass-to-charge-matching-tolerance-tuning

## Summary

Tune m/z matching tolerance thresholds during cross-dataset LCMS feature alignment to balance false-positive and false-negative feature correspondence rates. Proper tolerance selection is critical for Eclipse module operation, as it governs which candidate feature pairs pass the initial m/z-based matching stage before retention-time refinement.

## When to use

You are preparing to align two or more nontargeted LCMS datasets from the same analytical method using Eclipse and need to determine the m/z tolerance window. This skill applies when you have parsed feature metadata (m/z, retention time, intensity distributions) across datasets and are ready to identify candidate feature pairs but lack an empirically validated tolerance threshold for your specific instrument, method, or sample type.

## When NOT to use

- Input datasets are from different LCMS analytical methods (Eclipse requires same-method datasets; cross-method alignment requires different preprocessing)
- Feature metadata is not yet normalized or contains mixed scale/unit conventions for m/z or RT
- You lack prior knowledge or validation data for instrument m/z accuracy; tuning tolerance without instrument characterization may lead to arbitrary thresholds

## Inputs

- Two or more nontargeted LCMS feature tables in tabular format (same analytical method)
- Feature metadata including m/z, retention time, and intensity values
- Feature metadata normalized across datasets (parsed, no unit/scale mismatches)

## Outputs

- Candidate feature pair list (m/z-matched features prior to RT refinement)
- Matched feature correspondence table linking features across datasets
- Alignment confidence scores per matched feature pair

## How to apply

Eclipse applies m/z-based matching with a tolerance threshold to identify candidate feature pairs across datasets. The tolerance value (typically expressed in ppm or absolute Da) sets the maximum m/z deviation allowed for two features from different datasets to be considered a match candidate. Start with a conservative threshold (e.g., instrument resolution-based estimate or method-specific literature value) and apply it during the m/z-matching step. Retain-time-based clustering in the subsequent step refines these candidates within co-eluting windows, so an initially permissive m/z tolerance can be compensated by tight retention-time constraints. Validate the selected tolerance by examining the proportion of retained candidates that survive RT-based refinement and checking for known feature duplicates or expected metabolite signatures in the output matched feature correspondence table. Adjust tolerance upward if too many true matches are rejected, or downward if spurious matches persist after RT refinement.

## Related tools

- **Eclipse** (LCMS feature alignment module that applies m/z-based matching with tolerance threshold followed by retention-time clustering; tolerance tuning directly controls the candidate feature pair generation stage) — https://github.com/broadinstitute/bmxp/blob/main/bmxp/eclipse/readme.md
- **bmxp** (Parent Python/C package providing Eclipse as a standalone module within the BMXP metabolomics processing pipeline; tolerance tuning is part of Eclipse's documented workflow) — https://github.com/broadinstitute/bmxp

## Examples

```
from bmxp.eclipse import MSAligner; aligner = MSAligner(mz_tolerance_ppm=5); matched_pairs = aligner.align(feature_table_1, feature_table_2)
```

## Evaluation signals

- Candidate feature pairs generated by m/z matching should be substantially reduced by subsequent RT-based clustering; if >90% of candidates are retained after RT refinement, tolerance may be too permissive
- Known metabolite features present in all input datasets should appear in the final matched feature correspondence table with high alignment confidence scores
- m/z deviation distribution of matched pairs should cluster near zero and fall well within the tolerance window; mean absolute m/z error should be < 50% of the applied tolerance
- Cross-validation: re-run alignment with ±10–20% tolerance adjustment and verify that the core set of high-confidence matches remains stable while only edge-case pairs change
- Output matched correspondence table should contain consistent feature counts across datasets for true alignment successes (e.g., if all three input datasets contain a feature, it should appear in all pairwise correspondences)

## Limitations

- Tolerance tuning is method-specific and instrument-specific; a threshold validated on one LCMS platform may not transfer directly to a different instrument or ionization mode
- Eclipse requires all input datasets to be from the same analytical method; tolerance tuning does not compensate for cross-method drift or systematic m/z offsets
- Very tight m/z tolerances may reject true matches if m/z calibration drifts between injection batches; pooled technical replicates or internal standards (handled by Blueshift) may be needed before alignment
- Retention-time-based refinement (the second matching step) can only recover false negatives if RT windows are wide enough; aggressive m/z tolerance reduction cannot be fully compensated by loose RT clustering without risking spurious matches

## Evidence

- [other] Apply m/z-based matching with tolerance threshold to identify candidate feature pairs across datasets: "Apply m/z-based matching with tolerance threshold to identify candidate feature pairs across datasets."
- [other] Retention-time clustering refines candidates within co-eluting windows: "Apply retention-time-based clustering to refine candidate matches within co-eluting windows."
- [other] Eclipse is a standalone module designed to align two or more same-method datasets: "Eclipse is a standalone module designed to align two or more same-method nontargeted LCMS datasets"
- [readme] Each tool is meant to be a standalone module that performs a step in the processing pipeline: "Each tool is meant to be a standalone module that performs a step in our processing pipeline."
- [other] Output matched feature correspondence table links features across datasets with alignment confidence scores: "Output matched feature correspondence table linking features across datasets with alignment confidence scores."