HolobiomicsLab bioinformatic-object-conversion
Summary
Conversion of mass spectrometry imaging data from one standardized bioinformatic object format to another—specifically, transforming Cardinal MSImagingExperiment objects into Seurat-compatible SpaMTP objects while preserving spectral intensities, spatial coordinates, feature metadata (m/z values), and any derived annotations (e.g., spatial shrunken centroids clustering). This skill enables seamless integration of MSI data into the Seurat ecosystem for downstream spatial-omics analysis.
When to use
When you have processed Cardinal MSI data (normalized peak intensities, optional SSC segmentation results) and need to transition to Seurat-based workflows for differential expression, pathway analysis, or integration with spatial transcriptomics data. Specifically: the input is a Cardinal MSImagingExperiment object containing spectral data and spatial pixel coordinates; the analysis goal requires Seurat-native functions (e.g., NormalizeData, ScaleData, pathway assays); and you have metadata annotations (m/z feature info, clustering results) that must transfer intact.
When NOT to use
- Input is already a Seurat object or other non-Cardinal format—no conversion needed.
- Cardinal object is unprocessed or lacks normalized peak intensities; convert only after normalization and quality control are complete.
- Spatial coordinates are missing or cannot be reliably extracted from the Cardinal object; conversion requires valid x, y pixel positions for each spectrum.
Inputs
- Cardinal MSImagingExperiment object (processed, with normalized peaks and optional SSC segmentation results)
- m/z feature metadata (mass-to-charge ratio values and associated ion identities)
- Pixel spatial coordinates (x, y pixel positions)
- Optional: Cardinal-derived annotations (SSC clustering labels, peak classifications)
Outputs
- Seurat object with 'Spatial' assay
- SpaMTP-compatible object (inherits Seurat Class Object)
- Transferred spatial coordinates (in spatial slot)
- Transferred feature metadata (m/z values in feature meta.data)
- Transferred Cardinal annotations (in cell/pixel metadata)
How to apply
Invoke the CardinalToSeurat conversion function on a loaded and processed Cardinal MSImagingExperiment object. The function extracts three core components: (1) spectral intensities (m/z feature counts per pixel), (2) pixel spatial coordinates (x, y locations), and (3) feature metadata (m/z values and ion identities). These are packaged into a Seurat object with the 'Spatial' assay containing spectral counts, spatial metadata transferred to the object's spatial coordinate slot, and feature metadata (m/z, annotations) preserved in the feature meta.data slot. Any Cardinal-derived annotations—such as SSC-based clustering assignments or peak classifications—are transferred to the Seurat object's cell (pixel) metadata. The rationale: this preserves all experimental and computational context while enabling access to Seurat's rich statistical and visualization ecosystem (differential metabolite analysis, CreatePathwayAssay, ImageDimPlot, etc.).
Related tools
- Cardinal (Source object format; provides MSImagingExperiment class, normalization, and segmentation (SSC) functionality for input data preparation) — https://github.com/Vitek-Lab/Cardinal3-vignettes
- Seurat (Target object format and downstream analysis platform; provides Spatial assay, NormalizeData, ScaleData, pathway assays, and visualization functions post-conversion) — https://satijalab.org/seurat/
- SpaMTP (Wrapper package inheriting both Cardinal and Seurat functionalities; implements CardinalToSeurat conversion and provides integrative spatial-omics analysis tools) — https://github.com/GenomicsMachineLearning/SpaMTP
Examples
spotted_seurat <- CardinalToSeurat(spotted_cardinal); DefaultAssay(spotted_seurat) <- "Spatial"; spotted_seurat <- NormalizeData(spotted_seurat)
Evaluation signals
- Seurat object is successfully created and contains a 'Spatial' assay with spectral intensity counts matching the original Cardinal object's peak matrix.
- Spatial coordinates (x, y pixel positions) are present in the Seurat object's spatial coordinate slot and match the original Cardinal MSI pixel positions.
- Feature metadata (m/z values and ion annotations) are preserved in the feature meta.data slot with no loss of information.
- Cardinal-derived metadata (e.g., SSC cluster assignments) are transferred to the Seurat object's cell metadata (pixel metadata) and remain accessible via standard Seurat accessors.
- Standard Seurat functions (NormalizeData, ScaleData, CreatePathwayAssay, ImageDimPlot) execute without error on the converted object.
Limitations
- Conversion assumes the Cardinal object has been previously normalized and quality-filtered; unnormalized or raw data may not transfer meaningful spectral intensities.
- Spatial resolution and pixel metadata are preserved only if they exist in the source Cardinal object; missing spatial information cannot be imputed during conversion.
- The conversion is one-directional (Cardinal → Seurat); reverse conversion back to Cardinal format is not part of this workflow and may require separate tools.
- Feature annotation accuracy depends on prior Cardinal-based m/z assignment and lipid nomenclature curation; errors in m/z matching or ion naming propagate to the converted Seurat object.
Evidence
- [methods] Load a processed Cardinal MSImagingExperiment object containing normalized peaks and optional spatial shrunken centroids (SSC) segmentation results.: "Load a processed Cardinal MSImagingExperiment object containing normalized peaks and optional spatial shrunken centroids (SSC) segmentation results."
- [methods] Construct a Seurat object with the 'Spatial' assay containing spectral counts, transfer spatial metadata (x, y coordinates) to the object's spatial slot, and preserve feature metadata (m/z values) in the feature meta.data slot.: "Construct a Seurat object with the 'Spatial' assay containing spectral counts, transfer spatial metadata (x, y coordinates) to the object's spatial slot, and preserve feature metadata (m/z values) in"
- [methods] Preserve any Cardinal-derived annotations (e.g., SSC clustering results) in the Seurat object's cell metadata for downstream analysis compatibility.: "Preserve any Cardinal-derived annotations (e.g., SSC clustering results) in the Seurat object's cell metadata for downstream analysis compatibility."
- [readme] SpaMTP inherits functionalities from two well established R packages (Cardinal and Seurat) to present a user-friendly platform for integrative spatial-omics analysis. Build on the foundation of a Seurat Class Object: "SpaMTP inherits functionalities from two well established R packages (Cardinal and Seurat) to present a user-friendly platform for integrative spatial-omics analysis. Build on the foundation of a"