ion-filter-status-categorization
Summary
Categorize ions by their pass/fail status across multiple quality-control filters (mispicked, group, replicability, insource) and aggregate counts and percentages per status category. This enables structured summarization of filtering outcomes prior to visualization or downstream statistical analysis.
When to use
After applying one or more mpactr filters (filter_mispicked_ions, filter_group, filter_cv, filter_insource_ions) to a peak table, when you need to quantify how many ions passed or failed each filter and summarize the overall filtering impact by status distribution. Use this skill when preparing data for treemap or tabular reporting of QC outcomes.
When NOT to use
- Input is raw, unfiltered peak table — apply filters first before categorizing status.
- Goal is to identify individual ions that failed a specific filter — use per-ion qc_summary output directly instead of aggregating.
- Peak table has not been imported into mpactr format — use import_data() first.
Inputs
- mpactr object (post-filtering)
- qc_summary() output (data frame with per-ion filter status columns)
Outputs
- data frame with columns: status, count, percentage
- ion count and percentage distribution by filter status
How to apply
Call qc_summary() on the filtered mpactr object to extract per-ion filter status (passed/failed for mispicked, group, replicability, and insource filters). Pivot or group the qc_summary output using data.table grouping operations to count the number of ions in each status category (e.g., 'passed_all', 'failed_mispicked', 'failed_group'). Calculate the percentage of total ions for each status by dividing category count by total ion count. Store results in a data frame with columns for status label, ion count, and percentage. The rationale is that aggregating pass/fail outcomes by filter type provides a quantitative summary of data quality and the selective impact of each filter stage, enabling both numerical reporting and area-proportional visualization.
Related tools
- mpactr (Provides qc_summary() function to extract per-ion filter status and enables chaining of multiple filters whose outcomes are then categorized) — https://github.com/mums2/mpactr
- data.table (Used to group qc_summary output by status and compute aggregated counts and percentages)
- ggplot2 (Renders treemap or other visualizations of the status-aggregated counts (optional downstream use))
Examples
qc_summary_output <- qc_summary(filtered_mpactr_obj); status_counts <- qc_summary_output[, .(count = .N, percentage = 100 * .N / nrow(qc_summary_output)), by = status]
Evaluation signals
- Sum of all category counts equals total number of ions in the input peak table.
- Sum of all category percentages equals 100% (within rounding error).
- Each status category label is present in exactly one row of the output data frame (no duplicates).
- Counts are non-negative integers; percentages are in range [0, 100].
- Status labels match the filter types available in qc_summary (mispicked, group, replicability, insource) or compound combinations thereof.
Limitations
- qc_summary() output depends on which filters were applied to the mpactr object; if no filters are run, all ions will show 'passed' status, which may not reflect actual data quality.
- Categorization relies on correct interpretation of the qc_summary output structure; incorrect pivoting or grouping can produce misleading aggregates.
- Status categories may overlap or be hierarchical (e.g., an ion can fail multiple filters simultaneously); the aggregation strategy (e.g., counting as 'failed_any', 'failed_all', or per-filter) must be chosen before grouping.
Evidence
- [methods] ion-status-extraction: "call qc_summary() to extract per-ion filter status (passed/failed for mispicked, group, replicability, insource filters)"
- [methods] data-aggregation: "Ion counts and percentages by status can be computed from qc_summary() output using data.table grouping"
- [abstract] filter-types: "filter = "mispicked", "group", "replicability", "insource""
- [methods] mpactr-capability: "The goal of mpactr is to correct for errors that occur during the pre-processing of raw tandem MS/MS data."
1---2name: ion-filter-status-categorization3description: Use when after applying one or more mpactr filters (filter_mispicked_ions, filter_group, filter_cv, filter_insource_ions) to a peak table, when you need to quantify how many ions passed or failed each filter and summarize the overall filtering impact by status distribution.4license: CC-BY-4.05---67# ion-filter-status-categorization89## Summary1011Categorize ions by their pass/fail status across multiple quality-control filters (mispicked, group, replicability, insource) and aggregate counts and percentages per status category. This enables structured summarization of filtering outcomes prior to visualization or downstream statistical analysis.1213## When to use1415After applying one or more mpactr filters (filter_mispicked_ions, filter_group, filter_cv, filter_insource_ions) to a peak table, when you need to quantify how many ions passed or failed each filter and summarize the overall filtering impact by status distribution. Use this skill when preparing data for treemap or tabular reporting of QC outcomes.1617## When NOT to use1819- Input is raw, unfiltered peak table — apply filters first before categorizing status.20- Goal is to identify individual ions that failed a specific filter — use per-ion qc_summary output directly instead of aggregating.21- Peak table has not been imported into mpactr format — use import_data() first.2223## Inputs2425- mpactr object (post-filtering)26- qc_summary() output (data frame with per-ion filter status columns)2728## Outputs2930- data frame with columns: status, count, percentage31- ion count and percentage distribution by filter status3233## How to apply3435Call qc_summary() on the filtered mpactr object to extract per-ion filter status (passed/failed for mispicked, group, replicability, and insource filters). Pivot or group the qc_summary output using data.table grouping operations to count the number of ions in each status category (e.g., 'passed_all', 'failed_mispicked', 'failed_group'). Calculate the percentage of total ions for each status by dividing category count by total ion count. Store results in a data frame with columns for status label, ion count, and percentage. The rationale is that aggregating pass/fail outcomes by filter type provides a quantitative summary of data quality and the selective impact of each filter stage, enabling both numerical reporting and area-proportional visualization.3637## Related tools3839- **mpactr** (Provides qc_summary() function to extract per-ion filter status and enables chaining of multiple filters whose outcomes are then categorized) — https://github.com/mums2/mpactr40- **data.table** (Used to group qc_summary output by status and compute aggregated counts and percentages)41- **ggplot2** (Renders treemap or other visualizations of the status-aggregated counts (optional downstream use))4243## Examples4445```46qc_summary_output <- qc_summary(filtered_mpactr_obj); status_counts <- qc_summary_output[, .(count = .N, percentage = 100 * .N / nrow(qc_summary_output)), by = status]47```4849## Evaluation signals5051- Sum of all category counts equals total number of ions in the input peak table.52- Sum of all category percentages equals 100% (within rounding error).53- Each status category label is present in exactly one row of the output data frame (no duplicates).54- Counts are non-negative integers; percentages are in range [0, 100].55- Status labels match the filter types available in qc_summary (mispicked, group, replicability, insource) or compound combinations thereof.5657## Limitations5859- qc_summary() output depends on which filters were applied to the mpactr object; if no filters are run, all ions will show 'passed' status, which may not reflect actual data quality.60- Categorization relies on correct interpretation of the qc_summary output structure; incorrect pivoting or grouping can produce misleading aggregates.61- Status categories may overlap or be hierarchical (e.g., an ion can fail multiple filters simultaneously); the aggregation strategy (e.g., counting as 'failed_any', 'failed_all', or per-filter) must be chosen before grouping.6263## Evidence6465- [methods] ion-status-extraction: "call qc_summary() to extract per-ion filter status (passed/failed for mispicked, group, replicability, insource filters)"66- [methods] data-aggregation: "Ion counts and percentages by status can be computed from qc_summary() output using data.table grouping"67- [abstract] filter-types: "filter = "mispicked", "group", "replicability", "insource""68- [methods] mpactr-capability: "The goal of mpactr is to correct for errors that occur during the pre-processing of raw tandem MS/MS data."
HolobiomicsLab 