# Bioconductor Spatialexperiment

> Defines an S4 class for storing data from spatial -omics experiments. The class extends SingleCellExperiment to support storage and retrieval of additional information from spot-based and molecule-based platforms, including spatial coordina

- Skill: `biomate-ai/bioconductor-spatialexperiment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add biomate-ai/bioconductor-spatialexperiment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/biomate-ai/bioconductor-spatialexperiment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: biomate-ai (https://skillmd.com/u/biomate-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/biomate-ai/bioconductor-spatialexperiment

---


# SpatialExperiment

## Dependencies & Environment

> Package-intrinsic requirements from the Bioconductor landing page — reproduce in any R environment.

- **Version:** 1.22.0 · **Bioconductor:** 3.23 · **R:** ≥ 4.6
- **Depends:** SingleCellExperiment
- **Imports:** rjson, magick, S4Vectors, SummarizedExperiment, BiocGenerics, BiocFileCache
- **Install:** `BiocManager::install("SpatialExperiment")`

## When to Use
- **Spot-Based Spatial Transcriptomics**: Representing and manipulating data from spot-based spatial transcriptomics platforms (e.g., 10x Genomics Visium) containing gene expression, spatial coordinates, and histology images using `SpatialExperiment()` and `imgData()`.
- **Molecule-Resolved Spatial Data**: Storing and querying molecule-resolved spatial data (e.g., seqFISH) where exact X-Y coordinates of individual transcripts are recorded, using `splitAsBumpyMatrix()` and the `molecules()` accessor.
- **Image Transformations**: Applying basic image transformations like rotation and mirroring to spatial images using `rotateImg()` and `mirrorImg()`.

## When NOT to Use
- For **standard single-cell RNA-seq data** lacking spatial coordinates, use `SingleCellExperiment` instead because the spatial-specific slots like `spatialCoords` and `imgData` will remain empty and add unnecessary overhead.
- For **pure image processing** without transcriptomics, use other imaging tools because `SpatialExperiment` is designed to link `assays` (like `counts`) with spatial metadata.

## Data Requirements
- **Assays**: A count matrix (e.g., `counts`) representing gene expression across spatial locations.
- **Spatial Coordinates**: A numeric matrix or `DataFrame` of coordinates (e.g., `x` and `y`) for each spot or cell.
- **Image Data (Optional)**: Images stored as `SpatialImage` objects within an `imgData` `DataFrame`.

## Key Parameters
- **assays** (required): A list of matrices containing expression data (e.g., `counts`).
- **spatialCoords** (optional): A numeric matrix containing spatial coordinates.
- **spatialCoordsNames** (optional): A character vector specifying which `colData` fields correspond to spatial coordinates.
- **imgData** (optional): A `DataFrame` containing image metadata and `SpatialImage` objects.
- **colData** (optional): A `DataFrame` containing spot- or cell-level metadata.
- **sample_id** (default `"sample_01"`): A character string specifying the sample identifier.

## Best Practices
- Use `spatialCoords()` and `imgData()` accessor functions instead of directly manipulating internal slots to maintain object integrity.
- For 10x Genomics Visium data, use `TENxVisiumList()` and `import()` from the `VisiumIO` package to automatically load outputs from Space Ranger.
- Make sample identifiers unique prior to combining objects with `cbind()` to avoid automatic index appending.

## Common Pitfalls
- **Duplicated sample IDs during replacement**: Attempting to replace `sample_id`s with non-unique values returns an error; fix this by ensuring replacement IDs map uniquely to existing ones.
- **Loss of sample IDs**: Attempting to remove `sample_id` by setting it to `NULL` fails because it is a protected field; fix this by retaining the `sample_id` or replacing it with valid unique strings.
- **Conflicting spatial coordinates**: Supplying both `spatialCoords` and `spatialCoordsNames` causes `spatialCoordsNames` to be ignored; fix this by setting either to `NULL` to suppress the warning message.

## Alternatives
- **SingleCellExperiment**: The parent class, which can store coordinates in `colData` but lacks dedicated `spatialCoords` and `imgData` slots.
- **Seurat**: Another framework for single-cell and spatial data analysis.
- **Giotto**: An independent R package for spatial transcriptomics.

## Citations
- Righelli, D., et al. (2022). SpatialExperiment: infrastructure for spatially resolved transcriptomics data in Bioconductor. *Bioinformatics*, 38(11), 3128-3130.

## References
- Homepage: bioconductor.org/packages/SpatialExperiment
- Vignette: https://bioconductor.org/packages/release/bioc/vignettes/SpatialExperiment/inst/doc/SpatialExperiment.html

<!-- biomate-cta -->
---

## Run this on BioMate

This skill is the **knowledge layer** — when, why, and how to use `spatialexperiment`. To **run this analysis on your own data** with managed compute, automated QC, and reproducible outputs, use **[BioMate](https://www.biomate.ai?ref=kb&pkg=spatialexperiment)** — free to start.

▶ **[Open `spatialexperiment` on BioMate →](https://www.biomate.ai?ref=kb&pkg=spatialexperiment)**