# scverse/squidpy architecture

> Architecture diagram of the GitHub repository scverse/squidpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/scverse/squidpy
- Repository: https://github.com/scverse/squidpy

## Overview

1. **What this repository is**
   Squidpy is a Python library for spatial omics analysis. The central architecture is a set of analysis and visualization modules that operate mainly on `anndata.AnnData`-style data, with a parallel image-processing layer for tissue microscopy. It is not an app; it is a scientific computation toolkit.

2. **Core data model boundary**
   The main boundary is between spatial transcriptomics/cell data and image data. Transcriptomic/spatial metadata is handled through read/analysis routines, while microscopy images are handled through the `im` package. Results are typically attached back to the input object and then consumed by plotting or downstream analysis.

3. **Input and data acquisition layer**
   The `read` package contains file readers, with explicit support for Visium-oriented spatial inputs. The `datasets` package is separate and handles example-data discovery, registry lookup, and downloading of packaged datasets from remote sources. This isolates “load user data” from “fetch tutorial/test data.”

4. **Graph and spatial statistics subsystem**
   The `gr` namespace is the main analytical engine. It groups algorithms for spatial neighbor graphs and higher-level analyses such as neighborhood enrichment, co-occurrence/patterns, Ripley-style spatial statistics, niche analysis, ligand-receptor analysis, and SEPAL-related routines. These functions consume spatial coordinates, graph structures, and annotations.

5. **Tooling / feature extraction layer**
   The `tl` namespace contains more method-like analysis utilities, such as sliding-window computations and distance-based variable summaries. This layer sits between raw input/graph construction and the plotting layer, providing reusable computed features for downstream analysis.

6. **Image processing subsystem**
   The `im` package is the dedicated image pipeline. It includes container abstractions, coordinate handling, I/O, preprocessing, segmentation, and feature extraction. This module is where high-resolution tissue images are normalized, tiled, segmented, and transformed into derived features used by the graph/statistics layers.

7. **Experimental image extensions**
   `experimental/im` contains newer or provisional image workflows such as tissue detection and tile generation. Keeping these under an `experimental` namespace is an architectural boundary: stable APIs remain in `im`, while incubating image methods are isolated from the core contract.

8. **Visualization subsystem**
   The `pl` package contains plotting code for graphs, spatial views, ligand-receptor results, and variable-by-distance outputs. It also includes interactive plotting support in a nested `_interactive` area. Plotting is a consumer layer: it renders results produced by `gr`, `tl`, `im`, and `read` without owning the analysis logic.

9. **Shared infrastructure and utilities**
   The repository has a small set of shared modules for constants, compatibility shims, validators, docs helpers, and generic utilities. These are cross-cutting support pieces that reduce duplication across the analysis, I/O, and plotting packages.

10. **Documentation and examples as a first-class surface**
   `docs/` is extensive and includes API reference, class docs, tutorials, notebooks, release notes, and custom Sphinx extensions. This indicates the library’s architecture is meant to be learned through executable examples, not only through API reference.

11. **Tests mirror the package boundaries**
   `tests/` mirrors the main subsystems: datasets, read, image, graph, plotting, tools, experimental, and utility helpers. This is a strong sign that each top-level package is an independently testable subsystem with its own contracts and fixtures.

12. **Build and release pipeline**
   GitHub Actions workflows cover build, test, notebook execution, and release. Supporting scripts in `.scripts/ci` download data and run notebooks during CI. ReadTheDocs configuration and code coverage integration show that documentation and reproducibility are part of the release architecture.

13. **External ecosystem dependencies that shape the design**
   The package is built around the scverse stack, especially `scanpy` and `anndata`, and uses scientific image tooling such as `scikit-image`. The README also points users to `napari-spatialdata` for interactive visualization, which suggests Squidpy’s own interactive layer is being aligned with the broader SpatialData ecosystem rather than acting as the primary viewer.

14. **How to draw the architecture**
   A good diagram would show: external spatial data and image files flowing into `read`/`datasets` and `im`; analysis branching into `gr` and `tl`; derived results flowing into `pl`; and `experimental/im` as a side branch for emerging image features. Surrounding all of that are shared utilities, docs, tests, and CI/release automation.

