Metabolite Feature Flagging

metabolite-feature-flagging

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.

Summary

A quality-control filtering step that identifies and marks LC-MS metabolite features failing to meet minimum detection-rate thresholds across QC samples, preventing low-confidence features from downstream multivariate analysis. This skill operationalizes the flag_detection function in the notame workflow to enforce reproducibility criteria on feature abundance data.

When to use

After drift correction and before imputation, when you have a MetaboSet object with LC-MS peak abundances and need to remove features with insufficient detection consistency across QC samples. Apply this when QC sample labels are present in the fData metadata and you want to enforce a minimum reproducibility cutoff (e.g., 70% QC detection rate) to filter out noise-prone or poorly ionizing compounds before statistical analysis.

When NOT to use

• Input data lacks QC sample replicates or QC column in fData—flag_detection requires labeled QC samples to compute detection rates.
• Feature detection has already been filtered by upstream peak-picking software—applying redundant flagging may over-filter genuine low-abundance metabolites.
• Analysis goal requires retention of all detected features regardless of reproducibility (e.g., exploratory hypothesis generation from rare features)—flagging is irreversible without manual intervention.

Inputs

• MetaboSet object (Biobase ExpressionSet subclass) with exprs (feature × sample abundance matrix), pData (sample metadata including QC labels), and fData (feature metadata with QC column)

Outputs

• MetaboSet object with updated Flag column in fData marking features with detection rate < qc_limit threshold
• Filtered feature set (implicitly excluded from subsequent analyses when all_features=FALSE)

How to apply

Load the MetaboSet object containing feature abundances (exprs), sample metadata (pData), and feature metadata (fData) with a QC column marking quality-control samples. Call flag_detection with qc_limit=0.7 to identify features observed in fewer than 70% of QC samples; this function computes detection rates per feature and updates the Flag column in fData with non-NA values for features below threshold. The rationale is that features consistently detected across replicate QC injections are more likely to be true signals than sporadic detections. Verify that flagged features are excluded from downstream multivariate analyses by setting all_features=FALSE; the Flag column acts as a persistent mask for the workflow.

Related tools

• notame (Implements flag_detection function and coordinates QC-based feature flagging within the LC-MS preprocessing workflow) — https://github.com/hanhineva-lab/notame
• Biobase (Provides ExpressionSet class foundation for MetaboSet objects, enabling structured storage of feature flags in fData slots)
• R (Execution environment for flag_detection and MetaboSet manipulation)

Examples

mset_flagged <- flag_detection(mset, qc_limit = 0.7); mset_filtered <- filter_by_flag(mset_flagged, all_features = FALSE)

Evaluation signals

• Flag column in fData contains non-NA values (e.g., 'low_detection') for features with QC detection rate < qc_limit; unflagged features have NA.
• Number of flagged features matches manual count of features observed in < 70% of QC samples when qc_limit=0.7.
• Multivariate analysis outputs (PCA, OPLS-DA) exclude flagged features when all_features=FALSE, reducing dimensionality and noise compared to all_features=TRUE.
• Flagged features correspond to those with sporadic or absent peaks in QC abundance matrix (exprs) across QC sample columns.
• Reproducibility improves post-filtering: QC sample clustering tightness or inter-QC correlation increases after flagging applied.

Limitations

• qc_limit threshold (0.7) is arbitrary; no universal consensus exists for optimal detection-rate cutoff across metabolite classes—tissue types, ionization modes, or compound chemistry may require empirical tuning.
• Flags permanently mark features in fData but do not remove them; downstream functions must respect all_features parameter to enforce exclusion—silent retention is possible if parameter is misset.
• Requires sufficient QC replicates to estimate reliable detection rates; sparse QC sampling (n < 3–5) produces unstable thresholds.
• Does not account for biology-driven variability (e.g., metabolites genuinely absent in some QC pools); detection rate alone cannot distinguish instrumental noise from true metabolite absence.

Evidence

• [other] flag_detection is used to flag features based on detection: "flag_detection``` is used to flag features based on detection"
• [methods] Apply flag_detection with qc_limit parameter to identify features below acceptance threshold: "Apply flag_detection with qc_limit=0.7 to identify features not observed in at least 70% of QC samples"
• [methods] Flagging updates Flag column in feature metadata: "Update the Flag column in fData to record flagged features with non-NA values"
• [methods] Flagged features excluded from downstream analysis by default: "Verify that flagged features are excluded from subsequent multivariate analyses by default (all_features=FALSE)"
• [readme] MetaboSet is built on Biobase ExpressionSet: "MetaboSetis built upon theExpressionSet``` class from the Biobase package"
• [other] Next, flag all the features with extensive amounts of missing values: "Next, flag all the features with extensive amounts of missing values"