# Spectral Mz Window Filtering

> Use when when you have resolved mzML or mzXML spectrum files and need to isolate signals for a target m/z value (e.g., 870.954) across all retention times or a specific scan.

- Skill: `holobiomicslab/spectral-mz-window-filtering-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/spectral-mz-window-filtering-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/spectral-mz-window-filtering-2/raw
- Safety review: pending
- 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/spectral-mz-window-filtering-2

---


# spectral-mz-window-filtering

> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->
## Summary

Filter mass spectrometry scans to extract signals within a specified mass-to-charge (m/z) tolerance window, isolating ions of interest for downstream chromatographic or spectral analysis. This is a foundational step in extracted-ion chromatogram (XIC) computation and targeted metabolite detection.

## When to use

When you have resolved mzML or mzXML spectrum files and need to isolate signals for a target m/z value (e.g., 870.954) across all retention times or a specific scan. Use this skill when you want to compute XICs, perform targeted feature extraction, or visually inspect intensity profiles for a known compound mass with a defined tolerance (e.g., ±0.5 Th or in ppm).

## When NOT to use

- Input is already a feature table or pre-computed XIC matrix—filtering has already been applied.
- MS2/MS3 fragmentation scans are the primary target; this skill is designed for MS1-level isolation.
- Mass tolerance is not specified or cannot be justified by instrument specifications; filtering without a well-defined window risks loss of true signal or inclusion of noise.

## Inputs

- mzML or mzXML spectrum file (resolved, centroided or profile MS1 scans)
- target m/z value (numeric, e.g., 870.954)
- mass tolerance parameter (numeric, e.g., 0.5 Th or 5 ppm)

## Outputs

- Filtered m/z signals within the tolerance window for each scan
- Paired retention time and summed intensity values (two-column data format)
- Extracted-ion chromatogram (XIC) intensity-vs-retention-time profile

## How to apply

Load the mzML or mzXML file using a mass spectrometry data parser (e.g., pyteomics or mzmine). For each MS1 scan, filter all m/z signals to retain only those within the specified mass tolerance window—typically defined as xicmz ± tolerance in Daltons or parts-per-million. Record the retention time and summed intensity across the filtered m/z range for each scan. The filtering decision should account for the instrument's mass accuracy and the width of the isotopic envelope; common practice uses 0.5 Th tolerance for high-resolution instruments. Export or tabulate the filtered retention time and intensity as paired values.

## Related tools

- **GNPS LCMS Visualization Dashboard** (Web interface for accepting resolved mzML/mzXML files and parameters (xicmz, xic_tolerance, xic_norm) to compute and visualize filtered XICs interactively) — github.com/Wang-Bioinformatics-Lab/GNPS_LCMSDashboard
- **pyteomics** (Python library for parsing and reading MS data formats (mzML, mzXML) programmatically)
- **mzmine** (Desktop/batch tool for mass spectrometry data processing, including m/z window filtering and feature extraction)

## Examples

```
https://gnps-lcms.ucsd.edu/?usi=mzspec%3AMSV000084951%3AAH22&xicmz=870.9543493652343&xic_tolerance=0.5&xic_norm=False&show_ms2_markers=True
```

## Evaluation signals

- Verify that all retained m/z values fall within xicmz ± tolerance (e.g., 870.954 ± 0.5 Th ⟹ [870.454, 871.454]).
- Check that summed intensities are positive and non-zero for at least some scans; zero or NaN intensity across all scans indicates filtering removed all signal.
- Confirm output XIC profile shows a coherent retention-time peak (single or multi-modal distribution), not random or uniform intensity across time.
- Compare the m/z window filter output against the raw spectrum image preview to visually validate that the correct ion envelope was isolated.
- For multi-file comparisons, verify that the same m/z and tolerance parameters produce comparable XIC shapes across files (e.g., same peak location in retention time).

## Limitations

- Mass tolerance must be specified a priori; incorrect tolerance (too narrow or too wide) will either miss the target signal or include interfering ions.
- Profile-mode data may include baseline noise; summing raw intensities without peak-picking can inflate the extracted signal if not pre-filtered.
- High mass accuracy instruments (e.g., <5 ppm) may require narrower tolerance windows; low-resolution instruments (e.g., >100 ppm) may need broader windows, affecting selectivity.
- Overlapping isotopic envelopes or isobaric compounds within the tolerance window will be co-extracted and cannot be separated by this filtering step alone.

## Evidence

- [other] The dashboard accepts resolved mzML/mzXML spectrum files and parameters including xicmz (target m/z value, e.g. 870.954), xic_tolerance (mass tolerance window, e.g. 0.5): "The dashboard accepts resolved mzML/mzXML spectrum files and parameters including xicmz (target m/z value, e.g. 870.954), xic_tolerance (mass tolerance window, e.g. 0.5)"
- [other] Filter all MS1 scans to extract signals within the specified m/z tolerance window (e.g., xicmz ± tolerance in ppm or Th).: "Filter all MS1 scans to extract signals within the specified m/z tolerance window (e.g., xicmz ± tolerance in ppm or Th)"
- [other] Load the mzML or mzXML file using a mass spectrometry data parser (e.g., pyteomics or mzmine).: "Load the mzML or mzXML file using a mass spectrometry data parser (e.g., pyteomics or mzmine)"
- [other] For each scan, record the retention time and summed intensity across the filtered m/z range.: "For each scan, record the retention time and summed intensity across the filtered m/z range"
- [other] Tabulate retention time and intensity as paired values and export as a two-column data file (retention_time, intensity).: "Tabulate retention time and intensity as paired values and export as a two-column data file (retention_time, intensity)"