How scverse/spatialdata works
Project Type and Purpose
• SpatialData is a Python data‐framework library for spatial omics: it provides an in‐memory object model, I/O to/from disk in OME-NGFF/Zarr, high-level operations (map, aggregate, rasterize, vectorize), and transformation utilities.
• It ships a CLI entrypoint, a core API, multiple sub-packages (dataloader, io, models, transformations), plus docs, benchmarks, and tests.
A. CLI/API Layer
• src/spatialdata/__main__.py → “spatialdata” command-line entrypoint
• High-level API functions in src/spatialdata/\*.py (e.g., config.py, testing.py)
B. Core Library Layer
• src/spatialdata/_core/ — spatialdata objects, element definitions, centroids, concatenation, extent, validation
• src/spatialdata/_core/operations/ — spatial operations (aggregate, map, rasterize, transform, vectorize)
• src/spatialdata/_core/query/ — relational and spatial query engines
C. I/O Layer
• src/spatialdata/_io/ — format definitions, utilities
• Readers/Writers: io_points, io_raster, io_shapes, io_table, io_zarr
D. Dataloader & Dataset Layer
• src/spatialdata/dataloader/ → “datasets.py” for standardized dataset ingestion
• src/spatialdata/datasets.py → helper functions to construct common spatialdata instances
E. Models & Transformations Layer
• src/spatialdata/models/ — statistical or ML-style models on spatialdata
• src/spatialdata/transformations/ — coordinate transforms, NGFF coordinate systems, operations utils
F. Storage & External Dependencies
• OME-NGFF/Zarr on disk
• External libraries: xarray, zarr, numpy, pandas, pyproj, dask (implied by I/O)
G. Extensions & Ecosystem
• Integration points with spatialdata-io, spatialdata-plot, napari-spatialdata
H. Tooling & CI/CD
• GitHub workflows (build_image.yml, test.yaml, release.yaml), Dockerfile, benchmarks/asv, docs build
Relationships and Data Flows
• CLI/API → Core Library (invokes operations, queries)
• Core Library → I/O Layer (load/save datasets)
• Core Library ↔ Dataloader (to assemble SpatialData objects from raw inputs)
• Core Library → Models & Transformations (applies transforms and model fits)
• I/O Layer → Zarr/OME-NGFF (disk or cloud storage backend)
• Ecosystem packages → I/O Layer & Core Library (plug-ins use the same interfaces)
Architectural Patterns & Design Principles
• Layered architecture (API → Core → I/O → Storage)
• Plugin-style extensibility: new I/O formats, new transform modules, new dataloaders
• Separation of concerns: “_core” is pure in-memory data logic; “_io” handles persistence; “dataloader” ingest; “models” & “transformations” live on top
• Use of object-oriented design for data elements and functional decomposition for operations
Optional CI/CD & Documentation Layer
• At the side or bottom, represent GitHub Actions workflows, Dockerfile, docs build pipeline
• This informs maintainers how code changes propagate into releases and docs