msi-intensity-matrix-isotope-correction
License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution.
Summary
Type II isotopic correction removes [M+Na]+ adduct overlap from [M+H]+ ion images in mass spectrometry imaging (MSI) data by subtracting scaled sodium adduct intensities from protonated adduct intensities across all pixels in a feature-by-pixel intensity matrix. This correction is essential for accurate lipid quantitation in imzML-formatted MSI experiments where multiple adduct forms of the same neutral lipid species co-ionize.
When to use
Apply this skill when you have loaded a feature-by-pixel intensity matrix (HDF5 format following Cardinal::HDF5 layout) from imzML MSI data in positive ion mode and you have identified paired [M+H]+ and [M+Na]+ features for the same neutral lipid species (differing by ~22 Da in m/z). Use this when [M+H]+ signals are contaminated by isotopic overlap from [M+Na]+ adducts and you need corrected intensities for downstream quantitation based on internal standards.
When NOT to use
- Input is negative ion mode MSI data (Type II correction applies only to [M+H]+/[M+Na]+ pairs in positive mode)
- No paired [M+H]+/[M+Na]+ features exist in the feature list (correction requires identifiable sodium adduct partners)
- Intensity matrix is not in feature-by-pixel layout or does not follow Cardinal::HDF5 conventions (workflow assumes specific HDF5 structure)
Inputs
- Feature-by-pixel intensity matrix (float32, shape n_features × n_pixels)
- Feature metadata including neutral lipid identifiers and m/z values
- HDF5 container with Cardinal::HDF5 layout (spectraData/intensity dataset, featureData, pixelData groups)
Outputs
- Corrected feature-by-pixel intensity matrix (float32, same shape as input)
- Updated HDF5 container with corrected spectraData/intensity dataset
- Preserved featureData, pixelData, and all dimension scales and layout metadata
How to apply
First, identify paired [M+H]+ and [M+Na]+ features by matching neutral lipid identifiers and verifying their m/z difference is approximately 22 Da (accounting for the mass difference of Na vs H substitution). For each [M+Na]+ feature, calculate its fractional contribution to the corresponding [M+H]+ feature using natural isotope abundance ratios (the Type II correction model). Subtract the scaled [M+Na]+ pixel intensities from the corresponding [M+H]+ pixel intensities across the entire feature-by-pixel matrix, then clamp all negative resulting values to zero to preserve physical meaning. Write the corrected intensity matrix back to the HDF5 container in the spectraData/intensity dataset while preserving all dimension scales, metadata (feature_by_pixel layout flag), and the pixelData and featureData groups unchanged.
Related tools
- LipidQMap (Implements Type II isotopic correction via graphical interface; loads imzML files, identifies [M+H]+/[M+Na]+ pairs, performs correction, and exports corrected ion images) — https://github.com/swinnenteam/LipidQMap
- Cardinal (Defines the HDF5 data structure (Cardinal::HDF5 conventions) used to store and retrieve the feature-by-pixel intensity matrix and metadata) — https://cardinalmsi.org
Evaluation signals
- Corrected [M+H]+ intensities are ≤ raw [M+H]+ intensities at each pixel (subtraction never increases signal)
- No negative intensity values remain in the corrected matrix (all clamped to zero)
- Feature and pixel metadata (IDs, m/z values, spatial coordinates) are unchanged in featureData and pixelData groups
- HDF5 dimension scales and layout flag (feature_by_pixel) are preserved in the output container
- User can toggle between raw, isotope-corrected, and quantified images in LipidQMap UI, confirming correction was applied
Limitations
- Type II correction assumes natural isotope abundance ratios are constant; unusual isotope enrichment in samples will invalidate the correction model
- Correction requires precise m/z matching (~22 Da difference) to pair [M+H]+ and [M+Na]+ features; low mass resolution or miscalibration may fail to identify pairs
- Negative pixel intensities are clamped to zero, potentially losing information about noise or measurement artifacts
- Correction is applied globally across all pixels; spatial heterogeneity in adduct formation is not accounted for
Evidence
- [other] LipidQMap performs Type II isotopic correction by correcting [M+H]+ adducts for isotopic overlap contributed by [M+Na]+ adducts in ion images.: "LipidQMap performs Type II isotopic correction by correcting [M+H]+ adducts for isotopic overlap contributed by [M+Na]+ adducts in ion images."
- [other] Load the feature-by-pixel intensity matrix (float32, shape n_features × n_pixels) and feature metadata from the input HDF5 file using the Cardinal::HDF5 layout.: "Load the feature-by-pixel intensity matrix (float32, shape n_features × n_pixels) and feature metadata from the input HDF5 file using the Cardinal::HDF5 layout."
- [other] Identify paired [M+H]+ and [M+Na]+ features by matching neutral lipid identifiers and comparing their m/z values (accounting for mass difference of ~22 Da for Na vs H substitution).: "Identify paired [M+H]+ and [M+Na]+ features by matching neutral lipid identifiers and comparing their m/z values (accounting for mass difference of ~22 Da for Na vs H substitution)."
- [other] For each [M+Na]+ feature, calculate its fractional contribution to the corresponding [M+H]+ feature based on natural isotope abundance ratios (Type II correction model).: "For each [M+Na]+ feature, calculate its fractional contribution to the corresponding [M+H]+ feature based on natural isotope abundance ratios (Type II correction model)."
- [other] Subtract the scaled [M+Na]+ intensities from the [M+H]+ intensities across all pixels, clamping negative values to zero.: "Subtract the scaled [M+Na]+ intensities from the [M+H]+ intensities across all pixels, clamping negative values to zero."
- [other] Write the corrected intensity matrix back to the HDF5 container in the same spectraData/intensity dataset, preserving dimension scales, layout metadata (feature_by_pixel), and all pixelData and featureData groups unchanged.: "Write the corrected intensity matrix back to the HDF5 container in the same spectraData/intensity dataset, preserving dimension scales, layout metadata (feature_by_pixel), and all pixelData and"
- [readme] Can perform Type II isotopic correction, and can correct [M+H]+ adducts for isotopic overlap from [M+Na]+ adducts.: "Can perform Type II isotopic correction, and can correct [M+H]+ adducts for isotopic overlap from [M+Na]+ adducts."
- [readme] In the imzML import dialog, click on the "Open Files" button to select one or more imzML files. Select if the file contains positive or negative ion mode data.: "In the imzML import dialog, click on the "Open Files" button to select one or more imzML files. Select if the file contains positive or negative ion mode data."
1---2name: msi-intensity-matrix-isotope-correction3description: Use when you have loaded a feature-by-pixel intensity matrix (HDF5 format following Cardinal::HDF5 layout) from imzML MSI data in positive ion mode and you have identified paired [M+H]+ and [M+Na]+ features for the same neutral lipid species (differing by ~22 Da in m/z).4license: CC-BY-4.05---67# msi-intensity-matrix-isotope-correction89> **License: restricted** — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->10## Summary1112Type II isotopic correction removes [M+Na]+ adduct overlap from [M+H]+ ion images in mass spectrometry imaging (MSI) data by subtracting scaled sodium adduct intensities from protonated adduct intensities across all pixels in a feature-by-pixel intensity matrix. This correction is essential for accurate lipid quantitation in imzML-formatted MSI experiments where multiple adduct forms of the same neutral lipid species co-ionize.1314## When to use1516Apply this skill when you have loaded a feature-by-pixel intensity matrix (HDF5 format following Cardinal::HDF5 layout) from imzML MSI data in positive ion mode and you have identified paired [M+H]+ and [M+Na]+ features for the same neutral lipid species (differing by ~22 Da in m/z). Use this when [M+H]+ signals are contaminated by isotopic overlap from [M+Na]+ adducts and you need corrected intensities for downstream quantitation based on internal standards.1718## When NOT to use1920- Input is negative ion mode MSI data (Type II correction applies only to [M+H]+/[M+Na]+ pairs in positive mode)21- No paired [M+H]+/[M+Na]+ features exist in the feature list (correction requires identifiable sodium adduct partners)22- Intensity matrix is not in feature-by-pixel layout or does not follow Cardinal::HDF5 conventions (workflow assumes specific HDF5 structure)2324## Inputs2526- Feature-by-pixel intensity matrix (float32, shape n_features × n_pixels)27- Feature metadata including neutral lipid identifiers and m/z values28- HDF5 container with Cardinal::HDF5 layout (spectraData/intensity dataset, featureData, pixelData groups)2930## Outputs3132- Corrected feature-by-pixel intensity matrix (float32, same shape as input)33- Updated HDF5 container with corrected spectraData/intensity dataset34- Preserved featureData, pixelData, and all dimension scales and layout metadata3536## How to apply3738First, identify paired [M+H]+ and [M+Na]+ features by matching neutral lipid identifiers and verifying their m/z difference is approximately 22 Da (accounting for the mass difference of Na vs H substitution). For each [M+Na]+ feature, calculate its fractional contribution to the corresponding [M+H]+ feature using natural isotope abundance ratios (the Type II correction model). Subtract the scaled [M+Na]+ pixel intensities from the corresponding [M+H]+ pixel intensities across the entire feature-by-pixel matrix, then clamp all negative resulting values to zero to preserve physical meaning. Write the corrected intensity matrix back to the HDF5 container in the spectraData/intensity dataset while preserving all dimension scales, metadata (feature_by_pixel layout flag), and the pixelData and featureData groups unchanged.3940## Related tools4142- **LipidQMap** (Implements Type II isotopic correction via graphical interface; loads imzML files, identifies [M+H]+/[M+Na]+ pairs, performs correction, and exports corrected ion images) — https://github.com/swinnenteam/LipidQMap43- **Cardinal** (Defines the HDF5 data structure (Cardinal::HDF5 conventions) used to store and retrieve the feature-by-pixel intensity matrix and metadata) — https://cardinalmsi.org4445## Evaluation signals4647- Corrected [M+H]+ intensities are ≤ raw [M+H]+ intensities at each pixel (subtraction never increases signal)48- No negative intensity values remain in the corrected matrix (all clamped to zero)49- Feature and pixel metadata (IDs, m/z values, spatial coordinates) are unchanged in featureData and pixelData groups50- HDF5 dimension scales and layout flag (feature_by_pixel) are preserved in the output container51- User can toggle between raw, isotope-corrected, and quantified images in LipidQMap UI, confirming correction was applied5253## Limitations5455- Type II correction assumes natural isotope abundance ratios are constant; unusual isotope enrichment in samples will invalidate the correction model56- Correction requires precise m/z matching (~22 Da difference) to pair [M+H]+ and [M+Na]+ features; low mass resolution or miscalibration may fail to identify pairs57- Negative pixel intensities are clamped to zero, potentially losing information about noise or measurement artifacts58- Correction is applied globally across all pixels; spatial heterogeneity in adduct formation is not accounted for5960## Evidence6162- [other] LipidQMap performs Type II isotopic correction by correcting [M+H]+ adducts for isotopic overlap contributed by [M+Na]+ adducts in ion images.: "LipidQMap performs Type II isotopic correction by correcting [M+H]+ adducts for isotopic overlap contributed by [M+Na]+ adducts in ion images."63- [other] Load the feature-by-pixel intensity matrix (float32, shape n_features × n_pixels) and feature metadata from the input HDF5 file using the Cardinal::HDF5 layout.: "Load the feature-by-pixel intensity matrix (float32, shape n_features × n_pixels) and feature metadata from the input HDF5 file using the Cardinal::HDF5 layout."64- [other] Identify paired [M+H]+ and [M+Na]+ features by matching neutral lipid identifiers and comparing their m/z values (accounting for mass difference of ~22 Da for Na vs H substitution).: "Identify paired [M+H]+ and [M+Na]+ features by matching neutral lipid identifiers and comparing their m/z values (accounting for mass difference of ~22 Da for Na vs H substitution)."65- [other] For each [M+Na]+ feature, calculate its fractional contribution to the corresponding [M+H]+ feature based on natural isotope abundance ratios (Type II correction model).: "For each [M+Na]+ feature, calculate its fractional contribution to the corresponding [M+H]+ feature based on natural isotope abundance ratios (Type II correction model)."66- [other] Subtract the scaled [M+Na]+ intensities from the [M+H]+ intensities across all pixels, clamping negative values to zero.: "Subtract the scaled [M+Na]+ intensities from the [M+H]+ intensities across all pixels, clamping negative values to zero."67- [other] Write the corrected intensity matrix back to the HDF5 container in the same spectraData/intensity dataset, preserving dimension scales, layout metadata (feature_by_pixel), and all pixelData and featureData groups unchanged.: "Write the corrected intensity matrix back to the HDF5 container in the same spectraData/intensity dataset, preserving dimension scales, layout metadata (feature_by_pixel), and all pixelData and"68- [readme] Can perform Type II isotopic correction, and can correct [M+H]+ adducts for isotopic overlap from [M+Na]+ adducts.: "Can perform Type II isotopic correction, and can correct [M+H]+ adducts for isotopic overlap from [M+Na]+ adducts."69- [readme] In the imzML import dialog, click on the "Open Files" button to select one or more imzML files. Select if the file contains positive or negative ion mode data.: "In the imzML import dialog, click on the "Open Files" button to select one or more imzML files. Select if the file contains positive or negative ion mode data."
