SpatialData framework for handling spatial multi-modal and multi-scale data. Use this skill for questions about spatial omics data analysis, visualization, and the SpatialData Python ecosystem.
Visualizing spatial data with napari or spatialdata-plot
Performing spatial queries and data aggregation
Framework Implementation:
Building spatial data pipelines with SpatialData objects
Implementing coordinate transformations and spatial indexing
Working with OME-NGFF/Zarr format storage
Creating annotation tables with AnnData
Technical Operations:
Loading/saving spatial data in various formats
Querying spatial elements by regions of interest
Performing SQL-like joins between spatial elements and tables
相关技能
Managing multi-scale image pyramids and chunked storage
Ecosystem Integration:
Using spatialdata-io for technology-specific readers
Integrating with napari-spatialdata for interactive visualization
Working with spatialdata-plot for static plotting
Processing data from technologies like Visium, Stereo-seq, MERFISH
Key Concepts
Core SpatialData Elements
Images: Multi-dimensional arrays with channels (c), spatial dimensions (y, x, z), and coordinate transformations
Labels: Segmentation masks as integer arrays where each value represents a spatial region/instance
Points: Coordinate data for transcript locations, point clouds, or single-molecule data
Shapes: Geometric regions (circles, polygons, multipolygons) for areas of interest
Tables: AnnData objects storing annotations that can be linked to spatial elements
Essential Terminology
Coordinate Systems: Reference frames for spatial alignment and transformations
Spatial Elements: Building blocks (images, labels, points, shapes) with metadata
OME-NGFF: Open Microscopy Environment Next-Generation File Format specification
Zarr: Chunked storage format for large multi-dimensional arrays
Regions of Interest (ROIs): Specific spatial subsets for analysis
Multi-scale: Pyramidal image representations at different resolutions
Data Relationships
Tables can annotate spatial elements but not other tables
Images cannot be directly annotated by tables (no index)
Spatial elements require coordinate systems and transformations
Labels and Shapes are both types of "Regions"
Quick Reference
Basic Data Operations
1. Load and explore sample dataset
from spatialdata.datasets import blobs
sdata = blobs()
print(sdata)
# Shows all elements: images, labels, points, shapes, tables
2. Access element instances and properties
# Get unique label instances
from spatialdata import get_element_instances
instances = get_element_instances(sdata["blobs_multiscale_labels"])
# Get image channels
from spatialdata.models import get_channels
channels = get_channels(sdata["blobs_multiscale_image"])
3. Work with coordinate transformations
# Set image channels
from spatialdata.models import Image2DModel
sdata["blobs_image"] = Image2DModel.parse(
sdata["blobs_image"],
c_coords=["r", "g", "b"]
)
Annotation and Table Operations
4. Retrieve annotation values from elements
from spatialdata import get_values
# Get values from points element
genes = get_values(value_key="genes", element=sdata["blobs_points"])
# Get values from table annotations
channel_values = get_values(
value_key="channel_0_sum",
sdata=sdata,
element_name="blobs_labels",
table_name="table"
)
Transformations: Coordinate systems and transformations
Utils: Helper functions for data manipulation
Examples: Function signatures and usage patterns
advanced.md (4 pages)
Content: Design document and advanced concepts
Use for: Understanding framework architecture, design decisions
Key sections: Goals and non-goals, element types, OME-NGFF compliance, coordinate systems
Examples: Technical specifications and implementation details
io.md (1 page)
Content: Glossary and terminology
Use for: Understanding spatial data terminology
Key sections: Definitions of NGFF, OME, Zarr, ROI, spatial elements, vector/raster data
Examples: Clear explanations of technical terms
other.md (6 pages)
Content: General information and links
Use for: Project overview, citation information, ecosystem links
Key sections: Main project description, related packages, contributing guidelines
Examples: Links to documentation and resources
Working with This Skill
For Beginners
Start with getting_started.md to install SpatialData and dependencies
Use the Quick Reference examples to understand basic operations
Practice with the blobs dataset - it contains examples of all element types
Learn the terminology from io.md glossary
Beginner workflow:
# 1. Install and load
pip install spatialdata
from spatialdata.datasets import blobs
# 2. Explore the data structure
sdata = blobs()
print(sdata)
# 3. Access specific elements
points = sdata["blobs_points"]
labels = sdata["blobs_labels"]
# 4. Basic operations
from spatialdata import get_values
values = get_values("genes", element=points)
For Intermediate Users
Study api.md for detailed function references
Learn spatial queries - bounding_box_query and polygon_query
Work with annotations - understand table-element relationships
Explore coordinate transformations and multi-scale data
Intermediate workflow:
# 1. Create your own annotation tables
from spatialdata.models import TableModel
table = TableModel.parse(adata, region="my_labels")
# 2. Perform spatial queries
result = sdata.query.bounding_box(...)
# 3. Join data with annotations
from spatialdata import join_spatialelement_table
elements, table = join_spatialelement_table(...)
# 4. Work with coordinate systems
sdata.transform_to("global", "new_system")
For Advanced Users
Read advanced.md for architecture understanding
Implement custom data readers using spatialdata-io patterns
Optimize performance with chunking and lazy loading
Contribute to the ecosystem - understanding OME-NGFF compliance
Advanced workflow:
# 1. Create custom elements with specific transformations
from spatialdata.models import Image2DModel
image = Image2DModel.parse(
data,
transformations={"custom": Translation([100, 100])}
)
# 2. Optimize large datasets
# Use chunking, multi-scale representations
# Implement custom spatial indexes
# 3. Extend the framework
# Create custom models, readers, or visualization tools
Navigation Tips
For installation issues: Check getting_started.md for dependency conflicts
For API questions: Search api.md for specific function names
For conceptual understanding: Start with io.md terminology, then read advanced.md
For practical examples: Use the Quick Reference section with real code patterns
For ecosystem integration: Look for spatialdata-io, spatialdata-plot, napari-spatialdata references
Resources
Ecosystem Packages
spatialdata-io: Technology-specific readers and converters
spatialdata-plot: Static plotting and visualization
napari-spatialdata: Interactive napari plugin
spatialdata-sandbox: Example datasets and converters
Storage Formats
Zarr: Chunked storage for large arrays
OME-NGFF: Standard for bioimaging data
Parquet: Columnar storage for tabular data
Community
scverse project: Governance and contribution guidelines
GitHub repository: Source code and issue tracking
Documentation: Comprehensive guides and tutorials
Notes
SpatialData uses standard scientific Python libraries (xarray, AnnData, geopandas)
All spatial elements require coordinate systems and transformations
Tables use AnnData format and can annotate multiple spatial elements
The framework emphasizes lazy loading and chunked storage for performance
Compatible with OME-NGFF specification for interoperability
Updating
To refresh this skill with updated documentation:
Re-run the scraper with the same configuration
The skill will be rebuilt with the latest information from the SpatialData documentation