ion-image-augmentation-design
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Design and apply mode-specific data augmentation pipelines (COL and ISO) to ion images for mass spectrometry imaging to generate contrastive pairs while preserving domain-relevant physical properties. The choice of augmentation mode and composition depends on the ion relationship type (co-localized vs. isotopic) and is critical for learning meaningful low-dimensional representations.
When to use
When preparing ion image data from mass spectrometry imaging for contrastive self-supervised representation learning, and you need to generate augmented image pairs that reflect either co-localization relationships between different molecular ions (COL mode) or isotopic relationships within the same molecule (ISO mode). Use this skill when your input is raw or preprocessed MSI matrix data with known pixel dimensions and you require augmented images that preserve physical augmentation realism (e.g., photon counting artifacts, intensity-dependent pixel dropout).
When NOT to use
- Ion images where spatial structure is unknown or pixel coordinates cannot be reliably mapped (augmentation may corrupt meaningful localization patterns).
- When isotope identification or co-localization discovery is not a downstream goal; use only if contrastive learning on ion relationships is required.
- Pre-augmented or already heavily corrupted ion images; augmentation assumes access to relatively clean original data to avoid compounding artifacts.
Inputs
- Preprocessed MSI matrix data [X*Y, P] where X, Y are pixel coordinates and P is the number of ions
- Original ion image (2D spatial array of ion intensities)
- MSI data shape parameters (horizontal and vertical pixel counts)
- Ion mode designation ('positive' or 'negative')
- Mode selection ('COL' or 'ISO')
Outputs
- Two augmented ion images from COL mode pipeline (color jitter → filtering → Poisson noise → random missing values)
- Two augmented ion images from ISO mode pipeline (COL operations + intensity-dependent missing values)
- 512-dimensional representation vectors (one per augmented image, generated by downstream ResNet18 encoders)
How to apply
First, determine which augmentation mode matches your analysis goal: COL mode for co-localized ion discovery, ISO mode for isotope identification. Load the original ion image and apply the COL mode pipeline sequentially: color jitter to adjust pixel intensities, filtering to smooth or enhance spatial features, Poisson noise to simulate photon-counting artifacts inherent in mass spectrometry, and random missing values at arbitrary locations to model detector inefficiencies. For ISO mode, execute all COL operations, then apply an additional intensity-dependent missing value process that selectively removes pixels based on their intensity levels, modeling how low-intensity (likely isotopic) pixels are more prone to signal loss. Generate two augmented images per pipeline (four total: two from COL, two from ISO if running both modes). The augmented images are then fed to shared-parameter ResNet18 encoders to produce 512-dimensional representation vectors. Validate that augmentation preserves the spatial structure of ion localization patterns while introducing realistic noise and missing data consistent with MSI acquisition physics.
Related tools
- ResNet18 (Encoder backbone that processes augmented ion images to produce 512-dimensional representation vectors) — https://github.com/gankLei-X/DeepION
- Color jitter augmentation (First operation in COL mode pipeline; adjusts pixel intensities to simulate measurement variability) — https://github.com/gankLei-X/DeepION
- Filtering augmentation (Second operation in COL mode pipeline; smooths or enhances spatial features in ion images) — https://github.com/gankLei-X/DeepION
- Poisson noise augmentation (Third operation in COL mode pipeline; simulates photon-counting artifacts from mass spectrometry detection) — https://github.com/gankLei-X/DeepION
- Random missing value augmentation (Fourth operation in COL mode pipeline; introduces arbitrary pixel dropout to model detector inefficiencies) — https://github.com/gankLei-X/DeepION
- Intensity-dependent missing value augmentation (Additional operation unique to ISO mode; selectively removes pixels based on intensity levels for isotope-specific modeling) — https://github.com/gankLei-X/DeepION
- kornia (Supporting library for augmentation operations implementation)
- boly_pytorch (Supporting library for augmentation operations and contrastive learning implementation)
Examples
python run.py --input_Matrix Pos_brain_data_matrix.txt --input_PeakList Pos_brain_data_peak.csv --input_shape 198 422 --mode COL --ion_mode positive --num 5 --output_file Pos_COL_result
Evaluation signals
- Two augmented images are successfully generated per augmentation pipeline with no shape mismatch relative to the original ion image
- Augmented images retain spatial coherence: large-scale ion localization patterns are visually preserved despite noise and missing values
- Poisson noise magnitude is consistent with expected photon-counting statistics for mass spectrometry (variance ≈ intensity)
- Downstream ResNet18 encoders produce non-zero, non-NaN 512-dimensional vectors; contrastive loss converges during training, indicating meaningful augmentation diversity
- ISO mode augmented images exhibit selective intensity-dependent missing values (low-intensity pixels removed more frequently than high-intensity ones), validating isotope-specific augmentation behavior
Limitations
- Augmentation design assumes access to clean, preprocessed MSI data; severely degraded or already artifact-heavy raw ion images may produce compounded corruption rather than meaningful contrastive pairs.
- Mode selection (COL vs. ISO) must match the true ion relationship type; applying ISO augmentation to co-localized ions or vice versa may degrade representation learning quality.
- Fixed augmentation hyperparameters (color jitter strength, Poisson noise rate, missing value fraction) are not explicitly tuned per dataset; optimal augmentation intensity may vary with MSI instrument, ionization mode, or sample type.
- No explicit augmentation-invariance validation is provided in the article; the method assumes that physical augmentations (noise, missing values) preserve ion relationship semantics without empirical quantification.
- Augmentation module does not account for spatial correlation in missing values (e.g., clustered detector failures common in real MSI); random missing value placement may underestimate artifacts in high-resolution spatial regions.
Evidence
- [other] The COL mode augmentation applies four operations to ion images: color jitter, filtering, Poisson noise, and random missing value. The ISO mode includes all COL operations plus an additional intensity-dependent missing value process.: "The COL mode augmentation applies four operations to ion images: color jitter, filtering, Poisson noise, and random missing value. The ISO mode includes all COL operations plus an additional"
- [readme] T_COL including color jitter, filtering, Poisson noise, and random missing value is carried in COL mode, while T_ISO introduces an additional process of intensity-dependent missing value in ISO mode.: "T_COL including color jitter, filtering, Poisson noise, and random missing value is carried in COL mode, while T_ISO introduces an additional process of intensity-dependent missing value in ISO mode."
- [readme] The original ion image is first imported into the data augmentation module "T" to generate two augmented images: "The original ion image is first imported into the data augmentation module "T" to generate two augmented images"
- [readme] Two augmented images are propagated through a pair of ResNet18-based encoders that shared parameters, then output two 512-dimensional representation vectors: "Two augmented images are propagated through a pair of ResNet18-based encoders that shared parameters, then output two 512-dimensional representation vectors"
- [readme] A contrastive loss is employed to maximize similarity with a stop-gradient operation to prevent collapsing during training.: "A contrastive loss is employed to maximize similarity with a stop-gradient operation to prevent collapsing during training."
- [readme] COL and ISO are designed for the cases of regular co-localized ions from different molecules and isotope ions from a same molecule respectively.: "COL and ISO are designed for the cases of regular co-localized ions from different molecules and isotope ions from a same molecule respectively."
1---2name: ion-image-augmentation-design-23description: Use when when preparing ion image data from mass spectrometry imaging for contrastive self-supervised representation learning, and you need to generate augmented image pairs that reflect either co-localization relationships between different molecular ions (COL mode) or isotopic relationships.4license: CC-BY-4.05---67# ion-image-augmentation-design89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Design and apply mode-specific data augmentation pipelines (COL and ISO) to ion images for mass spectrometry imaging to generate contrastive pairs while preserving domain-relevant physical properties. The choice of augmentation mode and composition depends on the ion relationship type (co-localized vs. isotopic) and is critical for learning meaningful low-dimensional representations.1314## When to use1516When preparing ion image data from mass spectrometry imaging for contrastive self-supervised representation learning, and you need to generate augmented image pairs that reflect either co-localization relationships between different molecular ions (COL mode) or isotopic relationships within the same molecule (ISO mode). Use this skill when your input is raw or preprocessed MSI matrix data with known pixel dimensions and you require augmented images that preserve physical augmentation realism (e.g., photon counting artifacts, intensity-dependent pixel dropout).1718## When NOT to use1920- Ion images where spatial structure is unknown or pixel coordinates cannot be reliably mapped (augmentation may corrupt meaningful localization patterns).21- When isotope identification or co-localization discovery is not a downstream goal; use only if contrastive learning on ion relationships is required.22- Pre-augmented or already heavily corrupted ion images; augmentation assumes access to relatively clean original data to avoid compounding artifacts.2324## Inputs2526- Preprocessed MSI matrix data [X*Y, P] where X, Y are pixel coordinates and P is the number of ions27- Original ion image (2D spatial array of ion intensities)28- MSI data shape parameters (horizontal and vertical pixel counts)29- Ion mode designation ('positive' or 'negative')30- Mode selection ('COL' or 'ISO')3132## Outputs3334- Two augmented ion images from COL mode pipeline (color jitter → filtering → Poisson noise → random missing values)35- Two augmented ion images from ISO mode pipeline (COL operations + intensity-dependent missing values)36- 512-dimensional representation vectors (one per augmented image, generated by downstream ResNet18 encoders)3738## How to apply3940First, determine which augmentation mode matches your analysis goal: COL mode for co-localized ion discovery, ISO mode for isotope identification. Load the original ion image and apply the COL mode pipeline sequentially: color jitter to adjust pixel intensities, filtering to smooth or enhance spatial features, Poisson noise to simulate photon-counting artifacts inherent in mass spectrometry, and random missing values at arbitrary locations to model detector inefficiencies. For ISO mode, execute all COL operations, then apply an additional intensity-dependent missing value process that selectively removes pixels based on their intensity levels, modeling how low-intensity (likely isotopic) pixels are more prone to signal loss. Generate two augmented images per pipeline (four total: two from COL, two from ISO if running both modes). The augmented images are then fed to shared-parameter ResNet18 encoders to produce 512-dimensional representation vectors. Validate that augmentation preserves the spatial structure of ion localization patterns while introducing realistic noise and missing data consistent with MSI acquisition physics.4142## Related tools4344- **ResNet18** (Encoder backbone that processes augmented ion images to produce 512-dimensional representation vectors) — https://github.com/gankLei-X/DeepION45- **Color jitter augmentation** (First operation in COL mode pipeline; adjusts pixel intensities to simulate measurement variability) — https://github.com/gankLei-X/DeepION46- **Filtering augmentation** (Second operation in COL mode pipeline; smooths or enhances spatial features in ion images) — https://github.com/gankLei-X/DeepION47- **Poisson noise augmentation** (Third operation in COL mode pipeline; simulates photon-counting artifacts from mass spectrometry detection) — https://github.com/gankLei-X/DeepION48- **Random missing value augmentation** (Fourth operation in COL mode pipeline; introduces arbitrary pixel dropout to model detector inefficiencies) — https://github.com/gankLei-X/DeepION49- **Intensity-dependent missing value augmentation** (Additional operation unique to ISO mode; selectively removes pixels based on intensity levels for isotope-specific modeling) — https://github.com/gankLei-X/DeepION50- **kornia** (Supporting library for augmentation operations implementation)51- **boly_pytorch** (Supporting library for augmentation operations and contrastive learning implementation)5253## Examples5455```56python run.py --input_Matrix Pos_brain_data_matrix.txt --input_PeakList Pos_brain_data_peak.csv --input_shape 198 422 --mode COL --ion_mode positive --num 5 --output_file Pos_COL_result57```5859## Evaluation signals6061- Two augmented images are successfully generated per augmentation pipeline with no shape mismatch relative to the original ion image62- Augmented images retain spatial coherence: large-scale ion localization patterns are visually preserved despite noise and missing values63- Poisson noise magnitude is consistent with expected photon-counting statistics for mass spectrometry (variance ≈ intensity)64- Downstream ResNet18 encoders produce non-zero, non-NaN 512-dimensional vectors; contrastive loss converges during training, indicating meaningful augmentation diversity65- ISO mode augmented images exhibit selective intensity-dependent missing values (low-intensity pixels removed more frequently than high-intensity ones), validating isotope-specific augmentation behavior6667## Limitations6869- Augmentation design assumes access to clean, preprocessed MSI data; severely degraded or already artifact-heavy raw ion images may produce compounded corruption rather than meaningful contrastive pairs.70- Mode selection (COL vs. ISO) must match the true ion relationship type; applying ISO augmentation to co-localized ions or vice versa may degrade representation learning quality.71- Fixed augmentation hyperparameters (color jitter strength, Poisson noise rate, missing value fraction) are not explicitly tuned per dataset; optimal augmentation intensity may vary with MSI instrument, ionization mode, or sample type.72- No explicit augmentation-invariance validation is provided in the article; the method assumes that physical augmentations (noise, missing values) preserve ion relationship semantics without empirical quantification.73- Augmentation module does not account for spatial correlation in missing values (e.g., clustered detector failures common in real MSI); random missing value placement may underestimate artifacts in high-resolution spatial regions.7475## Evidence7677- [other] The COL mode augmentation applies four operations to ion images: color jitter, filtering, Poisson noise, and random missing value. The ISO mode includes all COL operations plus an additional intensity-dependent missing value process.: "The COL mode augmentation applies four operations to ion images: color jitter, filtering, Poisson noise, and random missing value. The ISO mode includes all COL operations plus an additional"78- [readme] T_COL including color jitter, filtering, Poisson noise, and random missing value is carried in COL mode, while T_ISO introduces an additional process of intensity-dependent missing value in ISO mode.: "T_COL including color jitter, filtering, Poisson noise, and random missing value is carried in COL mode, while T_ISO introduces an additional process of intensity-dependent missing value in ISO mode."79- [readme] The original ion image is first imported into the data augmentation module "T" to generate two augmented images: "The original ion image is first imported into the data augmentation module "T" to generate two augmented images"80- [readme] Two augmented images are propagated through a pair of ResNet18-based encoders that shared parameters, then output two 512-dimensional representation vectors: "Two augmented images are propagated through a pair of ResNet18-based encoders that shared parameters, then output two 512-dimensional representation vectors"81- [readme] A contrastive loss is employed to maximize similarity with a stop-gradient operation to prevent collapsing during training.: "A contrastive loss is employed to maximize similarity with a stop-gradient operation to prevent collapsing during training."82- [readme] COL and ISO are designed for the cases of regular co-localized ions from different molecules and isotope ions from a same molecule respectively.: "COL and ISO are designed for the cases of regular co-localized ions from different molecules and isotope ions from a same molecule respectively."
HolobiomicsLab