frequency-threshold-adduct-selection
Summary
A filtering step that selects adducts and fragments for metabolite annotation based on observed frequency thresholds, optionally retaining quasi-molecular adducts with minimum occurrence frequency above a user-defined cutoff. This is applied during cluster-based candidate filtering to improve specificity by removing rare or low-confidence adduct assignments.
When to use
After feature clustering has grouped co-eluting features and assigned candidate KEGG metabolites with multiple potential adduct forms, use this skill when you need to reduce false positive annotations by filtering out low-frequency adducts. Particularly useful when the experimental setup or MS ionization conditions are not a priori constrained, or when you want to let the data empirically guide adduct selection by retaining only adducts observed with frequency > 0.1 (or user-specified threshold).
When NOT to use
- Input is already a pre-validated peak table with known adducts and ionization conditions — skip to diffusion prioritization.
- Your MS experiment used a restricted ionization protocol with predetermined adducts — provide an explicit quasi-molecular adduct list rather than relying on frequency thresholds.
- Dataset is very small (< 50 features) such that observed frequency statistics are unreliable — use domain expertise or external adduct databases instead.
Inputs
- Annotated feature table with KEGG candidate assignments and adduct annotations (from matching stage)
- Cluster group identifiers (pcgroup column) from feature clustering output
- Optional: user-defined quasi-molecular adduct list (e.g., MH, MNa, MK)
- Optional: minimum observed frequency threshold (default 0.1)
Outputs
- Filtered MH.Tab: feature table containing only features with quasi-molecular adducts meeting frequency threshold
- Adduct-filtered candidate annotations retaining only high-confidence molecular ion assignments
How to apply
Apply the mWISE clusterBased.filter function to the annotated feature table after featuresClustering has produced cluster group assignments (pcgroup). By default, the filter retains quasi-molecular adducts (MH, MNa, MK, etc.) together with any other adducts exhibiting observed frequency higher than 0.1 across the dataset, unless you explicitly provide a restricted quasi-molecular adduct list. The user can modify the minimum observed frequency threshold according to their ionization efficiency expectations and noise tolerance. Features assigned to in-source fragments or adducts below the frequency cutoff are discarded, producing a filtered MH.Tab output containing only cluster-validated quasi-molecular ion candidates.
Related tools
- mWISE (Provides clusterBased.filter function to apply frequency-based adduct filtering and quasi-molecular adduct retention logic) — https://dev.b2s.club/b2slab/mWISE
- CAMERA (Source of default adduct and fragment table used by mWISE, informing which ion forms are considered quasi-molecular vs. in-source)
- R (Execution environment for mWISE functions)
Examples
mWISE::clusterBased.filter(annotated.table, pcgroup='pcgroup', min.frequency=0.1, quasi.molecular=c('MH', 'MNa', 'MK'))
Evaluation signals
- Verify that output MH.Tab contains no features assigned to in-source fragments or rare adducts below the frequency threshold.
- Check that the number of candidate annotations per feature has been reduced compared to pre-filter input, indicating successful removal of low-confidence adduct assignments.
- Confirm that quasi-molecular adducts (MH, MNa, MK) are present in output even if their observed frequency equals or exceeds the threshold.
- Inspect cluster group (pcgroup) identifiers are preserved in output, confirming that filtering operated on clustered features rather than singleton features.
- Validate that adduct frequency statistics used for thresholding were computed consistently across all clusters in the dataset.
Limitations
- Frequency-based filtering assumes that high-frequency adducts are biologically or chemically meaningful, which may not hold for ionization artifacts or matrix effects.
- Default 0.1 threshold is empirically motivated but may be too stringent for small datasets or too permissive for noisy experiments; user must validate the choice against their MS acquisition and sample complexity.
- Does not account for adduct-specific ionization efficiencies or instrumental bias; adducts with genuinely lower ionization efficiency may be incorrectly filtered out.
- Filtering is irreversible within this step; features removed cannot be recovered unless the recoveringPeaks function is later applied to restore completely removed peaks.
Evidence
- [other] The clusterBased.filter function then filters candidates by retaining only those with quasi-molecular adducts, optionally using adducts with observed frequency higher than 0.1 if no specific quasi-molecular list is provided: "The clusterBased.filter function then filters candidates by retaining only those with quasi-molecular adducts, optionally using adducts with observed frequency higher than 0.1 if no specific"
- [other] Apply mWISE clusterBased.filter function to each cluster, 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): "Apply mWISE clusterBased.filter function to each cluster, retaining only features assigned to quasi-molecular adducts (MH, MNa, MK, etc.) and filtering out in-source fragments and low-frequency"
- [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. The user can modify the minimum observed: "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. The user can modify the minimum observed"
- [intro] The default table of adducts and fragments is built using information from CAMERA R package, H. Tong et al., and cliqueMS: "The default table of adducts and fragments is built using information from CAMERA R package, H. Tong et al., and cliqueMS"
1---2name: frequency-threshold-adduct-selection3description: Use when after feature clustering has grouped co-eluting features and assigned candidate KEGG metabolites with multiple potential adduct forms, use this skill when you need to reduce false positive annotations by filtering out low-frequency adducts.4license: CC-BY-4.05---67# frequency-threshold-adduct-selection89## Summary1011A filtering step that selects adducts and fragments for metabolite annotation based on observed frequency thresholds, optionally retaining quasi-molecular adducts with minimum occurrence frequency above a user-defined cutoff. This is applied during cluster-based candidate filtering to improve specificity by removing rare or low-confidence adduct assignments.1213## When to use1415After feature clustering has grouped co-eluting features and assigned candidate KEGG metabolites with multiple potential adduct forms, use this skill when you need to reduce false positive annotations by filtering out low-frequency adducts. Particularly useful when the experimental setup or MS ionization conditions are not a priori constrained, or when you want to let the data empirically guide adduct selection by retaining only adducts observed with frequency > 0.1 (or user-specified threshold).1617## When NOT to use1819- Input is already a pre-validated peak table with known adducts and ionization conditions — skip to diffusion prioritization.20- Your MS experiment used a restricted ionization protocol with predetermined adducts — provide an explicit quasi-molecular adduct list rather than relying on frequency thresholds.21- Dataset is very small (< 50 features) such that observed frequency statistics are unreliable — use domain expertise or external adduct databases instead.2223## Inputs2425- Annotated feature table with KEGG candidate assignments and adduct annotations (from matching stage)26- Cluster group identifiers (pcgroup column) from feature clustering output27- Optional: user-defined quasi-molecular adduct list (e.g., MH, MNa, MK)28- Optional: minimum observed frequency threshold (default 0.1)2930## Outputs3132- Filtered MH.Tab: feature table containing only features with quasi-molecular adducts meeting frequency threshold33- Adduct-filtered candidate annotations retaining only high-confidence molecular ion assignments3435## How to apply3637Apply the mWISE `clusterBased.filter` function to the annotated feature table after `featuresClustering` has produced cluster group assignments (pcgroup). By default, the filter retains quasi-molecular adducts (MH, MNa, MK, etc.) together with any other adducts exhibiting observed frequency higher than 0.1 across the dataset, unless you explicitly provide a restricted quasi-molecular adduct list. The user can modify the minimum observed frequency threshold according to their ionization efficiency expectations and noise tolerance. Features assigned to in-source fragments or adducts below the frequency cutoff are discarded, producing a filtered MH.Tab output containing only cluster-validated quasi-molecular ion candidates.3839## Related tools4041- **mWISE** (Provides clusterBased.filter function to apply frequency-based adduct filtering and quasi-molecular adduct retention logic) — https://dev.b2s.club/b2slab/mWISE42- **CAMERA** (Source of default adduct and fragment table used by mWISE, informing which ion forms are considered quasi-molecular vs. in-source)43- **R** (Execution environment for mWISE functions)4445## Examples4647```48mWISE::clusterBased.filter(annotated.table, pcgroup='pcgroup', min.frequency=0.1, quasi.molecular=c('MH', 'MNa', 'MK'))49```5051## Evaluation signals5253- Verify that output MH.Tab contains no features assigned to in-source fragments or rare adducts below the frequency threshold.54- Check that the number of candidate annotations per feature has been reduced compared to pre-filter input, indicating successful removal of low-confidence adduct assignments.55- Confirm that quasi-molecular adducts (MH, MNa, MK) are present in output even if their observed frequency equals or exceeds the threshold.56- Inspect cluster group (pcgroup) identifiers are preserved in output, confirming that filtering operated on clustered features rather than singleton features.57- Validate that adduct frequency statistics used for thresholding were computed consistently across all clusters in the dataset.5859## Limitations6061- Frequency-based filtering assumes that high-frequency adducts are biologically or chemically meaningful, which may not hold for ionization artifacts or matrix effects.62- Default 0.1 threshold is empirically motivated but may be too stringent for small datasets or too permissive for noisy experiments; user must validate the choice against their MS acquisition and sample complexity.63- Does not account for adduct-specific ionization efficiencies or instrumental bias; adducts with genuinely lower ionization efficiency may be incorrectly filtered out.64- Filtering is irreversible within this step; features removed cannot be recovered unless the recoveringPeaks function is later applied to restore completely removed peaks.6566## Evidence6768- [other] The clusterBased.filter function then filters candidates by retaining only those with quasi-molecular adducts, optionally using adducts with observed frequency higher than 0.1 if no specific quasi-molecular list is provided: "The clusterBased.filter function then filters candidates by retaining only those with quasi-molecular adducts, optionally using adducts with observed frequency higher than 0.1 if no specific"69- [other] Apply mWISE clusterBased.filter function to each cluster, 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): "Apply mWISE clusterBased.filter function to each cluster, retaining only features assigned to quasi-molecular adducts (MH, MNa, MK, etc.) and filtering out in-source fragments and low-frequency"70- [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. The user can modify the minimum observed: "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. The user can modify the minimum observed"71- [intro] The default table of adducts and fragments is built using information from CAMERA R package, H. Tong et al., and cliqueMS: "The default table of adducts and fragments is built using information from CAMERA R package, H. Tong et al., and cliqueMS"
HolobiomicsLab 