stat-agent 0.1.26__tar.gz → 2.0.0__tar.gz

stat_agent-2.0.0/PKG-INFO

@@ -0,0 +1,335 @@
+Metadata-Version: 2.4
+Name: stat-agent
+Version: 2.0.0
+Summary: STAT: Spatial Transcriptomics Analytical agenT - AI-powered, provenance-aware spatial omics analysis
+Author-email: Yihang Chen <ychenlp@connect.ust.hk>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/chenyhvvvv/STAT-agent
+Project-URL: Repository, https://github.com/chenyhvvvv/STAT-agent
+Keywords: spatial transcriptomics,single-cell,agent,AI,bioinformatics,anndata,scanpy,langgraph
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: anndata>=0.10
+Requires-Dist: scipy>=1.10
+Requires-Dist: scanpy>=1.10
+Requires-Dist: geopandas>=0.14
+Requires-Dist: shapely>=2.0
+Requires-Dist: pillow>=9.0
+Requires-Dist: tifffile>=2022.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: langgraph<2,>=1.0
+Requires-Dist: langchain<2,>=1.0
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: langchain-openai<2,>=1.0
+Requires-Dist: langchain-anthropic<2,>=1.0
+Requires-Dist: langchain-google-genai>=2.0
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0
+Requires-Dist: starlette>=0.40
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: nbformat>=5.9
+Provides-Extra: loop
+Requires-Dist: deepagents<0.8,>=0.7.13; extra == "loop"
+Provides-Extra: research
+Requires-Dist: tavily-python>=0.5; extra == "research"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-timeout>=2.3; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: anyio>=4; extra == "dev"
+Provides-Extra: bench
+Requires-Dist: jsonschema>=4; extra == "bench"
+Requires-Dist: tabulate>=0.9; extra == "bench"
+Provides-Extra: skills
+Requires-Dist: squidpy>=1.2; extra == "skills"
+Requires-Dist: esda>=2.4.0; extra == "skills"
+Requires-Dist: gseapy>=1.0; extra == "skills"
+Requires-Dist: liana; extra == "skills"
+Requires-Dist: cellphonedb<6.0,>=5.0; extra == "skills"
+Requires-Dist: plotnine>=0.12; extra == "skills"
+Requires-Dist: harmonypy>=0.0.9; extra == "skills"
+Requires-Dist: bbknn>=1.5.0; extra == "skills"
+Requires-Dist: scanorama>=1.7.0; extra == "skills"
+Requires-Dist: scvi-tools<2.0,>=1.0; extra == "skills"
+Requires-Dist: tangram-sc>=1.0.0; extra == "skills"
+Requires-Dist: qpsolvers[osqp]>=4.0; extra == "skills"
+Requires-Dist: ray>=2.0; extra == "skills"
+Requires-Dist: flashdeconv>=0.1.0; extra == "skills"
+Requires-Dist: cell2location>=0.1.4; extra == "skills"
+Requires-Dist: palantir>=1.0.0; extra == "skills"
+Requires-Dist: NaiveDE>=0.1; extra == "skills"
+Requires-Dist: SpatialDE>=1.1; extra == "skills"
+Requires-Dist: scikit-misc>=0.5; extra == "skills"
+Requires-Dist: igraph<1.0,>=0.9; extra == "skills"
+Requires-Dist: torch>=2.0; extra == "skills"
+Requires-Dist: SpaGCN>=1.2.5; extra == "skills"
+Requires-Dist: GraphST>=1.1.0; extra == "skills"
+Requires-Dist: paste-bio>=1.0.0; extra == "skills"
+Requires-Dist: POT<0.9.5,>=0.9.0; extra == "skills"
+Requires-Dist: plotly>=5; extra == "skills"
+Requires-Dist: pynrrd>=1.0; extra == "skills"
+Dynamic: license-file
+
+<!-- BANNER -->
+
+<div align="center">
+
+# STAT — Spatial Transcriptomics Analytical agenT
+
+Ask in natural language, get a planned, verified, and executed analysis of spatial omics data.
+
+[![PyPI version](https://img.shields.io/pypi/v/stat-agent.svg?color=blue)](https://pypi.org/project/stat-agent/)
+[![bioRxiv](https://img.shields.io/badge/bioRxiv-10.64898%2F2026.05.01.722244-b31b1b.svg)](https://doi.org/10.64898/2026.05.01.722244)
+[![Demo](https://img.shields.io/badge/demo-statagent.online-2563eb.svg)](https://statagent.online/)
+
+</div>
+
+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](#installation)
+- [Quick start](#quick-start)
+- [Data format](#data-format)
+- [Built-in skills](#built-in-skills)
+- [LLM providers](#llm-providers)
+- [Benchmarks and reproducibility](#benchmarks-and-reproducibility)
+- [License](#license)
+
+## Installation
+
+Python 3.11 or newer.
+
+```bash
+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, ...):
+
+```bash
+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](https://statagent.online/).
+
+### Web interface
+
+```bash
+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
+
+```bash
+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
+```
+
+<details>
+<summary>A chat turn in the interface</summary>
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/chenyhvvvv/STAT-agent/main/demo_chat_turn.jpg">
+    <img src="https://raw.githubusercontent.com/chenyhvvvv/STAT-agent/main/demo_chat_turn.jpg" alt="STAT one chat-turn demo" width="500" />
+  </a>
+</p>
+
+</details>
+
+## Data format
+
+STAT auto-detects your data layout. Place files in a single directory.
+
+**Single-slice**
+
+```text
+dataset/
+├── tissue.h5ad          # Required: AnnData with x, y in obs
+└── he.tif               # Optional: H&E image (pixel coords = cell coords)
+```
+
+**Multi-slice**
+
+```text
+dataset/
+├── tissue_slice_0.h5ad
+├── he_slice_0.tif
+├── tissue_slice_1.h5ad
+└── he_slice_1.tif
+```
+
+**Multi-omics (gene + protein)**
+
+```text
+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:
+
+<!-- SKILLS-TABLE-START -->
+### Cell type annotation
+
+| Skill | Summary |
+| --- | --- |
+| [Cell Type Annotation with scANVI](src/stat_agent/skills/celltype-annotation-scANVI/SKILL.md) | Annotate cell types in spatial transcriptomics data using scANVI transfer learning from a reference scRNA-seq dataset. |
+| [Fast Cell Type Annotation (Clustering + LLM)](src/stat_agent/skills/celltype-annotation-GPT/SKILL.md) | Annotate cell types using unsupervised clustering, marker genes, and LLM-based annotation. |
+| [Cell Type Annotation via Spatial Mapping (Tangram)](src/stat_agent/skills/annotation-tangram/SKILL.md) | Map single-cell reference annotations onto spatial transcriptomics data using Tangram deep learning alignment. |
+
+### Spot deconvolution
+
+| Skill | Summary |
+| --- | --- |
+| [Cell Type Deconvolution (RCTD)](src/stat_agent/skills/celltype-deconvolution-RCTD/SKILL.md) | Perform cell type deconvolution (or annotation on spot) on spatial transcriptomics data (Visium spots) using RCTD with a single-cell refere… |
+| [Bayesian Cell Type Deconvolution (Cell2location)](src/stat_agent/skills/deconvolution-cell2location/SKILL.md) | Reference-based Bayesian deconvolution of spot-level spatial transcriptomics using Cell2location. |
+| [Fast Spot Deconvolution (FlashDeconv)](src/stat_agent/skills/deconvolution-flashdeconv/SKILL.md) | Ultra-fast reference-based cell type deconvolution for spot-level spatial data using FlashDeconv. |
+
+### Spatial domains
+
+| Skill | Summary |
+| --- | --- |
+| [Spatial Domain Detection (SpaGCN)](src/stat_agent/skills/spatial-domain-SpaGCN/SKILL.md) | Identify spatial domains in spot-level spatial transcriptomics data using SpaGCN, integrating gene expression, spatial location, and H&E hi… |
+| [Spatial Domain Detection (STAGATE)](src/stat_agent/skills/spatial-domain-STAGATE/SKILL.md) | Identify spatial domains using STAGATE (Spatial-Transcriptomics Graph Attention Auto-Encoder). |
+| [Spatial Domain Detection (GraphST)](src/stat_agent/skills/spatial-domain-GraphST/SKILL.md) | Identify spatial domains in spot-level data using GraphST (Graph Self-supervised Transformer). |
+
+### Spatial statistics & niches
+
+| Skill | Summary |
+| --- | --- |
+| [Spatial Statistics Analysis](src/stat_agent/skills/spatial-statistics-squidpy/SKILL.md) | Compute spatial statistics including Moran's I (spatial autocorrelation of genes), Ripley's K (spatial point pattern of cell types), co-occ… |
+| [Neighborhood Enrichment Analysis](src/stat_agent/skills/spatial-stats-neighborhood-enrichment/SKILL.md) | Compute neighborhood enrichment z-scores to identify which cell types are spatially co-localized or depleted from each other's neighborhood… |
+| [Spatial Niche Detection](src/stat_agent/skills/niche-detection-Harmonics/SKILL.md) | Identify spatial cellular niches using Harmonics hierarchical model. |
+| [Spatially Variable Genes (SpatialDE)](src/stat_agent/skills/svg-SpatialDE/SKILL.md) | Identify spatially variable genes using SpatialDE Gaussian process regression. |
+
+### Differential expression & pathway
+
+| Skill | Summary |
+| --- | --- |
+| [Differential Gene Expression Analysis](src/stat_agent/skills/differential-expression/SKILL.md) | Find differentially expressed marker genes between groups using scanpy rank_genes_groups with Wilcoxon test. |
+| [GO Enrichment Analysis](src/stat_agent/skills/pathway-GO-enrichment/SKILL.md) | Find enriched Gene Ontology (GO) terms for a user-provided gene list. |
+| [Over-Representation & Pathway Enrichment Analysis (ORA)](src/stat_agent/skills/enrichment-ora-ssgsea/SKILL.md) | Test whether a gene list is enriched for specific pathways or gene sets using Over-Representation Analysis (Fisher's exact test). |
+| [Per-Cell Pathway Activity Scoring (ssGSEA)](src/stat_agent/skills/pathway-ssgsea/SKILL.md) | Compute per-cell pathway activity scores using single-sample Gene Set Enrichment Analysis (ssGSEA). |
+| [Two-Group Pathway Enrichment Comparison](src/stat_agent/skills/pathway-enrichment-compare/SKILL.md) | Compare pathway / gene-set enrichment between two user-provided gene lists (typically markers of two cell populations, clusters, or conditi… |
+
+### Cell-cell communication
+
+| Skill | Summary |
+| --- | --- |
+| [Cell-Cell Communication Analysis (LIANA+)](src/stat_agent/skills/cell-communication-LIANA/SKILL.md) | Analyze cell-cell communication using LIANA+ to identify significant ligand-receptor interactions between cell types. |
+| [Cell-Cell Communication Analysis (CellPhoneDB)](src/stat_agent/skills/cell-communication-CellPhoneDB/SKILL.md) | Analyze cell-cell communication using CellPhoneDB statistical method to identify significant ligand-receptor interactions between cell type… |
+
+### Multi-slice integration
+
+| Skill | Summary |
+| --- | --- |
+| [Batch Integration (Harmony)](src/stat_agent/skills/integration-Harmony/SKILL.md) | Integrate multiple spatial transcriptomics slices using Harmony batch correction. |
+| [Batch Integration (BBKNN)](src/stat_agent/skills/integration-bbknn/SKILL.md) | Correct batch effects across multiple slices using BBKNN (Batch Balanced K-Nearest Neighbors). |
+| [Batch Integration (Scanorama)](src/stat_agent/skills/integration-scanorama/SKILL.md) | Correct batch effects across multiple slices using Scanorama panoramic stitching. |
+
+### Slice alignment & registration
+
+| Skill | Summary |
+| --- | --- |
+| [Spatial Alignment (STalign)](src/stat_agent/skills/alignment-STalign/SKILL.md) | Align two cell-level spatial transcriptomics slices using STalign. |
+| [Slice Registration (PASTE)](src/stat_agent/skills/registration-paste/SKILL.md) | Align multiple spatial transcriptomics slices using PASTE (Probabilistic Alignment of ST Experiments). |
+
+### Trajectory inference
+
+| Skill | Summary |
+| --- | --- |
+| [Pseudotime Trajectory Analysis (Palantir / DPT)](src/stat_agent/skills/trajectory-palantir-dpt/SKILL.md) | Infer cell developmental trajectories and pseudotime ordering using expression-based methods. |
+
+<!-- SKILLS-TABLE-END -->
+
+**Adding a skill.** See [docs/adding-a-skill.md](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`.
+
+| Provider | Env var | Example |
+| --- | --- | --- |
+| OpenAI | `OPENAI_API_KEY` | `openai/gpt-5.4`, `openai/gpt-4o` |
+| Anthropic | `ANTHROPIC_API_KEY` | `anthropic/claude-opus-4-7`, `anthropic/claude-sonnet-4-6` |
+| Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `google/gemini-3.1-pro-preview`, `google/gemini-2.5-pro` |
+| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek/deepseek-flash` |
+| Poe (gateway) | `POE_API_KEY` | `poe/claude-sonnet-4.5`, `poe/gpt-5.5` |
+| xAI | `XAI_API_KEY` | `xai/grok-4` |
+| Moonshot | `MOONSHOT_API_KEY` | `moonshot/kimi-k2` |
+| Zhipu | `ZHIPU_API_KEY` | `zhipu/glm-4.5` |
+| DashScope | `DASHSCOPE_API_KEY` | `dashscope/qwen3-max` |
+| Any OpenAI-compatible endpoint | `STAT_API_KEY` | `custom/<model>`, with the endpoint in the web interface's *Base URL* field |
+
+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](https://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](https://github.com/chenyhvvvv/STAT-PaperRepro).
+
+## License
+
+[BSD-3-Clause](LICENSE) © STAT contributors.

stat_agent-2.0.0/README.md

@@ -0,0 +1,248 @@
+<!-- BANNER -->
+
+<div align="center">
+
+# STAT — Spatial Transcriptomics Analytical agenT
+
+Ask in natural language, get a planned, verified, and executed analysis of spatial omics data.
+
+[![PyPI version](https://img.shields.io/pypi/v/stat-agent.svg?color=blue)](https://pypi.org/project/stat-agent/)
+[![bioRxiv](https://img.shields.io/badge/bioRxiv-10.64898%2F2026.05.01.722244-b31b1b.svg)](https://doi.org/10.64898/2026.05.01.722244)
+[![Demo](https://img.shields.io/badge/demo-statagent.online-2563eb.svg)](https://statagent.online/)
+
+</div>
+
+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](#installation)
+- [Quick start](#quick-start)
+- [Data format](#data-format)
+- [Built-in skills](#built-in-skills)
+- [LLM providers](#llm-providers)
+- [Benchmarks and reproducibility](#benchmarks-and-reproducibility)
+- [License](#license)
+
+## Installation
+
+Python 3.11 or newer.
+
+```bash
+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, ...):
+
+```bash
+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](https://statagent.online/).
+
+### Web interface
+
+```bash
+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
+
+```bash
+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
+```
+
+<details>
+<summary>A chat turn in the interface</summary>
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/chenyhvvvv/STAT-agent/main/demo_chat_turn.jpg">
+    <img src="https://raw.githubusercontent.com/chenyhvvvv/STAT-agent/main/demo_chat_turn.jpg" alt="STAT one chat-turn demo" width="500" />
+  </a>
+</p>
+
+</details>
+
+## Data format
+
+STAT auto-detects your data layout. Place files in a single directory.
+
+**Single-slice**
+
+```text
+dataset/
+├── tissue.h5ad          # Required: AnnData with x, y in obs
+└── he.tif               # Optional: H&E image (pixel coords = cell coords)
+```
+
+**Multi-slice**
+
+```text
+dataset/
+├── tissue_slice_0.h5ad
+├── he_slice_0.tif
+├── tissue_slice_1.h5ad
+└── he_slice_1.tif
+```
+
+**Multi-omics (gene + protein)**
+
+```text
+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:
+
+<!-- SKILLS-TABLE-START -->
+### Cell type annotation
+
+| Skill | Summary |
+| --- | --- |
+| [Cell Type Annotation with scANVI](src/stat_agent/skills/celltype-annotation-scANVI/SKILL.md) | Annotate cell types in spatial transcriptomics data using scANVI transfer learning from a reference scRNA-seq dataset. |
+| [Fast Cell Type Annotation (Clustering + LLM)](src/stat_agent/skills/celltype-annotation-GPT/SKILL.md) | Annotate cell types using unsupervised clustering, marker genes, and LLM-based annotation. |
+| [Cell Type Annotation via Spatial Mapping (Tangram)](src/stat_agent/skills/annotation-tangram/SKILL.md) | Map single-cell reference annotations onto spatial transcriptomics data using Tangram deep learning alignment. |
+
+### Spot deconvolution
+
+| Skill | Summary |
+| --- | --- |
+| [Cell Type Deconvolution (RCTD)](src/stat_agent/skills/celltype-deconvolution-RCTD/SKILL.md) | Perform cell type deconvolution (or annotation on spot) on spatial transcriptomics data (Visium spots) using RCTD with a single-cell refere… |
+| [Bayesian Cell Type Deconvolution (Cell2location)](src/stat_agent/skills/deconvolution-cell2location/SKILL.md) | Reference-based Bayesian deconvolution of spot-level spatial transcriptomics using Cell2location. |
+| [Fast Spot Deconvolution (FlashDeconv)](src/stat_agent/skills/deconvolution-flashdeconv/SKILL.md) | Ultra-fast reference-based cell type deconvolution for spot-level spatial data using FlashDeconv. |
+
+### Spatial domains
+
+| Skill | Summary |
+| --- | --- |
+| [Spatial Domain Detection (SpaGCN)](src/stat_agent/skills/spatial-domain-SpaGCN/SKILL.md) | Identify spatial domains in spot-level spatial transcriptomics data using SpaGCN, integrating gene expression, spatial location, and H&E hi… |
+| [Spatial Domain Detection (STAGATE)](src/stat_agent/skills/spatial-domain-STAGATE/SKILL.md) | Identify spatial domains using STAGATE (Spatial-Transcriptomics Graph Attention Auto-Encoder). |
+| [Spatial Domain Detection (GraphST)](src/stat_agent/skills/spatial-domain-GraphST/SKILL.md) | Identify spatial domains in spot-level data using GraphST (Graph Self-supervised Transformer). |
+
+### Spatial statistics & niches
+
+| Skill | Summary |
+| --- | --- |
+| [Spatial Statistics Analysis](src/stat_agent/skills/spatial-statistics-squidpy/SKILL.md) | Compute spatial statistics including Moran's I (spatial autocorrelation of genes), Ripley's K (spatial point pattern of cell types), co-occ… |
+| [Neighborhood Enrichment Analysis](src/stat_agent/skills/spatial-stats-neighborhood-enrichment/SKILL.md) | Compute neighborhood enrichment z-scores to identify which cell types are spatially co-localized or depleted from each other's neighborhood… |
+| [Spatial Niche Detection](src/stat_agent/skills/niche-detection-Harmonics/SKILL.md) | Identify spatial cellular niches using Harmonics hierarchical model. |
+| [Spatially Variable Genes (SpatialDE)](src/stat_agent/skills/svg-SpatialDE/SKILL.md) | Identify spatially variable genes using SpatialDE Gaussian process regression. |
+
+### Differential expression & pathway
+
+| Skill | Summary |
+| --- | --- |
+| [Differential Gene Expression Analysis](src/stat_agent/skills/differential-expression/SKILL.md) | Find differentially expressed marker genes between groups using scanpy rank_genes_groups with Wilcoxon test. |
+| [GO Enrichment Analysis](src/stat_agent/skills/pathway-GO-enrichment/SKILL.md) | Find enriched Gene Ontology (GO) terms for a user-provided gene list. |
+| [Over-Representation & Pathway Enrichment Analysis (ORA)](src/stat_agent/skills/enrichment-ora-ssgsea/SKILL.md) | Test whether a gene list is enriched for specific pathways or gene sets using Over-Representation Analysis (Fisher's exact test). |
+| [Per-Cell Pathway Activity Scoring (ssGSEA)](src/stat_agent/skills/pathway-ssgsea/SKILL.md) | Compute per-cell pathway activity scores using single-sample Gene Set Enrichment Analysis (ssGSEA). |
+| [Two-Group Pathway Enrichment Comparison](src/stat_agent/skills/pathway-enrichment-compare/SKILL.md) | Compare pathway / gene-set enrichment between two user-provided gene lists (typically markers of two cell populations, clusters, or conditi… |
+
+### Cell-cell communication
+
+| Skill | Summary |
+| --- | --- |
+| [Cell-Cell Communication Analysis (LIANA+)](src/stat_agent/skills/cell-communication-LIANA/SKILL.md) | Analyze cell-cell communication using LIANA+ to identify significant ligand-receptor interactions between cell types. |
+| [Cell-Cell Communication Analysis (CellPhoneDB)](src/stat_agent/skills/cell-communication-CellPhoneDB/SKILL.md) | Analyze cell-cell communication using CellPhoneDB statistical method to identify significant ligand-receptor interactions between cell type… |
+
+### Multi-slice integration
+
+| Skill | Summary |
+| --- | --- |
+| [Batch Integration (Harmony)](src/stat_agent/skills/integration-Harmony/SKILL.md) | Integrate multiple spatial transcriptomics slices using Harmony batch correction. |
+| [Batch Integration (BBKNN)](src/stat_agent/skills/integration-bbknn/SKILL.md) | Correct batch effects across multiple slices using BBKNN (Batch Balanced K-Nearest Neighbors). |
+| [Batch Integration (Scanorama)](src/stat_agent/skills/integration-scanorama/SKILL.md) | Correct batch effects across multiple slices using Scanorama panoramic stitching. |
+
+### Slice alignment & registration
+
+| Skill | Summary |
+| --- | --- |
+| [Spatial Alignment (STalign)](src/stat_agent/skills/alignment-STalign/SKILL.md) | Align two cell-level spatial transcriptomics slices using STalign. |
+| [Slice Registration (PASTE)](src/stat_agent/skills/registration-paste/SKILL.md) | Align multiple spatial transcriptomics slices using PASTE (Probabilistic Alignment of ST Experiments). |
+
+### Trajectory inference
+
+| Skill | Summary |
+| --- | --- |
+| [Pseudotime Trajectory Analysis (Palantir / DPT)](src/stat_agent/skills/trajectory-palantir-dpt/SKILL.md) | Infer cell developmental trajectories and pseudotime ordering using expression-based methods. |
+
+<!-- SKILLS-TABLE-END -->
+
+**Adding a skill.** See [docs/adding-a-skill.md](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`.
+
+| Provider | Env var | Example |
+| --- | --- | --- |
+| OpenAI | `OPENAI_API_KEY` | `openai/gpt-5.4`, `openai/gpt-4o` |
+| Anthropic | `ANTHROPIC_API_KEY` | `anthropic/claude-opus-4-7`, `anthropic/claude-sonnet-4-6` |
+| Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | `google/gemini-3.1-pro-preview`, `google/gemini-2.5-pro` |
+| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek/deepseek-flash` |
+| Poe (gateway) | `POE_API_KEY` | `poe/claude-sonnet-4.5`, `poe/gpt-5.5` |
+| xAI | `XAI_API_KEY` | `xai/grok-4` |
+| Moonshot | `MOONSHOT_API_KEY` | `moonshot/kimi-k2` |
+| Zhipu | `ZHIPU_API_KEY` | `zhipu/glm-4.5` |
+| DashScope | `DASHSCOPE_API_KEY` | `dashscope/qwen3-max` |
+| Any OpenAI-compatible endpoint | `STAT_API_KEY` | `custom/<model>`, with the endpoint in the web interface's *Base URL* field |
+
+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](https://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](https://github.com/chenyhvvvv/STAT-PaperRepro).
+
+## License
+
+[BSD-3-Clause](LICENSE) © STAT contributors.