Main entry points: [`src/squidpy/read`](https://github.com/scverse/squidpy/tree/main/src/squidpy/read) (Read), [`src/squidpy/im`](https://github.com/scverse/squidpy/tree/main/src/squidpy/im) (Images), [`src/squidpy/gr`](https://github.com/scverse/squidpy/tree/main/src/squidpy/gr) (Graph stats), [`src/squidpy/pl`](https://github.com/scverse/squidpy/tree/main/src/squidpy/pl) (Plotting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_read["Read"]
  node_datasets["Datasets<br/>dataset registry"]
  node_im["Images<br/>image pipeline"]
  node_expim["Exp. images<br/>provisional image workflows"]
  node_gr["Graph stats<br/>spatial analysis"]
  node_tl["Tools<br/>feature utilities"]
  node_pl["Plotting<br/>visualization"]
end

subgraph group_support["Shared support"]
  node_constants["Constants<br/>shared config"]
  node_utils["Utils<br/>shared helpers<br/>[_utils.py]"]
  node_validators["Validators<br/>input checks<br/>[_validators.py]"]
  node_docshelpers["Docs helpers<br/>doc tooling<br/>[_docs.py]"]
end

subgraph group_docs["Docs"]
  node_documentation["Docs"]
end

subgraph group_tests["Tests"]
  node_testsuite["Tests"]
end

subgraph group_automation["Automation"]
  node_ci["CI workflows<br/>automation<br/>[workflows]"]
  node_scripts["CI scripts<br/>pipeline scripts<br/>[ci]"]
end

node_datasets -->|"example data"| node_read
node_read -->|"coordinates"| node_gr
node_read -->|"input tables"| node_tl
node_read -->|"loaded data"| node_pl
node_im -->|"image-derived features"| node_gr
node_im -->|"image views"| node_pl
node_expim -.->|"emerging APIs"| node_im
node_gr -->|"results"| node_pl
node_tl -->|"summaries"| node_pl
node_constants -->|"shared config"| node_read
node_constants -->|"shared config"| node_im
node_utils -->|"helpers"| node_gr
node_utils -->|"helpers"| node_pl
node_validators -->|"validation"| node_read
node_validators -->|"validation"| node_im
node_validators -->|"validation"| node_gr
node_docshelpers -->|"doc build"| node_documentation
node_testsuite -->|"coverage"| node_read
node_testsuite -->|"coverage"| node_im
node_testsuite -->|"coverage"| node_gr
node_testsuite -->|"coverage"| node_pl
node_scripts -->|"support"| node_ci
node_ci -->|"publish"| node_documentation
node_ci -->|"verify"| node_testsuite

click node_read "https://github.com/scverse/squidpy/tree/main/src/squidpy/read"
click node_datasets "https://github.com/scverse/squidpy/tree/main/src/squidpy/datasets"
click node_im "https://github.com/scverse/squidpy/tree/main/src/squidpy/im"
click node_expim "https://github.com/scverse/squidpy/tree/main/src/squidpy/experimental/im"
click node_gr "https://github.com/scverse/squidpy/tree/main/src/squidpy/gr"
click node_tl "https://github.com/scverse/squidpy/tree/main/src/squidpy/tl"
click node_pl "https://github.com/scverse/squidpy/tree/main/src/squidpy/pl"
click node_constants "https://github.com/scverse/squidpy/tree/main/src/squidpy/_constants"
click node_utils "https://github.com/scverse/squidpy/blob/main/src/squidpy/_utils.py"
click node_validators "https://github.com/scverse/squidpy/blob/main/src/squidpy/_validators.py"
click node_docshelpers "https://github.com/scverse/squidpy/blob/main/src/squidpy/_docs.py"
click node_documentation "https://github.com/scverse/squidpy/tree/main/docs"
click node_testsuite "https://github.com/scverse/squidpy/tree/main/tests"
click node_ci "https://github.com/scverse/squidpy/blob/main/.github/workflows"
click node_scripts "https://github.com/scverse/squidpy/blob/main/.scripts/ci"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_read,node_datasets,node_im,node_expim,node_gr,node_tl,node_pl toneBlue
class node_constants,node_utils,node_validators,node_docshelpers toneAmber
class node_documentation toneMint
class node_testsuite toneRose
class node_ci,node_scripts toneIndigo
```

## Components

### Core library

Primary analysis, I/O, image, and plotting subsystems.

- [Read](https://github.com/scverse/squidpy/tree/main/src/squidpy/read): I/O readers · Loads spatial inputs such as Visium-style data into the library's data model. · `src/squidpy/read`
- [Datasets](https://github.com/scverse/squidpy/tree/main/src/squidpy/datasets): dataset registry · Resolves, downloads, and serves packaged example datasets separate from user data loading. · `src/squidpy/datasets`
- [Images](https://github.com/scverse/squidpy/tree/main/src/squidpy/im): image pipeline · Core microscopy image container, coordinate handling, I/O, preprocessing, segmentation, and feature extraction. · `src/squidpy/im`
- [Exp. images](https://github.com/scverse/squidpy/tree/main/src/squidpy/experimental/im): provisional image workflows · Incubating image workflows such as tissue detection and tile generation. · `src/squidpy/experimental/im`
- [Graph stats](https://github.com/scverse/squidpy/tree/main/src/squidpy/gr): spatial analysis · Neighbor graphs, enrichment, co-occurrence, Ripley-style statistics, niche analysis, ligand-receptor analysis, and SEPAL routines. · `src/squidpy/gr`
- [Tools](https://github.com/scverse/squidpy/tree/main/src/squidpy/tl): feature utilities · Sliding-window and distance-based summaries used to prepare analysis features. · `src/squidpy/tl`
- [Plotting](https://github.com/scverse/squidpy/tree/main/src/squidpy/pl): visualization · Static and interactive plotting for graphs, spatial views, ligand-receptor results, and variable-by-distance outputs. · `src/squidpy/pl`

### Shared support

Cross-cutting constants, utilities, validators, and docs helpers.

- [Constants](https://github.com/scverse/squidpy/tree/main/src/squidpy/_constants): shared config · Package-wide constants and low-level shared definitions. · `src/squidpy/_constants`
- [Utils](https://github.com/scverse/squidpy/blob/main/src/squidpy/_utils.py): shared helpers · General-purpose helper functions used across the package. · `src/squidpy/_utils.py`
- [Validators](https://github.com/scverse/squidpy/blob/main/src/squidpy/_validators.py): input checks · Validation helpers that enforce contracts across readers, analysis, and plotting. · `src/squidpy/_validators.py`
- [Docs helpers](https://github.com/scverse/squidpy/blob/main/src/squidpy/_docs.py): doc tooling · Documentation-facing helpers shared by API docs and generated references. · `src/squidpy/_docs.py`

### Docs

Documentation, tutorials, and release notes.

- [Docs](https://github.com/scverse/squidpy/tree/main/docs): Sphinx docs · Reference docs, tutorials, notebooks, release notes, and custom Sphinx extensions. · `docs`

### Tests

Subsystem-level regression tests and fixtures.

- [Tests](https://github.com/scverse/squidpy/tree/main/tests): subsystem tests · Package-aligned tests for datasets, read, image, graph, plotting, tools, experimental code, and utilities. · `tests`

### Automation

CI, notebook execution, and release workflows.

- [CI workflows](https://github.com/scverse/squidpy/blob/main/.github/workflows): automation · GitHub Actions workflows for build, test, notebook execution, and release. · `.github/workflows`
- [CI scripts](https://github.com/scverse/squidpy/blob/main/.scripts/ci): pipeline scripts · Helper scripts that download data and execute notebooks during CI. · `.scripts/ci`

## Connections

- Datasets → Read: example data · Provides packaged datasets used alongside real user inputs.
- Read → Graph stats: coordinates · Feeds spatial observations and annotations into graph/statistical analyses.
- Read → Tools: input tables · Supplies imported data for derived feature computation.
- Read → Plotting: loaded data · Visualization consumes the imported spatial objects.
- Images → Graph stats: image-derived features · Image features and segmentation outputs can inform spatial analysis.
- Images → Plotting: image views · Plotting renders image-based outputs and overlays.
- Exp. images → Images: emerging APIs · Experimental image workflows extend the stable image subsystem.
- Graph stats → Plotting: results · Graph and spatial-statistics outputs are rendered by plotting.
- Tools → Plotting: summaries · Derived summaries become plotting inputs.
- Constants → Read: shared config · Provides package-level constants used by readers.
- Constants → Images: shared config · Provides package-level constants used by image code.
- Utils → Graph stats: helpers · Shared helpers support graph construction and analysis routines.
- Utils → Plotting: helpers · Shared helpers support plotting utilities.
- Validators → Read: validation · Checks reader inputs and file-specific assumptions.
- Validators → Images: validation · Checks image container and preprocessing inputs.
- Validators → Graph stats: validation · Checks analysis parameters and outputs.
- Docs helpers → Docs: doc build · Supports generated API/reference documentation.
- Tests → Read: coverage · Exercises reader contracts and fixtures.
- Tests → Images: coverage · Exercises image pipeline behavior.
- Tests → Graph stats: coverage · Exercises spatial-statistics algorithms.
- Tests → Plotting: coverage · Exercises plotting behavior.
- CI scripts → CI workflows: support · Feeds workflow steps for data download and notebook execution.
- CI workflows → Docs: publish · Build and release automation keeps docs and notebooks reproducible.
- CI workflows → Tests: verify · Workflows run the test matrix and notebook checks.
