DOCSEARCHbyAlgolia
Submit Docs

SpatialData

repository·main·Indexed 18 days ago

https://github.com/scverse/spatialdata

An open and universal framework, schema, and serialization format for processing uni- and multi-modal spatial omics datasets. Built on the OME-NGFF specification, it supports Python, R, and JavaScript. The framework provides a central SpatialData object to manage co-registered images, labels, shapes, points, and tables, with specialized model classes like Image2DModel, ShapesModel, and TableModel.

Tokens
20.2K
Snippets
70
Records
107
Agent score
63%

What's inside spatialdata

  1. Overview of the SpatialData ecosystem

    main

    SpatialData is a framework, schema, and serialization format for uni- and multi-modal spatial omics datasets. While the core spatialdata library provides the foundation, the ecosystem includes several specialized packages:

    • spatialdata-io: Used for loading data from common spatial omics technologies into the spatialdata format.
    • spatialdata-plot: A static plotting library designed for spatialdata objects.
    • napari-spatialdata: A napari plugin for interactive exploration and annotation of spatialdata datasets.
    • SpatialData (R): An R implementation of the framework.
    • SpatialData.js: A JavaScript/TypeScript implementation of the framework.

  2. Related ecosystem projects for SpatialData

    main

    SpatialData is supported by several satellite projects that extend its functionality:

    • Visualization: napari-spatialdata (a napari plugin for interactive visualization).
    • Raw Data IO: spatialdata-io (implements readers for raw data from common spatial omics technologies).
    • Static Plotting: spatialdata-plot (a library for static plotting of SpatialData objects).
    • Analysis Integration: Future updates to squidpy are planned to allow it to accept SpatialData objects as input for spatial and graph analysis.

  3. What is SpatialData and what is its scope?

    main

    SpatialData is an open and interoperable framework designed for the storage and processing of multi-modal spatial omics data.

    Key Characteristics:

    • Infrastructure, not Analysis: SpatialData is not an analysis library itself; it provides the infrastructure (IO and spatial queries) for other analysis libraries to use.
    • Data Formats: It uses an in-memory Python representation and an on-disk representation based on Zarr and Parquet formats, following the OME-NGFF specification where applicable.
    • Interoperability: It uses OME-NGFF as its primary interchange format rather than acting as a general-purpose format converter.

    Core Capabilities:

    • Multi-modal Loading: Supports multiscale images/labels (2D/3D), point clouds, shapes (polygons, circles), tables, and graphs.
    • Lazy Loading: Supports lazy loading for images and points to handle large datasets efficiently.
    • Spatial Alignment: Supports affine transformations (scale, translation, rotation) and sequences of transformations to align datasets via common coordinate systems.
    • Spatial Querying: Enables querying multimodal datasets for all data within specific regions (bounding boxes, polygons, or balls).
    • Aggregation: Supports aggregating observations by regions of interest using summary statistics like mean, sum, and count.

  4. Understand SpatialElements and Tables in SpatialData

    main

    SpatialData datasets are composed of two main types of building blocks: SpatialElements and Tables.

    SpatialElements

    SpatialElements are the core components containing spatial information. They are not custom classes but are standard scientific Python objects enriched with specific metadata (such as coordinate systems and transformations). They are categorized into:

    • images: Raster data (e.g., pixel-based intensity maps).
    • labels: Raster data used for segmentation or annotations.
    • shapes: Vector data (e.g., polygons, circles).
    • points: Vector data (e.g., individual cell coordinates).

    Tables

    Tables are used to store tabular data like gene expression values or cell metadata. They are represented as anndata.AnnData objects. While Tables are fundamental building blocks, they are not considered SpatialElements because they do not contain spatial information themselves. However, Tables can be associated with SpatialElements to provide annotations (e.g., linking gene expression to specific cells/points).

  5. Understand the SpatialData Zarr format and NGFF

    main

    SpatialData uses a specialized storage format based on the OME-Zarr specification:

    • NGFF (Next-Generation File Format): A specification by the OME (Open Microscopy Environment) for storing large-scale, multi-dimensional imaging and spatial data efficiently, often using Zarr.
    • OME-Zarr: An implementation of NGFF using the Zarr format.
    • SpatialData Zarr format: An extension of the OME-Zarr format. While OME-Zarr was originally designed for bioimaging, the SpatialData extension is required to accommodate the specific needs of spatial omics data.
    • Zarr Storage: A format for multi-dimensional arrays that supports chunking and compression. This allows SpatialData objects to be stored as .zarr directories, enabling efficient, scalable access to large datasets without loading everything into memory.

  6. Understand the SpatialData data model and Elements

    main

    A SpatialData object is a container for various spatial omics data types, known as Elements. Elements are not custom classes but standard scientific Python objects (like xarray.DataArray or AnnData) enriched with specific metadata for spatial integration.

    Key Elements include:

    • Images: 2D or 3D pixel-based arrays (e.g., microscopy images).
    • Regions of Interest:
      • Labels: Pixel masks (2D or 3D) representing segmentation or regions.
      • Shapes: Geometric primitives (circles, polygons) represented as geopandas DataFrames.
    • Points: 2D or 3D coordinates (e.g., transcript locations) represented as dask.dataframe.DataFrame.
    • Tables: Annotations for regions, represented as AnnData objects.

    Elements are semantically grouped using coordinate systems and coordinate transformations rather than explicit links. For example, a Labels element and an Image element are related if they share the same spatial coordinate system.

  7. How coordinate transformations work in SpatialData

    main

    SpatialData uses two sets of transformation classes to manage the relationship between intrinsic (data-defined) and extrinsic (user-defined) coordinate systems:

    1. NGFF-compliant transformations (NgffBaseTransformations): Used for I/O. These require full specification of both input and output coordinate systems. Examples include NgffIdentity, NgffTranslation, NgffScale, and NgffAffine.
    2. SpatialData transformations (BaseTransformation): Used for in-memory operations. These are self-defined and do not require explicit coordinate system knowledge. They apply transformations by "passing through" axes present in the element but not in the transformation, and ignoring axes present in the transformation but not in the element.

    Example behavior: Applying Scale([2, 3, 4], axes=('x', 'y', 'z')) to a cyx image will scale x and y, pass c through unaltered, and ignore the scaling for z because the z axis is missing.

  8. Understand the SpatialData model building blocks

    main

    A SpatialData object is composed of several specialized model types that represent different modalities of spatial omics data. These models act as the fundamental building blocks for storing and organizing spatial information. The available models are:

    • Images: Image2DModel and Image3DModel for multi-channel or volumetric image data.
    • Labels: Labels2DModel and Labels3DModel for segmentation masks or annotated regions.
    • Geometry: ShapesModel for polygons/lines and PointsModel for point-based data (e.g., cell centroids).
    • Tabular Data: TableModel for storing metadata, gene expression, or other attribute-based tables.

  9. Align images using transformations

    main

    SpatialData allows for affine (linear) transformations to map images onto each other.

    • If you already have a transformation matrix, use the Transformation/coordinate system tutorial.
    • If you do not have a matrix, use the Landmark annotation tutorial to align images using landmarks.

  10. Understand the SpatialData data format structure

    main

    The SpatialData format is built as a collection of versioned subclasses of ome_zarr.format.Format. Each subclass corresponds to a specific type of element (Raster, Shapes, Points, or Tables).

    To ensure backward compatibility during major version changes, SpatialData uses specific versioned classes (e.g., ShapesFormatV01, ShapesFormatV02) alongside 'Current' pointers (e.g., CurrentShapesFormat) that always point to the most up-to-date implementation.

    All valid formats are encompassed by the spatialdata.SpatialDataFormatType union type.

  11. Difference between Raster and Vector data

    main

    SpatialData handles two primary types of geometric representations:

    • Raster: Data represented as a grid of pixels (e.g., images or labels).
      • Rasterization is the process of converting vector shapes into a pixel-based raster format.
    • Vector: Data represented by mathematical coordinates defining geometric shapes (e.g., points, circles, or polygons).
      • Vectorization is the process of converting raster data into a vector format (e.g., converting a pixel-based cell boundary into a polygon of vertices).

  12. Annotate cells using AnnData (Tables)

    main
    In SpatialData, cell annotations (count/intensity data, cell types, etc.) are stored in tables, which follow the AnnData format. This allows you to use scanpy functionality like normalization, clustering, and differential expression calculation on your spatial data.