ion-mobility-saturation-detection-and-repair
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Detects and reconstructs saturated ion signals in IM-MS data using multidimensional smoothing across m/z, mobility, and retention time dimensions, then exports frame-level metadata (field strength, pressure, temperature, MS actuals) to enable validation and downstream analysis.
When to use
Apply this skill when preprocessing raw Agilent MassHunter (.d) or UIMF IM-MS data files that exhibit signal saturation—ion intensity clipping caused by detector or amplifier limits—which distorts peak shape and abundance estimates across the m/z and drift-time axes. The skill is essential before quantitative omics workflows (proteomics, metabolomics) where accurate intensity recovery is required.
When NOT to use
- Input is already a processed feature table or quantification matrix—saturation repair must occur on raw ion-level data before aggregation.
- Data origin is unclear or from instruments not supported by PNNL PreProcessor (e.g., Bruker, Waters native formats without conversion)—compatibility and vendor-specific file format parsing are prerequisites.
- Ions exhibit highly convoluted elution/mobility profiles due to severe interference; saturation repair may produce incorrect reconstructions in such cases.
Inputs
- Agilent MassHunter (.d) raw data file
- UIMF (Unified Ion Mobility Format) raw data file
- Ion mobility-mass spectrometry acquisition data from drift-tube (DT) or SLIM instruments
Outputs
- Saturation-corrected ion mobility frame data
- Ion mobility frame metadata export (field strength, pressure, temperature, MS actuals in text format)
- Preprocessing log with warnings about repair confidence and convoluted profiles
- Smoothed multidimensional signal reconstructed across m/z, mobility, and retention time
How to apply
Load a raw Agilent MassHunter (.d) or UIMF file into PNNL PreProcessor. Apply the built-in multidimensional smoothing algorithm, which simultaneously repairs saturated peaks across m/z, ion mobility, and retention time dimensions by reconstructing signal intensity from neighboring unsaturated frames and scans. After repair, export ion mobility frame metadata (field strength, pressure, temperature, and MS instrument actuals) to a text file for audit and QC. Verify repair success by examining output logs for warnings about convoluted elution/mobility profiles that may have resulted in incorrect repairs; flag ions with highly overlapped profiles for manual review. The algorithm enhances real signals while removing artifacts in jagged peaks common in low-abundance ions.
Related tools
- PNNL PreProcessor (Primary preprocessing engine; orchestrates saturation repair as part of multidimensional smoothing pipeline) — https://github.com/PNNL-Comp-Mass-Spec/PNNL-PreProcessor
- Agilent MassHunter (Source data acquisition and native file format (.d) container; PreProcessor reads proprietary formats via MassHunter Data Access Component Library) — https://www.agilent.com
- IM-MS Browser (Supports polygon extraction for batch processing; provides .m method files used by PreProcessor for standardized frame setup)
- IMFE (Ion Mobility Frame Extraction) (Callable from within PNNL PreProcessor; converts ion mobility data to DDA format for downstream fragmentation analysis)
Evaluation signals
- Output logs contain no ERRORS for saturation repair step; presence of INFO messages confirming repair application across all affected frames.
- Exported metadata file is valid text format with populated fields for field strength, pressure, temperature, and MS instrument parameters—schema check confirms required columns are present and numeric values are within physically plausible ranges.
- Comparison of pre- and post-repair intensity profiles for saturated ions shows smooth reconstruction (no cliff edges or discontinuities) and intensity increase in previously clipped regions; jagged low-abundance peaks are visibly smoothed.
- Log warnings explicitly flag any ions with convoluted elution/mobility profiles; these warnings enable targeted review and justify exclusion from downstream quantification if repair confidence is low.
- Repaired data passes downstream demultiplexing and peak deconvolution steps without anomalous failures; ion abundance estimates for validated standards/controls agree with expected stoichiometry and known purity.
Limitations
- Saturation repair software may produce incorrect results for ions with highly convoluted elution/mobility profiles caused by interferences; manual inspection of flagged ions is recommended.
- Repair accuracy depends on adjacent frame quality and uniformity; isolated saturated frames or severe saturation across most of the chromatogram may yield unreliable reconstructions.
- Metadata export does not include per-scan or per-frame saturation flags; practitioners must cross-reference repair logs to identify which specific frames underwent saturation correction.
- PNNL PreProcessor is closed-source and binary-only due to vendor restrictions on proprietary Agilent data format handling; algorithm implementation details and internal thresholds cannot be independently verified or modified.
Evidence
- [methods] Saturation repair as part of multidimensional smoothing and metadata export: "PNNL-PreProcessor implements saturation repair as part of multidimensional smoothing of data, and provides metadata export functionality as separate utilities within its preprocessing pipeline"
- [methods] Repair algorithm spans three dimensions: "Apply multidimensional smoothing and saturation repair algorithm to detect and reconstruct saturated peaks across the m/z, mobility, and retention time dimensions."
- [methods] Metadata export content specification: "Export ion mobility frame metadata (field strength, pressure, temperature, and MS actuals) to a text file."
- [methods] Limitation on convoluted profiles: "the saturation repair software may produce incorrect results for ions with highly convoluted elution/mobility profiles caused by interferences"
- [methods] Effect on low-abundance signals: "Smoothing removes artifacts in jagged peaks, which are common in low-abundance ions. Real signals are enhanced"
- [readme] Tool capabilities overview: "data compression and interpolation, ion mobility demultiplexing, multidimensional smoothing, noise filtering by low intensity threshold and spike removal, saturation repair and metadata export"
1---2name: ion-mobility-saturation-detection-and-repair-23description: Use when preprocessing raw Agilent MassHunter (.d) or UIMF IM-MS data files that exhibit signal saturation—ion intensity clipping caused by detector or amplifier limits—which distorts peak shape and abundance estimates across the m/z and drift-time axes.4license: CC-BY-4.05---67# ion-mobility-saturation-detection-and-repair89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Detects and reconstructs saturated ion signals in IM-MS data using multidimensional smoothing across m/z, mobility, and retention time dimensions, then exports frame-level metadata (field strength, pressure, temperature, MS actuals) to enable validation and downstream analysis.1314## When to use1516Apply this skill when preprocessing raw Agilent MassHunter (.d) or UIMF IM-MS data files that exhibit signal saturation—ion intensity clipping caused by detector or amplifier limits—which distorts peak shape and abundance estimates across the m/z and drift-time axes. The skill is essential before quantitative omics workflows (proteomics, metabolomics) where accurate intensity recovery is required.1718## When NOT to use1920- Input is already a processed feature table or quantification matrix—saturation repair must occur on raw ion-level data before aggregation.21- Data origin is unclear or from instruments not supported by PNNL PreProcessor (e.g., Bruker, Waters native formats without conversion)—compatibility and vendor-specific file format parsing are prerequisites.22- Ions exhibit highly convoluted elution/mobility profiles due to severe interference; saturation repair may produce incorrect reconstructions in such cases.2324## Inputs2526- Agilent MassHunter (.d) raw data file27- UIMF (Unified Ion Mobility Format) raw data file28- Ion mobility-mass spectrometry acquisition data from drift-tube (DT) or SLIM instruments2930## Outputs3132- Saturation-corrected ion mobility frame data33- Ion mobility frame metadata export (field strength, pressure, temperature, MS actuals in text format)34- Preprocessing log with warnings about repair confidence and convoluted profiles35- Smoothed multidimensional signal reconstructed across m/z, mobility, and retention time3637## How to apply3839Load a raw Agilent MassHunter (.d) or UIMF file into PNNL PreProcessor. Apply the built-in multidimensional smoothing algorithm, which simultaneously repairs saturated peaks across m/z, ion mobility, and retention time dimensions by reconstructing signal intensity from neighboring unsaturated frames and scans. After repair, export ion mobility frame metadata (field strength, pressure, temperature, and MS instrument actuals) to a text file for audit and QC. Verify repair success by examining output logs for warnings about convoluted elution/mobility profiles that may have resulted in incorrect repairs; flag ions with highly overlapped profiles for manual review. The algorithm enhances real signals while removing artifacts in jagged peaks common in low-abundance ions.4041## Related tools4243- **PNNL PreProcessor** (Primary preprocessing engine; orchestrates saturation repair as part of multidimensional smoothing pipeline) — https://github.com/PNNL-Comp-Mass-Spec/PNNL-PreProcessor44- **Agilent MassHunter** (Source data acquisition and native file format (.d) container; PreProcessor reads proprietary formats via MassHunter Data Access Component Library) — https://www.agilent.com45- **IM-MS Browser** (Supports polygon extraction for batch processing; provides .m method files used by PreProcessor for standardized frame setup)46- **IMFE (Ion Mobility Frame Extraction)** (Callable from within PNNL PreProcessor; converts ion mobility data to DDA format for downstream fragmentation analysis)4748## Evaluation signals4950- Output logs contain no ERRORS for saturation repair step; presence of INFO messages confirming repair application across all affected frames.51- Exported metadata file is valid text format with populated fields for field strength, pressure, temperature, and MS instrument parameters—schema check confirms required columns are present and numeric values are within physically plausible ranges.52- Comparison of pre- and post-repair intensity profiles for saturated ions shows smooth reconstruction (no cliff edges or discontinuities) and intensity increase in previously clipped regions; jagged low-abundance peaks are visibly smoothed.53- Log warnings explicitly flag any ions with convoluted elution/mobility profiles; these warnings enable targeted review and justify exclusion from downstream quantification if repair confidence is low.54- Repaired data passes downstream demultiplexing and peak deconvolution steps without anomalous failures; ion abundance estimates for validated standards/controls agree with expected stoichiometry and known purity.5556## Limitations5758- Saturation repair software may produce incorrect results for ions with highly convoluted elution/mobility profiles caused by interferences; manual inspection of flagged ions is recommended.59- Repair accuracy depends on adjacent frame quality and uniformity; isolated saturated frames or severe saturation across most of the chromatogram may yield unreliable reconstructions.60- Metadata export does not include per-scan or per-frame saturation flags; practitioners must cross-reference repair logs to identify which specific frames underwent saturation correction.61- PNNL PreProcessor is closed-source and binary-only due to vendor restrictions on proprietary Agilent data format handling; algorithm implementation details and internal thresholds cannot be independently verified or modified.6263## Evidence6465- [methods] Saturation repair as part of multidimensional smoothing and metadata export: "PNNL-PreProcessor implements saturation repair as part of multidimensional smoothing of data, and provides metadata export functionality as separate utilities within its preprocessing pipeline"66- [methods] Repair algorithm spans three dimensions: "Apply multidimensional smoothing and saturation repair algorithm to detect and reconstruct saturated peaks across the m/z, mobility, and retention time dimensions."67- [methods] Metadata export content specification: "Export ion mobility frame metadata (field strength, pressure, temperature, and MS actuals) to a text file."68- [methods] Limitation on convoluted profiles: "the saturation repair software may produce incorrect results for ions with highly convoluted elution/mobility profiles caused by interferences"69- [methods] Effect on low-abundance signals: "Smoothing removes artifacts in jagged peaks, which are common in low-abundance ions. Real signals are enhanced"70- [readme] Tool capabilities overview: "data compression and interpolation, ion mobility demultiplexing, multidimensional smoothing, noise filtering by low intensity threshold and spike removal, saturation repair and metadata export"
HolobiomicsLab 