STAT is an AI agent for spatial transcriptomics. Ask in plain language, and STAT plans the analysis, picks a method, checks your data, runs the code, fixes errors and explains the result, next to an interactive tissue viewer.

Table of contents

• Installation
• Quick start
• Data format
• Built-in skills
• LLM providers
• Benchmarks and reproducibility
• License

Installation

Python 3.11, for example in a conda environment:

conda create -n stat python=3.11 && conda activate stat
pip install stat-agent
pip install "git+https://github.com/chenyhvvvv/STAT-agent.git"   # or the latest main from GitHub

The analysis skills' dependencies (squidpy, scvi-tools, torch, ...):

pip install "stat-agent[skills]"

Some skills need packages that are not on PyPI (STAGATE with PyG wheels matching your torch and CUDA build); see the skill's SKILL.md and its dependencies block.

Quick start

To try STAT without installing it, open the live demo at statagent.online.

Web interface

stat-web                    # http://localhost:8889
./start_web.sh              # also starts a Jupyter Lab alongside on 8890

1. Enter the path to your dataset directory (or a saved session directory).
2. Pick a provider, model and API key, then Test Connection.
3. Load the dataset and ask in the chat panel:
   • "Annotate cell types using the breast-cancer reference."
   • "Find spatially variable genes."
   • "Show CD8A expression in slice 1."
   • "Run RCTD deconvolution and overlay the dominant cell type."

The mode selector switches between interactive (questions pause the turn) and auto (questions are answered by policy and shown as assumptions you can override). The Changes drawer lists what each turn produced, what is stale and why.

Command line

export ANTHROPIC_API_KEY=...
stat-agent chat ./dataset --model anthropic/claude-sonnet-4-6           # REPL
stat-agent chat ./dataset --model anthropic/claude-sonnet-4-6 -m "annotate cell types" --mode auto
stat-agent session report ./logs/session_x --format html --out report.html
stat-agent skill validate --strict

Data format

STAT auto-detects your data layout. Place files in a single directory.

Single-slice

dataset/
├── tissue.h5ad          # Required: AnnData with x, y in obs
└── he.tif               # Optional: H&E image (pixel coords = cell coords)

Multi-slice

dataset/
├── tissue_slice_0.h5ad
├── he_slice_0.tif
├── tissue_slice_1.h5ad
└── he_slice_1.tif

Multi-omics (gene + protein)

dataset/
├── tissue.h5ad          # Gene expression
├── tissue_protein.h5ad  # Protein expression
├── he.tif
└── protein_CD3.tif

Coordinate convention. Cell coordinates (x, y) in adata.obs map directly to image pixel (x, y). No coordinate transformation. Note the array indexing swap: image array img[y, x] corresponds to cell (x, y).

Required AnnData fields: adata.obs['x'], adata.obs['y'], and the expression matrix adata.X. adata.obs['celltype'] is optional; annotation skills populate it.

Built-in skills

Skills are discovered from src/stat_agent/skills/<slug>/SKILL.md and from ~/.stat_agent/skills/ (user skills take precedence). Each skill carries an applicability contract (modalities, data level, slice count), prerequisites, declared inputs and outputs, and a templated code body. The catalogue:

Cell type annotation

Spot deconvolution

Spatial domains

Spatial statistics & niches

Differential expression & pathway

Cell-cell communication

Multi-slice integration

Slice alignment & registration

Trajectory inference

Adding a skill. See docs/adding-a-skill.md: scaffold with stat-agent skill new <slug>, fill in the contract, validate with stat-agent skill validate --strict.

LLM providers

Models are addressed as provider/model-id (a bare id infers the provider). In the web interface pick the provider and type the model id; on the command line export the key and pass --model or set STAT_MODEL.

The staged pipeline uses prompted JSON for structured outputs, so the prompts are identical across backbones and no tool calling is required. The benchmark runs replayed at statagent.online used Claude Sonnet 4.6 and DeepSeek V4.1 Flash at maximum reasoning effort.

Other settings: STAT_MODE (interactive or auto), STAT_HOME (default ~/.stat_agent, holds user skills and the RCTD reference cache), STAT_LOGS_DIR, STAT_EXEC_TIMEOUT, STAT_SKILL_PATHS.

Benchmarks and reproducibility

statagent.online has the records of all STAT runs on the single-turn and multi-turn queries (the single-query benchmark and SessionBench), each replayable step by step in STAT's interface, and a download link for the results of the other experiments. The colorectal cancer (CRC) demo records are in STAT-PaperRepro.

License

BSD-3-Clause © STAT contributors.