Table of contents

• Installation
• Quick start
• Data format
• Built-in skills
• LLM providers
• Reproducing the paper
• License

Installation

Stable release from PyPI:

pip install stat-agent

With the full set of analysis skill dependencies (squidpy, scvi-tools, torch, liana, cell2location, …):

pip install "stat-agent[skills]"

Some skills require packages that aren't on PyPI; install separately as needed:

# STAGATE (requires PyG ecosystem wheels matching your torch + CUDA version)
pip install torch_geometric
pip install torch_sparse torch_scatter -f https://data.pyg.org/whl/torch-${TORCH_VER}+${CUDA_VER}.html
pip install git+https://github.com/QIFEIDKN/STAGATE_pyG.git

(Replace ${TORCH_VER} and ${CUDA_VER} with your installed torch/CUDA — e.g. 2.4.1+cu121.)

GPU note: the torch and CUDA versions should be adjusted to match your hardware. See pytorch.org.

Quick start

Web interface

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

In the UI:

1. Enter the path to your dataset directory.
2. Configure your LLM provider and paste an API key.
3. Click Load Dataset.
4. Ask questions 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."

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 will populate it.

Built-in skills

Skills are auto-discovered from stat_agent/skills/{slug}/SKILL.md. Each skill carries metadata (modalities, data level, prerequisites) and a templated code body. The current catalog:

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 new skill. Create stat_agent/skills/<your-slug>/SKILL.md with YAML frontmatter (name, title, description, filter_requirements, prerequisites, optional default_skill), then write the analysis instructions and code template in the body. The registry will pick it up at startup.

LLM providers

STAT supports five providers via a unified LLMBackend. In the web UI's Configure LLM panel, pick a Provider from the dropdown, then type the bare Model ID as it appears at that provider's API — no prefix needed. (Older saved configs that include a prefix like anthropic/… still work for backward compatibility.)

For programmatic use, export the corresponding environment variable before launching stat-web. Every model ID below has been verified end-to-end against the live provider API.

Poe caveat. claude-opus-4.6 and claude-sonnet-4.6 on Poe force extended-thinking on the bot side and are not yet supported through STAT — use claude-opus-4.7 instead, or switch to the direct Anthropic provider.

Tip. For long-context analysis (multi-slice integration, large reference profiles), prefer models with 200 k+ context: claude-opus-4-7, claude-opus-4-6, gpt-5.5, gemini-3.1-pro-preview.

Verify before a long run. Use the Test Connection button in the Configure LLM panel — it sends a one-token round-trip through the same LLMBackend code path as the agent and reports the exact error if anything is off.

Reproducing the paper

The analyses, figures, and benchmarks from the STAT paper live in a separate repository: https://github.com/chenyhvvvv/STAT-PaperRepro

License

BSD-3-Clause © STAT contributors.