# SpatialData-DB

> SpatialData-DB is a catalog of 13,541 public spatial omics datasets, grouped into 659 collections (the first pandas example below counts them per technology). Each dataset is converted to the SpatialData format and loads with one Python call. This file is for AI agents, and it is generated from catalog release catalog-2026-11-17.

## When to use

- Find spatial omics datasets by technology, tissue, organism or disease: call the MCP tool find_datasets (POST JSON-RPC to `/mcp`, e.g. `{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "find_datasets", "arguments": {"technology": "Xenium", "tissue": "lung", "organism": "human"}}}`), or filter catalog.parquet with pandas (How to query the catalog, below).
- Find the datasets that measure a gene or protein: the MCP tool find_by_gene, e.g. `{"symbol": "EPCAM"}`.
- Load one dataset as a SpatialData object: install the client (`pip install "spatialdata-db @ git+https://github.com/theislab/spatialdata-db-client@v0.1.4"`), then `Catalog().dataset("<uid>").to_sdata()` (Load a dataset, below).
- Cite the datasets you used: `cohort.citations("refs.bib")` in the client writes BibTeX for their studies, and every dataset page has a Cite section (Cite, below).
- Look at one dataset in full: the MCP tool show_dataset with its uid or slug, or its page /datasets/<slug>/.

## How to query the catalog

Send a descriptive User-Agent with every request (for example `my-agent/1.0 (contact@example.org)`): the host refuses Python's default urllib User-Agent with HTTP 403 (Cloudflare error 1010), while requests, curl and browsers work.

Ask the MCP server first (POST to `/mcp`, see Pages below). It counts, filters and summarizes every catalog column without a download, and each answer has a Python snippet pinned to the release. Download the files only for bulk work, e.g. a table of all datasets.

The catalog is one Parquet file per release, with one row per dataset, and collections.parquet has one row per collection. pandas or pyarrow read them straight from the release URL. A catalog.csv.gz, which Python's csv and gzip modules can read without pyarrow, comes with the next catalog release. Datasets per technology:

```python
import pandas as pd
catalog = pd.read_parquet("https://github.com/theislab/spatialdata-db-client/releases/download/catalog-2026-11-17/catalog.parquet")
print(catalog.groupby("technology").size().sort_values(ascending=False))
```

Human Xenium datasets of the lung, with their size and licence:

```python
sel = catalog[(catalog.organism == "human") & (catalog.technology == "10x_xenium") & (catalog.tissue == "lung")]
print(sel[["uid", "slug", "title", "n_obs", "license"]])
```

`technology` holds the platform id, e.g. '10x_xenium' or '10x_visium'; technology.json next to the catalog gives each id its label.

To find the datasets that measure a gene or protein, call the MCP tool find_by_gene (see Pages below). The release also has gene_search.parquet and feature_search.parquet, with one row per gene or feature and a bitset over the datasets, and a person can use the gene filter on /datasets/.

## Columns

