SpatialExperiment

A Python package for storing and analyzing spatial-omics experimental data. SpatialExperiment extends SingleCellExperiment with dedicated slots for image data and spatial coordinates, making it ideal for spatial transcriptomics and other spatially-resolved omics data.

Note

This package is in active development.

Install

To get started, install the package from PyPI

pip install spatialexperiment

Usage

The SpatialExperiment class extends SingleCellExperiment with the following key attributes:

• spatial_coords: A BioFrame containing spot/cell spatial coordinates relative to the image, typically including:

  • x-coordinates
  • y-coordinates
  • Additional spatial metadata

• img_data: A BiocFrame containing image-related information:

  • sample_ids: Unique identifiers for each sample
  • image_ids: Unique identifiers for each image
  • data: The actual image data
  • scale_factor: Scaling factors for proper image interpretation

• column_data: Contains sample_id mappings that link spots to their corresponding images

Quick Start

Here's how to create a SpatialExperiment object from scratch:

from spatialexperiment import SpatialExperiment, SpatialImage
import numpy as np
from biocframe import BiocFrame

# Create example data
nrows = 200  # Number of features (e.g., genes)
ncols = 500  # Number of spots/cells

# Generate random count data
counts = np.random.rand(nrows, ncols)

# Create feature annotations
row_data = BiocFrame({
    "gene_ids": [f"gene_{i}" for i in range(nrows)],
    "gene_names": [f"Gene_{i}" for i in range(nrows)]
})

# Create spot/cell annotations
col_data = BiocFrame({
    "n_genes": [50, 200] * int(ncols / 2),
    "condition": ["healthy", "tumor"] * int(ncols / 2),
    "cell_id": [f"spot_{i}" for i in range(ncols)],
    "sample_id": ["sample_1"] * int(ncols / 2) + ["sample_2"] * int(ncols / 2),
})

# Generate spatial coordinates
spatial_coords = BiocFrame({
    "x": np.random.uniform(low=0.0, high=100.0, size=ncols),
    "y": np.random.uniform(low=0.0, high=100.0, size=ncols)
})

# Create image data
img_data = BiocFrame({
    "sample_id": ["sample_1", "sample_1", "sample_2"],
    "image_id": ["aurora", "dice", "desert"],
    "data": [
        SpatialImage("tests/images/sample_image1.jpg"),
        SpatialImage("tests/images/sample_image2.png"),
        SpatialImage("tests/images/sample_image3.jpg"),
    ],
    "scale_factor": [1, 1, 1],
})

# Create SpatialExperiment object
spe = SpatialExperiment(
    assays={"counts": counts},
    row_data=row_data,
    column_data=col_data,
    spatial_coords=spatial_coords,
    img_data=img_data,
)

For more detailed information about available methods and functionality, please refer to the SingleCellExperiment documentation.

Note

This project has been set up using BiocSetup and PyScaffold.