contrastive-pair-generation
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Generate paired augmented images from a single ion image in mass spectrometry imaging (MSI) to enable contrastive learning. This skill is essential for training representation models that learn meaningful low-dimensional embeddings of ion spatial distributions while avoiding collapsed solutions.
When to use
Apply this skill when you have raw ion images from MSI data and need to train a contrastive encoder to learn stable, mode-specific representations. Use it specifically when your downstream task is co-localized ion discovery (COL mode) or isotope ion identification (ISO mode), and you want to maximize similarity between augmented views of the same image while preventing representation collapse.
When NOT to use
- When the input ion image is already a pre-computed 512-dimensional or lower-dimensional representation vector; augmentation is only meaningful on raw or reconstructed spatial images.
- When your analysis goal is descriptive spatial visualization rather than learning transferable representations; augmentation overhead is unnecessary if you only need to visualize raw ion distributions.
- When downstream tasks do not require robustness to intensity variations or missing values (e.g., simple peak intensity comparison without spatial context).
Inputs
- Raw ion image (2D pixel intensity matrix)
- MSI matrix data with shape [X*Y, P] where X, Y are horizontal/vertical pixel counts and P is ion count
- Mode specification: 'COL' or 'ISO'
- Pixel intensity values for intensity-dependent masking (ISO mode only)
Outputs
- First augmented ion image (T_COL applied)
- Second augmented ion image (T_COL + T_ISO for ISO mode, or T_COL for COL mode)
- Paired augmented image tuple for contrastive encoder input
How to apply
Load the raw ion image and extract pixel intensity values. Apply the T_COL augmentation suite (color jitter, filtering, Poisson noise, random missing value) to create the first augmented image. Apply the identical T_COL transformations to create a second augmented image. For ISO mode only, apply an additional intensity-dependent missing-value masking step to the second augmented image, where the probability of a pixel being masked is conditioned on its intensity value. Output both augmented images as a paired tuple for propagation through shared-parameter ResNet18 encoders. The contrastive loss will then maximize similarity between the two views while a stop-gradient operation prevents representation collapse.
Related tools
- ResNet18 (Shared-parameter encoder that processes both augmented images in parallel to produce 512-dimensional representation vectors for contrastive loss computation) — https://github.com/gankLei-X/DeepION
- kornia (Provides differentiable implementations of color jitter, filtering, and other augmentation transforms in the T_COL and T_ISO pipeline)
- PyTorch (Deep learning framework enabling efficient tensor-based augmentation, encoder propagation, and contrastive loss optimization)
Examples
python run.py --input_Matrix .../DATASET/Pos_brain_data_matrix.txt --input_PeakList .../DATASET/Pos_brain_data_peak.csv --input_shape 198 422 --mode ISO --ion_mode positive --output_file Pos_ISO_result
Evaluation signals
- Both augmented images retain spatial structure (pixel coordinates and local intensity patterns are preserved after augmentation); verify by visual inspection or local autocorrelation comparison.
- T_COL transforms (color jitter, filtering, Poisson noise, random missing value) are applied identically to both images; verify by recording and comparing random seeds or augmentation parameters used for each image.
- For ISO mode, the second augmented image has additional intensity-dependent missing value masking; verify by checking that masked pixels in the second image correlate with low/high intensity regions according to the learned masking function.
- Paired augmented images produce similar 512-dimensional encoder outputs before projection; verify by computing cosine similarity or Euclidean distance between encoder outputs and confirming it is higher than random image pairs.
- Contrastive loss decreases during training and representation collapse is prevented; verify by monitoring that the norm of representation vectors remains stable (neither exploding nor shrinking to zero).
Limitations
- Intensity-dependent missing value masking (T_ISO) assumes pixel intensity is a meaningful proxy for data quality; if intensity variation is noise rather than signal, the masking may discard valuable spatial information.
- Random missing value and intensity-dependent masking may remove genuine biological signal at certain intensity ranges, potentially biasing learned representations toward mid-range intensities.
- Poisson noise and color jitter are heuristic approximations of real MSI measurement variability; the augmentation may not capture all sources of systematic error in the instrument or preprocessing pipeline.
- The skill requires careful tuning of augmentation hyperparameters (jitter magnitude, filter kernels, noise level, masking probability function); suboptimal choices can lead to uninformative or over-regularized representations.
Evidence
- [other] T_ISO augmentation extends T_COL by introducing an additional intensity-dependent missing value process specifically for the ISO mode to generate two augmented images from an original ion image.: "T_ISO augmentation extends T_COL (which includes color jitter, filtering, Poisson noise, and random missing value) by introducing an additional intensity-dependent missing value process specifically"
- [readme] Two augmented images are propagated through ResNet18-based encoders to output 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] Projection and Prediction modules are used to avoid collapsing solutions and ensure meaningful representation learning with contrastive loss.: "Projection module and Prediction module are used to avoid collapsing solutions during the optimization process of maximizing the similarity between two augmentations from a same image and ensure to"
- [readme] T_COL includes color jitter, filtering, Poisson noise, and random missing value, while T_ISO introduces intensity-dependent missing value in ISO mode.: "The 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"
1---2name: contrastive-pair-generation3description: Use when you have raw ion images from MSI data and need to train a contrastive encoder to learn stable, mode-specific representations.4license: CC-BY-4.05---67# contrastive-pair-generation89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Generate paired augmented images from a single ion image in mass spectrometry imaging (MSI) to enable contrastive learning. This skill is essential for training representation models that learn meaningful low-dimensional embeddings of ion spatial distributions while avoiding collapsed solutions.1314## When to use1516Apply this skill when you have raw ion images from MSI data and need to train a contrastive encoder to learn stable, mode-specific representations. Use it specifically when your downstream task is co-localized ion discovery (COL mode) or isotope ion identification (ISO mode), and you want to maximize similarity between augmented views of the same image while preventing representation collapse.1718## When NOT to use1920- When the input ion image is already a pre-computed 512-dimensional or lower-dimensional representation vector; augmentation is only meaningful on raw or reconstructed spatial images.21- When your analysis goal is descriptive spatial visualization rather than learning transferable representations; augmentation overhead is unnecessary if you only need to visualize raw ion distributions.22- When downstream tasks do not require robustness to intensity variations or missing values (e.g., simple peak intensity comparison without spatial context).2324## Inputs2526- Raw ion image (2D pixel intensity matrix)27- MSI matrix data with shape [X*Y, P] where X, Y are horizontal/vertical pixel counts and P is ion count28- Mode specification: 'COL' or 'ISO'29- Pixel intensity values for intensity-dependent masking (ISO mode only)3031## Outputs3233- First augmented ion image (T_COL applied)34- Second augmented ion image (T_COL + T_ISO for ISO mode, or T_COL for COL mode)35- Paired augmented image tuple for contrastive encoder input3637## How to apply3839Load the raw ion image and extract pixel intensity values. Apply the T_COL augmentation suite (color jitter, filtering, Poisson noise, random missing value) to create the first augmented image. Apply the identical T_COL transformations to create a second augmented image. For ISO mode only, apply an additional intensity-dependent missing-value masking step to the second augmented image, where the probability of a pixel being masked is conditioned on its intensity value. Output both augmented images as a paired tuple for propagation through shared-parameter ResNet18 encoders. The contrastive loss will then maximize similarity between the two views while a stop-gradient operation prevents representation collapse.4041## Related tools4243- **ResNet18** (Shared-parameter encoder that processes both augmented images in parallel to produce 512-dimensional representation vectors for contrastive loss computation) — https://github.com/gankLei-X/DeepION44- **kornia** (Provides differentiable implementations of color jitter, filtering, and other augmentation transforms in the T_COL and T_ISO pipeline)45- **PyTorch** (Deep learning framework enabling efficient tensor-based augmentation, encoder propagation, and contrastive loss optimization)4647## Examples4849```50python run.py --input_Matrix .../DATASET/Pos_brain_data_matrix.txt --input_PeakList .../DATASET/Pos_brain_data_peak.csv --input_shape 198 422 --mode ISO --ion_mode positive --output_file Pos_ISO_result51```5253## Evaluation signals5455- Both augmented images retain spatial structure (pixel coordinates and local intensity patterns are preserved after augmentation); verify by visual inspection or local autocorrelation comparison.56- T_COL transforms (color jitter, filtering, Poisson noise, random missing value) are applied identically to both images; verify by recording and comparing random seeds or augmentation parameters used for each image.57- For ISO mode, the second augmented image has additional intensity-dependent missing value masking; verify by checking that masked pixels in the second image correlate with low/high intensity regions according to the learned masking function.58- Paired augmented images produce similar 512-dimensional encoder outputs before projection; verify by computing cosine similarity or Euclidean distance between encoder outputs and confirming it is higher than random image pairs.59- Contrastive loss decreases during training and representation collapse is prevented; verify by monitoring that the norm of representation vectors remains stable (neither exploding nor shrinking to zero).6061## Limitations6263- Intensity-dependent missing value masking (T_ISO) assumes pixel intensity is a meaningful proxy for data quality; if intensity variation is noise rather than signal, the masking may discard valuable spatial information.64- Random missing value and intensity-dependent masking may remove genuine biological signal at certain intensity ranges, potentially biasing learned representations toward mid-range intensities.65- Poisson noise and color jitter are heuristic approximations of real MSI measurement variability; the augmentation may not capture all sources of systematic error in the instrument or preprocessing pipeline.66- The skill requires careful tuning of augmentation hyperparameters (jitter magnitude, filter kernels, noise level, masking probability function); suboptimal choices can lead to uninformative or over-regularized representations.6768## Evidence6970- [other] T_ISO augmentation extends T_COL by introducing an additional intensity-dependent missing value process specifically for the ISO mode to generate two augmented images from an original ion image.: "T_ISO augmentation extends T_COL (which includes color jitter, filtering, Poisson noise, and random missing value) by introducing an additional intensity-dependent missing value process specifically"71- [readme] Two augmented images are propagated through ResNet18-based encoders to output 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"72- [readme] Projection and Prediction modules are used to avoid collapsing solutions and ensure meaningful representation learning with contrastive loss.: "Projection module and Prediction module are used to avoid collapsing solutions during the optimization process of maximizing the similarity between two augmentations from a same image and ensure to"73- [readme] T_COL includes color jitter, filtering, Poisson noise, and random missing value, while T_ISO introduces intensity-dependent missing value in ISO mode.: "The 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"
HolobiomicsLab