- `uid`: the dataset's id; the last 4 characters are its version.
- `study_id`: the study key; it is also the citation key in citations.bib.
- `organism`: human, mouse and so on.
- `tissue`: the tissue, as a name; tissue_id holds the ontology id (UBERON, or PO for plants).
- `disease`: the disease or condition; disease_id holds the MONDO id.
- `tissue_system`: the body system the tissue belongs to — top level of the tissue facet (tissue_system_id: its ontology id).
- `tissue_organ`: the organ the tissue belongs to — middle level of the tissue facet (tissue_organ_id: its ontology id).
- `disease_class`: the broad disease class — top level of the disease facet (disease_class_id: its ontology id).
- `disease_group`: the disease group — middle level of the disease facet (disease_group_id: its ontology id).
- `technology`: the platform id since catalog schema 3, e.g. 10x_visium, 10x_xenium, vizgen_merscope, ionpath_mibiscope (labels in the release's technology.json).
- `assay`: the assay name as the source gives it.
- `panel_size`: the number of target genes for targeted panels.
- `validation_status`: pass or fail: whether the curator validation succeeded with at most 5% of genes unresolved.
- `tier`: the dataset's tier: bronze or silver (gold is defined but not assigned in current releases); /llms-full.txt has the rule.
- `license`: the dataset's own licence (an SPDX-like id); check it before reuse.
- `license_url`: a link to the licence text.
- `license_noncommercial`: true when the licence forbids commercial use.
- `n_obs`: the number of observations (cells, spots, bins or pixels, see obs_unit).
- `n_features`: the number of genes or other features in the default table.
- `zarr_url`: the SpatialData store (.zarr) the client loads.
- `size_bytes`: the store's size.
- `slug`: the dataset's page on this site: /datasets/<slug>/.
- `title`: the source's title for the sample.
- `pathological`: false for disease "normal", empty for a missing or "unknown" disease, true otherwise.
- `low_obs`: true when n_obs is under 100.
- `review_status`: under_review when curation raised a question about the dataset (review_reason says which), else empty.
- `modality`: RNA, protein, metabolomics and so on; several are joined with |.
- `n_transcripts`: decoded transcripts, for imaging assays.
- `publication_date`: the source release date (when the repository made the data public), not the paper's date; to cite, use publication_year.
- `doi`: the publication DOI, when known.
- `publication_year`: the year of the paper that describes the dataset (empty when none is linked); use it for citations.
- `dataset_url`: the source page the data came from.
- `collections`: the slugs of the collections the dataset belongs to.
- `obs_unit`: what one observation is: cells, spots, bins, pixels or ROIs (null when unknown).
- `segmentation_source`: who segmented the cells: depositor, vendor or spatialdata-db.
- `same_section_group`: 10x libraries of one tissue section share this id (the newest release's uid).
- `panel`: the gene or antibody panel, as free text.

The full column list is in /llms-full.txt.

## Load a dataset

Install the client (Python 3.12 or newer):

```bash
pip install "spatialdata-db @ git+https://github.com/theislab/spatialdata-db-client@v0.1.4"
```

```python
from sddb import Catalog

ds = Catalog().dataset("VkGigAlvHGdpmGVG0000")
ds.elements()          # inspect without downloading
sdata = ds.to_sdata()  # cached locally, reused
print(sdata)
```

## Cite

Cite the dataset's publication, from the `doi` column, or the source in `dataset_url` when there is none. The release also has citations.bib (https://github.com/theislab/spatialdata-db-client/releases/download/catalog-2026-11-17/citations.bib), keyed by `study_id`. Every dataset page on this site has a "Cite this dataset" section.

## Releases and versions

Each catalog release is a GitHub release named catalog-YYYY-MM-DD (https://github.com/theislab/spatialdata-db-client/releases). This site and this file are built from catalog-2026-11-17. Put the release tag in every URL you store, so a result can be reproduced. A dataset's uid ends in a 4-character version, and the client release is v0.1.4.

## Licences

Every row carries its own licence (`license`, `license_url`, `license_noncommercial`) and its source (`dataset_url`). Check them before reusing a dataset. Some sources allow non-commercial use only.

## Pages

- [Datasets](/datasets/): all datasets with filters.
- [Collections](/collections/): studies and other groups of datasets.
- [Statistics](/stats/): counts and distributions.
- [Full agent guide](/llms-full.txt): this file plus every column and collection query.
- [OpenAPI description](/openapi.json): every route above, with the release as a parameter.
- MCP server: POST JSON-RPC to `/mcp` on this site (MCP streamable HTTP, stateless, read-only). Its tools are catalog_release, find_datasets, find_by_gene, show_dataset, summarize, list_values. Filters match exact values, ignoring case, by label or ontology id, and never a part of a word, so "brain" doesn't match "brainstem". /llms-full.txt describes each tool.
- [Sitemap](/sitemap.xml): every page and agent file. Each dataset page also has schema.org JSON-LD in its head, a Croissant 1.1 record with the store's URL.
- Markdown: every page links its Markdown version in its head (`<link rel="alternate" type="text/markdown">`). Datasets are in 256 files, [/datasets/md/00.md](/datasets/md/00.md) to /datasets/md/ff.md, and collections in 16, [/collections/md/0.md](/collections/md/0.md) to /collections/md/f.md, each section anchored by its slug.
- [Client documentation](https://spatialdata-db.readthedocs.io/en/latest/).
