# Quasi Molecular Adduct Filtering

> Use when after feature clustering has been applied to co-eluting LC-MS features and mass-to-charge ratio matching to KEGG has produced an annotated table with adduct assignments.

- Skill: `holobiomicslab/quasi-molecular-adduct-filtering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/quasi-molecular-adduct-filtering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/quasi-molecular-adduct-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/quasi-molecular-adduct-filtering

---


# quasi-molecular-adduct-filtering

## Summary

Filter LC-MS feature candidates to retain only quasi-molecular ion adducts (e.g., MH, MNa, MK) after feature clustering, removing in-source fragments and low-frequency adducts. This step reduces annotation candidate noise and improves specificity before diffusion-based prioritization.

## When to use

After feature clustering has been applied to co-eluting LC-MS features and mass-to-charge ratio matching to KEGG has produced an annotated table with adduct assignments. Use this skill when you need to focus on biologically plausible quasi-molecular ions and eliminate spurious in-source fragments or rare adducts that are unlikely to represent the true metabolite.

## When NOT to use

- Features have not yet been clustered — cluster-based filtering requires pcgroup assignments from featuresClustering.
- You need to retain all candidate adducts (including fragments) for separate analysis — this skill explicitly removes them.
- Input is already a final ranked annotation table — filtering should occur earlier in the pipeline, before diffusion prioritization.

## Inputs

- annotated feature table with KEGG candidates and adduct assignments (from matching stage)
- cluster group identifiers (pcgroup column, from featuresClustering output)
- quasi-molecular adduct list (optional; defaults to MH, MNa, MK if not supplied)
- observed adduct frequency threshold (default 0.1)

## Outputs

- filtered annotation table (MH.Tab) containing only quasi-molecular ion candidates
- cluster-validated feature annotations with spurious in-source fragments removed

## How to apply

Apply the mWISE clusterBased.filter function to the annotated feature table containing cluster group identifiers (pcgroup) and adduct assignments. Retain only candidates with quasi-molecular adducts (MH, MNa, MK, etc.); if no explicit quasi-molecular list is provided, the function defaults to these adducts plus any adducts with observed frequency > 0.1 (this threshold can be modified). The function processes each cluster independently, filtering out in-source fragments and low-frequency adducts (observed frequency ≤ 0.1) to produce a cleaned MH.Tab output table. This filtered table then serves as input to diffusion-based prioritization, ensuring that downstream scoring focuses on metabolically relevant ion species.

## Related tools

- **mWISE** (Provides clusterBased.filter function to filter candidates by quasi-molecular adducts and frequency thresholds; provides featuresClustering function that generates input pcgroup assignments) — https://dev.b2s.club/b2slab/mWISE
- **R** (Execution environment for mWISE functions)
- **CAMERA** (Source of default adduct and fragment information used to build adduct tables in mWISE)
- **cliqueMS** (Contributes to default adduct and fragment reference tables used for classification)

## Examples

```
MH.Tab <- clusterBased.filter(annotated_table, pcgroup_col="pcgroup", quasi_molecular_list=c("MH", "MNa", "MK"), freq_threshold=0.1)
```

## Evaluation signals

- Output table contains only candidates with quasi-molecular adduct labels (MH, MNa, MK, etc.) — no in-source fragments or other adduct types remain.
- Adduct frequency distribution in output shows all retained adducts have observed frequency > 0.1 (or user-specified threshold).
- Number of rows in filtered table is less than or equal to the input annotated table (filtering removes or consolidates candidates).
- Cluster group (pcgroup) assignments are preserved in output and align with input feature clusters.
- Downstream diffusion prioritization produces valid probability/network scores without missing-value errors, confirming input structure is correct.

## Limitations

- Default observed frequency threshold (0.1) may not be optimal for all ionization modes or instrument configurations; users should validate or adjust based on their experimental design.
- Filtering removes potentially informative fragment ions; if fragment-level analysis is needed, it must be performed on unfiltered data before this step.
- Assumes accurate prior clustering and mass-to-charge matching; errors in earlier stages (e.g., wrong pcgroup assignments, mismatched masses) propagate through filtering.
- Relies on accurate adduct annotation in the input table; if input adduct labels are misclassified, filtering will not recover them.

## Evidence

- [intro] The clusterBased.filter function then filters candidates by retaining only those with quasi-molecular adducts: "The clusterBased.filter function then filters candidates by retaining only those with quasi-molecular adducts"
- [intro] retaining only features assigned to quasi-molecular adducts (MH, MNa, MK, etc.) and filtering out in-source fragments and low-frequency adducts: "retaining only features assigned to quasi-molecular adducts (MH, MNa, MK, etc.) and filtering out in-source fragments and low-frequency adducts (observed frequency ≤ 0.1 threshold)"
- [intro] If not, the quasi-molecular adducts available in mWISE, together with the adducts with an observed frequency higher than 0.1 will be used for filtering: "If not, the quasi-molecular adducts available in mWISE, together with the adducts with an observed frequency higher than 0.1 will be used for filtering"
- [intro] Apply mWISE featuresClustering function to group co-eluting features based on intensity correlation and retention time proximity. Merge the resulting cluster group (pcgroup) identifiers into the annotated table: "Apply mWISE featuresClustering function to group co-eluting features based on intensity correlation and retention time proximity. Merge the resulting cluster group (pcgroup) identifiers into the"
- [intro] Output the filtered table containing only cluster-validated quasi-molecular ion candidates: "Output the filtered table containing only cluster-validated quasi-molecular ion candidates"