feature-table-subsetting
Summary
Partition a feature table into two complementary subsets based on a filtering criterion (e.g., m/z decimal values, mass defects, or coefficient of variation), retaining both the filtered-out and retained features for separate downstream analysis. This skill is essential in untargeted metabolomics to isolate features meeting quality or chemical criteria while preserving rejected features for audit trails and alternative interpretations.
When to use
Apply this skill after loading an MS-DIAL feature table when you need to separate features into two disjoint groups: one meeting a quantitative threshold (e.g., m/z decimal values outside [4, 8], coefficient of variation below a cutoff, or mass defects within acceptable bounds) and one not meeting it. Use it when your downstream analysis depends on feature quality flags and you want to preserve both subsets for reporting, validation, or downstream decision-making.
When NOT to use
- Input is already a pre-filtered feature table with no rejected features retained.
- You require features to be ranked or continuously scored rather than partitioned into discrete groups.
- The filtering criterion is unstable or depends on iterative re-estimation (e.g., adaptive thresholding); use model-based selection instead.
Inputs
- Feature table from MS-DIAL (with m/z values, retention times, and intensities)
- Feature metadata (e.g., mass-to-charge ratios, decimal parts, or quality metrics)
- Filtering criterion (logical threshold or range definition)
Outputs
- Subset of features meeting the filter criterion (e.g., 548 appropriate features)
- Subset of features failing the filter criterion (e.g., 56 inappropriate features)
- Summary report (count, percentage, feature identifiers for each subset)
How to apply
Load the feature table (including m/z values, intensities, or metadata) from MS-DIAL output into R. Extract or compute the filtering attribute for each feature (e.g., m/z decimal part via modulo operation, CV from QC replicates, or mass defect). Define the classification criterion as a logical condition (e.g., decimal m/z in [4, 8] = inappropriate). Partition the feature table into two subsets: one where the condition is TRUE (inappropriate/rejected features) and one where it is FALSE (appropriate/retained features). Return both subsets as separate data structures and a summary report (counts, percentages, feature lists) documenting the split. The rationale is to enable traceability and allow users to review rejected features without data loss.
Related tools
Examples
# In R using margheRita: result <- m_z_filtering(feature_table, decimal_range = c(4, 8)); appropriate_features <- result$retained; inappropriate_features <- result$excluded; summary(result)
Evaluation signals
- Sum of feature counts in both subsets equals the total input feature count (no features lost or duplicated).
- Each feature appears in exactly one subset (subsets are disjoint and exhaustive).
- Features in the 'inappropriate' subset all satisfy the filter criterion (e.g., m/z decimal in [4, 8]); features in the 'appropriate' subset do not.
- Summary report counts and percentages are internally consistent (e.g., 56 + 548 = 604 total; 56/604 ≈ 9.3%).
- No features are missing from the output (feature identifiers in both subsets account for all input feature IDs).
Limitations
- Subsetting is deterministic and threshold-based; if the threshold is misspecified or dataset-dependent, the split may be inappropriate for downstream analysis.
- The skill does not validate whether the filtering criterion is biologically meaningful or statistically justified—it only mechanically partitions based on the given rule.
- If features have missing or malformed metadata (e.g., null m/z values), the classification may fail or require imputation; the article does not specify how to handle missing data in subsetting.
Evidence
- [other] Step 4 of workflow: 'Separate the feature set into two subsets: 548 features with appropriate m/z values and 56 features with inappropriate m/z values.': "Separate the feature set into two subsets: 548 features with appropriate m/z values and 56 features with inappropriate m/z values."
- [other] Filter description: 'The m/z filtering function removes features whose m/z decimal values fall within the interval [4, 8] by default. When applied to the dataset, this filter excluded 56 features with inappropriate m/z values while retaining 548 features with appropriate m/z values.': "The m/z filtering function removes features whose m/z decimal values fall within the interval [4, 8] by default. When applied to the dataset, this filter excluded 56 features with inappropriate m/z"
- [other] Workflow step 3: 'Classify features as inappropriate if the decimal part lies within [4,8]; otherwise mark as appropriate.': "Classify features as inappropriate if the decimal part lies within [4,8]; otherwise mark as appropriate."
- [readme] README introduction: 'runs filters to exclude features/sample with many missing values, features with wrong m/z values': "runs filters to exclude features/sample with many missing values, features with wrong m/z values"
- [readme] README feature list: 'filtering by mass defects, filtering by coefficient of variation (samples vs QCs)': "filtering by mass defects, filtering by coefficient of variation (samples vs QCs)"
1---2name: feature-table-subsetting3description: Use when after loading an MS-DIAL feature table when you need to separate features into two disjoint groups: one meeting a quantitative threshold (e.g., m/z decimal values outside [4, 8], coefficient of variation below a cutoff, or mass defects within acceptable bounds) and one not meeting it.4license: CC-BY-4.05---67# feature-table-subsetting89## Summary1011Partition a feature table into two complementary subsets based on a filtering criterion (e.g., m/z decimal values, mass defects, or coefficient of variation), retaining both the filtered-out and retained features for separate downstream analysis. This skill is essential in untargeted metabolomics to isolate features meeting quality or chemical criteria while preserving rejected features for audit trails and alternative interpretations.1213## When to use1415Apply this skill after loading an MS-DIAL feature table when you need to separate features into two disjoint groups: one meeting a quantitative threshold (e.g., m/z decimal values outside [4, 8], coefficient of variation below a cutoff, or mass defects within acceptable bounds) and one not meeting it. Use it when your downstream analysis depends on feature quality flags and you want to preserve both subsets for reporting, validation, or downstream decision-making.1617## When NOT to use1819- Input is already a pre-filtered feature table with no rejected features retained.20- You require features to be ranked or continuously scored rather than partitioned into discrete groups.21- The filtering criterion is unstable or depends on iterative re-estimation (e.g., adaptive thresholding); use model-based selection instead.2223## Inputs2425- Feature table from MS-DIAL (with m/z values, retention times, and intensities)26- Feature metadata (e.g., mass-to-charge ratios, decimal parts, or quality metrics)27- Filtering criterion (logical threshold or range definition)2829## Outputs3031- Subset of features meeting the filter criterion (e.g., 548 appropriate features)32- Subset of features failing the filter criterion (e.g., 56 inappropriate features)33- Summary report (count, percentage, feature identifiers for each subset)3435## How to apply3637Load the feature table (including m/z values, intensities, or metadata) from MS-DIAL output into R. Extract or compute the filtering attribute for each feature (e.g., m/z decimal part via modulo operation, CV from QC replicates, or mass defect). Define the classification criterion as a logical condition (e.g., decimal m/z in [4, 8] = inappropriate). Partition the feature table into two subsets: one where the condition is TRUE (inappropriate/rejected features) and one where it is FALSE (appropriate/retained features). Return both subsets as separate data structures and a summary report (counts, percentages, feature lists) documenting the split. The rationale is to enable traceability and allow users to review rejected features without data loss.3839## Related tools4041- **margheRita** (R package providing m_z_filtering() and related subset/partition functions for MS-DIAL feature tables) — https://github.com/emosca-cnr/margheRita42- **R** (Scripting language for implementing feature table subsetting logic and modulo operations)43- **MS-Dial** (Source instrument-agnostic peak-picking and feature detection software; outputs the feature table to be subsetted) — http://prime.psc.riken.jp/Metabolomics_Software/MS-DIAL/4445## Examples4647```48# In R using margheRita: result <- m_z_filtering(feature_table, decimal_range = c(4, 8)); appropriate_features <- result$retained; inappropriate_features <- result$excluded; summary(result)49```5051## Evaluation signals5253- Sum of feature counts in both subsets equals the total input feature count (no features lost or duplicated).54- Each feature appears in exactly one subset (subsets are disjoint and exhaustive).55- Features in the 'inappropriate' subset all satisfy the filter criterion (e.g., m/z decimal in [4, 8]); features in the 'appropriate' subset do not.56- Summary report counts and percentages are internally consistent (e.g., 56 + 548 = 604 total; 56/604 ≈ 9.3%).57- No features are missing from the output (feature identifiers in both subsets account for all input feature IDs).5859## Limitations6061- Subsetting is deterministic and threshold-based; if the threshold is misspecified or dataset-dependent, the split may be inappropriate for downstream analysis.62- The skill does not validate whether the filtering criterion is biologically meaningful or statistically justified—it only mechanically partitions based on the given rule.63- If features have missing or malformed metadata (e.g., null m/z values), the classification may fail or require imputation; the article does not specify how to handle missing data in subsetting.6465## Evidence6667- [other] Step 4 of workflow: 'Separate the feature set into two subsets: 548 features with appropriate m/z values and 56 features with inappropriate m/z values.': "Separate the feature set into two subsets: 548 features with appropriate m/z values and 56 features with inappropriate m/z values."68- [other] Filter description: 'The m/z filtering function removes features whose m/z decimal values fall within the interval [4, 8] by default. When applied to the dataset, this filter excluded 56 features with inappropriate m/z values while retaining 548 features with appropriate m/z values.': "The m/z filtering function removes features whose m/z decimal values fall within the interval [4, 8] by default. When applied to the dataset, this filter excluded 56 features with inappropriate m/z"69- [other] Workflow step 3: 'Classify features as inappropriate if the decimal part lies within [4,8]; otherwise mark as appropriate.': "Classify features as inappropriate if the decimal part lies within [4,8]; otherwise mark as appropriate."70- [readme] README introduction: 'runs filters to exclude features/sample with many missing values, features with wrong m/z values': "runs filters to exclude features/sample with many missing values, features with wrong m/z values"71- [readme] README feature list: 'filtering by mass defects, filtering by coefficient of variation (samples vs QCs)': "filtering by mass defects, filtering by coefficient of variation (samples vs QCs)"
HolobiomicsLab