mpactr-filter-application
Summary
Apply independent, chainable mpactr filters to MS1 peak tables to remove mispicked ions, group-specific contamination, non-reproducible features, and in-source fragments. This skill corrects preprocessing errors in tandem mass spectrometry data by selectively removing low-quality features while preserving the original biological signal.
When to use
Use this skill when you have a preprocessed peak table from tandem MS/MS data (e.g., Progenesis CSV format) and need to remove systematic quality issues: isotopic patterns incorrectly split during peak picking, features present only in solvent/media blanks, features with coefficient of variation (CV) above a reproducibility threshold across technical replicates, or in-source fragment ions created during ionization. Apply filters in sequence based on which artifacts affect your dataset.
When NOT to use
- Input is already a validated, curated feature table from a published metabolomics study (filters are redundant).
- You have only a single replicate per sample group; filter_cv() requires technical replicates to estimate reproducibility.
- You lack metadata assigning samples to groups or blank categories; filter_group() and filter_cv() require this information.
Inputs
- peak_table (CSV format from Progenesis or MS-DIAL, with m/z, retention time, and abundance columns)
- metadata (CSV format with sample identifiers, group assignments, and technical replicate designations)
- filter parameters (merge_method, cv_threshold, group_to_remove, cluster_threshold)
Outputs
- filtered_peak_table (reduced feature set with mispicked ions, blanks, low-CV, and in-source fragments removed)
- row_count_comparison (before/after counts per filter step for validation)
How to apply
Load the peak table and metadata using import_data() with the appropriate format (e.g., format='Progenesis'). Apply filters independently and sequentially: filter_mispicked_ions() with merge_peaks=TRUE and merge_method='sum' to combine isotopic patterns; filter_group() to remove features overrepresented in blank/control samples (e.g., group_to_remove='Solvent_Blank'); filter_cv() with a CV threshold (e.g., cv_threshold=0.2) to remove features inconsistent across technical replicates; filter_insource_ions() with cluster_threshold (default 0.95) to remove fragment ions. Decide the copy_object parameter: set copy_object=TRUE to preserve the original data object in memory (deep copy), or copy_object=FALSE to update in-place and reduce memory usage when working with large datasets. Each filter returns a reduced feature table; record row counts before and after each step to track cumulative filtering effects.
Related tools
- mpactr (R package providing independent filter functions (filter_mispicked_ions, filter_group, filter_cv, filter_insource_ions) for correcting MS1 peak selection errors) — https://github.com/mums2/mpactr
- MPACT (GUI desktop application wrapping mpactr and related preprocessing, offering interactive peak table filtering and data visualization workflows) — https://github.com/BalunasLab/mpact
- data.table (R package used internally by mpactr for fast, memory-efficient tabular data manipulation during filtering operations)
- R (Runtime environment for executing mpactr filters and constructing custom filter chains)
Examples
library(mpactr); data <- import_data('cultures_peak_table.csv', format='Progenesis'); data_filtered <- data$filter_mispicked_ions(merge_peaks=TRUE, merge_method='sum', copy_object=TRUE)$filter_group(group_to_remove='Solvent_Blank')$filter_cv(cv_threshold=0.2)
Evaluation signals
- Row count decreases monotonically with each filter step; total reduction should match the sum of features removed by each filter (no double-counting).
- When copy_object=TRUE, the original data object row count remains unchanged after filtering; when copy_object=FALSE, the original is modified in-place, showing identical row counts to the assigned result.
- After filter_group(group_to_remove='Solvent_Blank'), the filtered table contains zero features unique to blank samples.
- After filter_cv(cv_threshold=0.2), all remaining features have CV ≤ 0.2 across technical replicates.
- After filter_mispicked_ions(merge_peaks=TRUE, merge_method='sum'), isotopic patterns that were previously split into separate rows are consolidated, reducing total feature count while preserving biological signal via summation.
Limitations
- Filters are independent; the order of application can affect results. No canonical ordering is prescribed; workflows must be project-specific.
- filter_cv() requires technical replicates to estimate reproducibility; if absent, this filter cannot be applied.
- filter_group() removes all features present in a designated group; if that group contains both true signal and contaminants, true biological features may be lost.
- No changelog is maintained in the repository, making it difficult to track breaking changes between versions.
- The copy_object parameter affects both memory usage and code clarity; in-place modification (copy_object=FALSE) can lead to unintended side effects if the original object reference is needed downstream.
Evidence
- [abstract] Reference semantics in R6 classes: "operates on reference semantics in which data is updated in-place. Compared to a shallow copy, where only data pointers are copied, or a deep copy, where the entire data object is copied in memory,"
- [readme] Filter independence and composability: "All filters are independent, meaning they can be used to create a project-specific workflow"
- [methods] filter_mispicked_ions() behavior and parameters: "filter_mispicked_ions(merge_peaks = TRUE, merge_method = "sum")"
- [other] In-place modification with copy_object=FALSE: "When filter_mispicked_ions() is called with copy_object=FALSE, the original data object is updated in-place; the raw data object with 7269 ions was reduced to 6625 ions"
- [readme] filter_group() target and use case: "filter_group(): removal of features overrepresented in a specific group of samples; for example removal of features present in solvent blanks due to carryover between samples"
- [readme] filter_cv() purpose and parameter: "filter_cv(): removal of non-reproducible features, or those that are inconsistent between technical replicates"
- [readme] filter_insource_ions() purpose and clustering parameter: "filter_insource_ions(): removal of fragment ions created during the first ionization in the tandem MS/MS workflow"
1---2name: mpactr-filter-application-33description: Use when you have a preprocessed peak table from tandem MS/MS data (e.4license: CC-BY-4.05metadata:6 source: https://skillmd.com/skills/holobiomicslab/mpactr-filter-application-37 edam_operation: http://edamontology.org/operation_36958 edam_topics:9 - http://edamontology.org/topic_012110 - http://edamontology.org/topic_352011 tools:12 - R13 - mpactr14 - MPACT15 - data.table16 techniques:17 - LC-MS18 license_tier: open19 provenance_tier: literature20derived_from:21- doi: 10.1128/mra.00997-2422 title: mpactr23- doi: 10.1021/acs.analchem.2c0463224 title: ''25evidence_spans:26- This table can be used for a variety of analyses that can be conducted in R27- library(mpactr)28claims: []29provenance:30 collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v231 assembled_by: scripts/collect_metabolomics_collection.py32 sources:33 - build: coll_mpactr34 doi: 10.1128/mra.00997-2435 title: mpactr36 dedup_kept_from: coll_mpactr37schema_version: 0.2.038attribution:39 generator: AgenticScienceBuilder40 original_doi: 10.1128/mra.00997-2441 all_source_dois:42 - 10.1128/mra.00997-2443 - 10.1021/acs.analchem.2c0463244 zenodo_doi: 10.5281/zenodo.2079402745 curators: []46 promoter: Louis-Félix Nothias47 sponsor: CNRS & Université Côte d'Azur48---4950# mpactr-filter-application5152## Summary5354Apply independent, chainable mpactr filters to MS1 peak tables to remove mispicked ions, group-specific contamination, non-reproducible features, and in-source fragments. This skill corrects preprocessing errors in tandem mass spectrometry data by selectively removing low-quality features while preserving the original biological signal.5556## When to use5758Use this skill when you have a preprocessed peak table from tandem MS/MS data (e.g., Progenesis CSV format) and need to remove systematic quality issues: isotopic patterns incorrectly split during peak picking, features present only in solvent/media blanks, features with coefficient of variation (CV) above a reproducibility threshold across technical replicates, or in-source fragment ions created during ionization. Apply filters in sequence based on which artifacts affect your dataset.5960## When NOT to use6162- Input is already a validated, curated feature table from a published metabolomics study (filters are redundant).63- You have only a single replicate per sample group; filter_cv() requires technical replicates to estimate reproducibility.64- You lack metadata assigning samples to groups or blank categories; filter_group() and filter_cv() require this information.6566## Inputs6768- peak_table (CSV format from Progenesis or MS-DIAL, with m/z, retention time, and abundance columns)69- metadata (CSV format with sample identifiers, group assignments, and technical replicate designations)70- filter parameters (merge_method, cv_threshold, group_to_remove, cluster_threshold)7172## Outputs7374- filtered_peak_table (reduced feature set with mispicked ions, blanks, low-CV, and in-source fragments removed)75- row_count_comparison (before/after counts per filter step for validation)7677## How to apply7879Load the peak table and metadata using import_data() with the appropriate format (e.g., format='Progenesis'). Apply filters independently and sequentially: filter_mispicked_ions() with merge_peaks=TRUE and merge_method='sum' to combine isotopic patterns; filter_group() to remove features overrepresented in blank/control samples (e.g., group_to_remove='Solvent_Blank'); filter_cv() with a CV threshold (e.g., cv_threshold=0.2) to remove features inconsistent across technical replicates; filter_insource_ions() with cluster_threshold (default 0.95) to remove fragment ions. Decide the copy_object parameter: set copy_object=TRUE to preserve the original data object in memory (deep copy), or copy_object=FALSE to update in-place and reduce memory usage when working with large datasets. Each filter returns a reduced feature table; record row counts before and after each step to track cumulative filtering effects.8081## Related tools8283- **mpactr** (R package providing independent filter functions (filter_mispicked_ions, filter_group, filter_cv, filter_insource_ions) for correcting MS1 peak selection errors) — https://github.com/mums2/mpactr84- **MPACT** (GUI desktop application wrapping mpactr and related preprocessing, offering interactive peak table filtering and data visualization workflows) — https://github.com/BalunasLab/mpact85- **data.table** (R package used internally by mpactr for fast, memory-efficient tabular data manipulation during filtering operations)86- **R** (Runtime environment for executing mpactr filters and constructing custom filter chains)8788## Examples8990```91library(mpactr); data <- import_data('cultures_peak_table.csv', format='Progenesis'); data_filtered <- data$filter_mispicked_ions(merge_peaks=TRUE, merge_method='sum', copy_object=TRUE)$filter_group(group_to_remove='Solvent_Blank')$filter_cv(cv_threshold=0.2)92```9394## Evaluation signals9596- Row count decreases monotonically with each filter step; total reduction should match the sum of features removed by each filter (no double-counting).97- When copy_object=TRUE, the original data object row count remains unchanged after filtering; when copy_object=FALSE, the original is modified in-place, showing identical row counts to the assigned result.98- After filter_group(group_to_remove='Solvent_Blank'), the filtered table contains zero features unique to blank samples.99- After filter_cv(cv_threshold=0.2), all remaining features have CV ≤ 0.2 across technical replicates.100- After filter_mispicked_ions(merge_peaks=TRUE, merge_method='sum'), isotopic patterns that were previously split into separate rows are consolidated, reducing total feature count while preserving biological signal via summation.101102## Limitations103104- Filters are independent; the order of application can affect results. No canonical ordering is prescribed; workflows must be project-specific.105- filter_cv() requires technical replicates to estimate reproducibility; if absent, this filter cannot be applied.106- filter_group() removes all features present in a designated group; if that group contains both true signal and contaminants, true biological features may be lost.107- No changelog is maintained in the repository, making it difficult to track breaking changes between versions.108- The copy_object parameter affects both memory usage and code clarity; in-place modification (copy_object=FALSE) can lead to unintended side effects if the original object reference is needed downstream.109110## Evidence111112- [abstract] Reference semantics in R6 classes: "operates on reference semantics in which data is updated *in-place*. Compared to a shallow copy, where only data pointers are copied, or a deep copy, where the entire data object is copied in memory,"113- [readme] Filter independence and composability: "All filters are independent, meaning they can be used to create a project-specific workflow"114- [methods] filter_mispicked_ions() behavior and parameters: "filter_mispicked_ions(merge_peaks = TRUE, merge_method = "sum")"115- [other] In-place modification with copy_object=FALSE: "When filter_mispicked_ions() is called with copy_object=FALSE, the original data object is updated in-place; the raw data object with 7269 ions was reduced to 6625 ions"116- [readme] filter_group() target and use case: "filter_group(): removal of features overrepresented in a specific group of samples; for example removal of features present in solvent blanks due to carryover between samples"117- [readme] filter_cv() purpose and parameter: "filter_cv(): removal of non-reproducible features, or those that are inconsistent between technical replicates"118- [readme] filter_insource_ions() purpose and clustering parameter: "filter_insource_ions(): removal of fragment ions created during the first ionization in the tandem MS/MS workflow"