# Mass Defect Filtering

> Use when after MS-Dial peak picking and feature table construction, when you observe a high proportion of features with anomalous m/z decimal values that are inconsistent with known metabolite ionization patterns.

- Skill: `holobiomicslab/mass-defect-filtering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/mass-defect-filtering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/mass-defect-filtering/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/mass-defect-filtering

---


# mass-defect-filtering

## Summary

Remove spurious or artifact features from untargeted metabolomics data by filtering on the decimal portion of m/z values. This quality-control filter excludes features with m/z decimal values falling within specified ranges (commonly [4, 8]), retaining only features with biologically plausible mass-to-charge ratios for downstream metabolite identification.

## When to use

After MS-Dial peak picking and feature table construction, when you observe a high proportion of features with anomalous m/z decimal values that are inconsistent with known metabolite ionization patterns. Apply this filter early in the preprocessing pipeline, before statistical testing or metabolite annotation, to reduce the false-positive feature count and improve spectral library matching accuracy.

## When NOT to use

- Input is already a curated metabolite library or list of known standards; mass-defect filtering is a quality metric for discovery, not validation.
- Data were acquired using targeted or pseudo-targeted acquisition with pre-selected m/z ranges; filtering may exclude intentionally selected features.
- The m/z decimal distribution in your instrument or ionization protocol is known to differ from the [4, 8] anomalous range; re-validate or adjust the threshold before applying.

## Inputs

- Feature table with m/z values from MS-Dial output
- Feature abundance matrix (samples × features)
- m/z value vector (one per feature)

## Outputs

- Filtered feature table (retained features with appropriate m/z values)
- Removed feature table (excluded features with inappropriate m/z values)
- Filtering summary report (count of retained and excluded features)

## How to apply

Extract the decimal part of each feature's m/z value by computing m/z modulo 1 (i.e., m/z − floor(m/z)). Classify each feature as inappropriate if its decimal portion lies within the default interval [4, 8]; otherwise mark it as appropriate. Separate the feature table into two subsets: one containing features that pass the filter (appropriate m/z values) and one containing filtered-out features (inappropriate m/z values). Return both subsets along with a summary report documenting the count and proportion of retained vs. excluded features. The rationale is that authentic metabolites typically exhibit m/z decimal distributions outside this anomalous range, particularly in data-independent acquisition (DIA) and high-resolution MS/MS workflows where spectral accuracy is critical for downstream identification.

## Related tools

- **margheRita** (R package providing the m_z_filtering() function and integrated pre-processing workflow (quality control, filtering, normalization) for MS-Dial output analysis) — https://github.com/emosca-cnr/margheRita
- **MS-Dial** (Peak picking and feature table generation software producing the m/z values input to the mass-defect filter)
- **R** (Execution environment for modulo arithmetic on m/z vectors and feature classification)
- **notame** (Alternative R package for non-targeted LC-MS workflow that includes quality metrics and feature flagging; compatible via margheRita export functions) — https://github.com/hanhineva-lab/notame

## Evaluation signals

- Feature count conservation: sum of retained and excluded features equals the input feature count with no data loss.
- Decimal distribution check: plot the decimal portion of m/z values before and after filtering; verify that retained features show absence or near-absence of decimal values in the [4, 8] range.
- Consistency with spectral library matching: post-filtering metabolite annotation should show increased cosine similarity scores and reduced number of ambiguous or low-confidence matches (improvement in fragment matching accuracy).
- Sample-wise abundance stability: total feature abundance per sample should remain consistent across filtered features; large shifts may indicate loss of true biological signal.
- Reproducibility: filtering with identical m/z decimal interval [4, 8] applied to replicate MS runs should yield consistent proportions of retained features (e.g., ~90–92% retention in typical workflows).

## Limitations

- The [4, 8] m/z decimal threshold is empirically derived and may require adjustment for different instrument types, ionization methods, or chromatographic columns; no theoretical justification for the specific interval is provided.
- Mass-defect filtering does not distinguish between instrumental artifacts and genuine low-abundance or rare metabolites; features excluded may include valid compounds with atypical m/z decimals.
- The filter assumes that anomalous m/z decimals are uniformly distributed across features and samples; batch or polarity-specific artifacts may not be adequately corrected.
- Application to targeted or semi-targeted workflows where m/z selection is predetermined may inadvertently remove intentionally included features.

## Evidence

- [other] The m/z filtering function removes features whose m/z decimal values fall within the interval [4, 8] by default.: "The m/z filtering function removes features whose m/z decimal values fall within the interval [4, 8] by default. When applied to the dataset, this filter excluded 56 features with inappropriate m/z"
- [other] Extract the decimal part of each m/z value by computing m/z modulo 1; classify as inappropriate if within [4,8].: "Extract the decimal part of each m/z value by computing m/z modulo 1. 3. Classify features as inappropriate if the decimal part lies within [4,8]; otherwise mark as appropriate."
- [readme] Filtering by mass defects is a pre-processing method specifically recommended for metabolomic profiles.: "a series of pre-processing functions (quality control, filtering and normalization) with a particular focus on methods specifically recommended for metabolomic profiles, such as filtering by mass"
- [readme] This pipeline is especially advantageous in the case of data-independent acquisition (DIA), where all MS/MS spectra are acquired with high resolution.: "This pipeline is especially advantageous in the case of data-independent acquisition (DIA), where all MS/MS spectra are acquired with high resolution."
- [readme] margheRita enhances fragment matching accuracy by providing an original metabolite spectral library.: "margheRita enhances fragment matching accuracy by providing an original metabolite spectral library acquired in both polarities using different chromatographic columns."