# Search Results Filtering And Parsing

> Use when you have loaded DIA mass spectrometry search results containing feature identification data with associated Q-value scores, and you need to restrict the analytes available in selection drop-downs to those meeting a quality cutoff (typically 1% FDR equivalent) before visualization or manual.

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

---


# search-results-filtering-and-parsing

## Summary

Load mass spectrometry search results (feature identification data with Q-value scores) and filter analytes by a stringent quality threshold to populate hierarchical drop-down selection interfaces in data exploration workflows. This skill ensures that only high-confidence identifications are exposed to downstream visualization and analysis.

## When to use

You have loaded DIA mass spectrometry search results containing feature identification data with associated Q-value scores, and you need to restrict the analytes available in selection drop-downs to those meeting a quality cutoff (typically 1% FDR equivalent) before visualization or manual inspection. Apply this skill when you want to present users with only confident identifications and avoid cluttering the interface with low-confidence features.

## When NOT to use

- Input is already a curated/pre-filtered feature table with no Q-value metadata available — skip to direct lookup indexing.
- Analysis goal requires inspection of low-confidence features (e.g., sensitivity study, decoy validation) — relax or disable the Q-value threshold.
- Downstream tool requires all results regardless of quality (e.g., benchmarking against external gold standard) — apply filtering after that step.

## Inputs

- Search results file containing feature identification data (format: upstream software output, e.g. OpenSwath, DIA-NN)
- Feature Q-value scores (per-feature FDR estimates)
- Analyte metadata: protein identifiers, peptide sequences, charge states

## Outputs

- Filtered analyte collection (passing Q-value ≤ 0.01)
- Hierarchical lookup structure indexed by protein → peptide → charge state
- Populated drop-down selection options for GUI (three-level)
- Retained feature identification records with metadata

## How to apply

First, load the search results file using a format-specific MassDash loader (e.g., ResultsLoader) that parses the upstream software output and retains feature Q-value metadata. Apply a Q-value filter with a threshold of 1% (≤0.01), removing all analytes with Q-value > 1%. For each passing feature, extract the analyte metadata (protein name, peptide sequence, charge state) and build hierarchical lookup structures indexed by protein → peptide → charge state. Return this filtered collection to the GUI layer for dynamic population of the three-level drop-down selection boxes. The rationale is that the 1% Q-value threshold provides a stringent quality gate, balancing sensitivity and specificity for confident analyte identification in interactive exploration.

## Related tools

- **MassDash** (Modular Python package and Streamlit GUI that loads search results, applies Q-value filtering, and exposes filtered analytes via hierarchical drop-down selection) — https://github.com/Roestlab/massdash
- **ResultsLoader** (MassDash format-specific loader that parses feature identification data and Q-value scores from upstream software output) — https://github.com/Roestlab/massdash
- **Streamlit** (Web-based GUI framework used by MassDash to render the three-level drop-down selection interface)

## Evaluation signals

- Verify that all returned analytes have Q-value ≤ 0.01 (no analyte with Q-value > 1% passes the filter).
- Confirm that the hierarchical lookup is non-null and contains at least one protein entry for each passing feature.
- Check that drop-down options are sorted or indexed consistently by protein, then peptide, then charge state (no duplicate entries).
- Validate that the count of filtered analytes is ≤ count of input analytes (monotonic decrease or equality).
- Spot-check a sample of filtered records to ensure metadata (protein name, peptide sequence, charge state) is complete and non-null.

## Limitations

- Q-value threshold (1%) is a fixed cutoff; may be overly stringent for low-abundance analytes or underly stringent for high-variance features. Users may need to adjust the threshold in the sidebar after inspection.
- Filtering depends on accurate Q-value computation from the upstream search engine; errors in Q-value calculation propagate directly.
- Hierarchical indexing assumes unique protein–peptide–charge-state combinations; redundancy or collision in this key space may silently drop or merge analytes.
- No support for post-search re-ranking or machine learning-based rescoring within this filter step; limited to the upstream Q-values.

## Evidence

- [other] the analytes populated in the drop down selection boxes are filtered based on the feature Q-value of 1%: "the analytes populated in the drop down selection boxes are filtered based on the feature Q-value of 1%"
- [other] Apply Q-value filter with threshold of 1% (≤0.01) to retain only high-confidence identifications: "Apply Q-value filter with threshold of 1% (≤0.01) to retain only high-confidence identifications, removing all analytes with Q-value > 1%"
- [other] Load search results file containing feature identification data and associated Q-value scores using massdash loaders: "Load search results file containing feature identification data and associated Q-value scores using massdash loaders (e.g., ResultsLoader or format-specific loader matching the upstream software)"
- [other] Extract analyte metadata (protein, peptide sequence, charge state) for each passing feature and build hierarchical lookup structures: "Extract analyte metadata (protein, peptide sequence, charge state) for each passing feature and build hierarchical lookup structures for the three-level drop-down selection interface"
- [other] MassDash is a modular and flexible python package that has a streamlit graphical user interface (GUI): "MassDash is a modular and flexible python package that has a streamlit graphical user interface (GUI)"