SDK Quick Start

Official Python and R client libraries for the Stomics.io API. Install the SDK, authenticate with your API key, and get data into your analysis pipeline in two lines of code.

Installation

Minimum Python 3.9. The [anndata] extra adds AnnData and scanpy integration.

pip install stomics-py
# With AnnData support (recommended):
pip install "stomics-py[anndata]"

Quick Start

Authenticate, search, load an AnnData object, and plot — all in under 10 lines.

from stomics import StomicsClient

# Authenticate — reads STOMICS_API_KEY env var automatically
client = StomicsClient()

# 1. Search for brain datasets
datasets = client.search(query="brain cortex", per_page=5)
for ds in datasets:
    print(ds.accession, ds.title)

# 2. Load expression data into AnnData
adata = client.load_anndata("STD0001")
print(adata)  # AnnData object with obsm['spatial'] populated

# 3. Plot with scanpy
import scanpy as sc
sc.pl.spatial(adata, color="n_genes_by_counts")

Search datasets

Filter the catalog by organism, tissue, disease, or technology.

from stomics import StomicsClient

client = StomicsClient(api_key="sk-your-key")

# Filter by organism, tissue, technology
results = client.search(
    query="liver",
    organism="1",
    tissue="3",
    technology="2",
    page=1,
    per_page=20,
)
print(f"Found {len(results)} datasets")
for ds in results:
    print(f"  {ds.accession}  {ds.title}  ({ds.download_count} downloads)")

List and download files

Each file in the listing includes a pre-signed download URL valid for 1 hour.

from stomics import StomicsClient

client = StomicsClient(api_key="sk-your-key")

# List files (includes pre-signed download URLs)
files = client.list_files("STD0001")
for f in files:
    size_mb = (f.size_bytes or 0) / 1_000_000
    print(f"  [{f.file_type:25s}]  {f.filename}  ({size_mb:.1f} MB)")

# Download a specific file with progress bar
matrix = next(f for f in files if f.file_type == "expression_matrix")
client.download_file("STD0001", matrix.id, f"./{matrix.filename}")

Fetch gene expression

Get per-spot expression values for a gene without downloading the full matrix.

from stomics import StomicsClient

client = StomicsClient()

# Fetch per-spot expression without downloading the full matrix
df = client.get_expression("STD0001", gene="BRCA1", sample_id="sample_1")
print(df.head())
#      x     y  expression
# 0   10    20        3.52
# 1   15    25        0.00

Method reference

Python	Description
`StomicsClient(api_key, base_url)`	Create an authenticated client
`client.search(query, organism, tissue, …)`	Search published datasets
`client.get_dataset(accession)`	Fetch dataset metadata
`client.list_files(accession)`	List files with pre-signed URLs
`client.download_file(accession, file_id, dest)`	Download a file to disk
`client.get_expression(accession, gene, sample_id)`	Per-spot expression values
`client.load_anndata(accession, sample_id)`	Load dataset as AnnData

The SDK wraps the Stomics REST API. See the API documentation for the underlying endpoints and parameters.