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 name (or by ID); client.list_vocabulary("tissue") lists the names
results = client.search(
    query="liver",
    organism="Homo sapiens",
    tissue="liver",
    technology="10x Visium",
    page=1,
    per_page=20,
)
print(f"Found {results.total} 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

Embeddings (UMAP / tSNE / PCA)

List, fetch, upload, or compute dimensionality reduction embeddings for a sample.

from stomics import StomicsClient

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

# List available embeddings for a sample
embeddings = client.list_embeddings("STD0001", sample_id=1)
for emb in embeddings:
    print(emb.method, emb.n_components)  # e.g. UMAP 2

# Fetch embedding coordinates
coords = client.get_embedding("STD0001", sample_id=1, embedding_id=embeddings[0].id)
print(f"{len(coords.spots)} spots in embedding")
# coords.spots[0] -> EmbeddingCoordinate(barcode="AAACAAGTATCTCCCA-1", dim_1=-2.3, dim_2=1.1, dim_3=None)

# Trigger server-side UMAP computation
result = client.compute_embedding("STD0001", sample_id=1)
print(result.embedding_id, result.status)  # e.g. 7 pending

# Upload pre-computed coordinates from CSV (barcode,UMAP_1,UMAP_2)
upload = client.upload_embedding("STD0001", sample_id=1, csv_path="umap_coords.csv")
print(f"Inserted {upload.inserted} spots (embedding {upload.embedding_id})")

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
`client.list_embeddings(accession, sample_id)`	List available embeddings
`client.get_embedding(accession, sample_id, embedding_id)`	Fetch embedding coordinates
`client.upload_embedding(accession, sample_id, csv_path)`	Upload CSV embedding coordinates
`client.compute_embedding(accession, sample_id)`	Trigger server-side UMAP computation
`client.get_embedding_compute_status(accession, sample_id)`	Poll computation status

The SDK wraps the Stomics REST API. See the API documentation for the underlying endpoints and parameters. To submit datasets programmatically, see the Programmatic Submission guide.