# Methods Reference

This page is the canonical human-readable reference for ChatSpatial tool names,
method names, common defaults, accepted values, and user-facing parameter
behavior. MCP clients expose the full schema for method-specific advanced
options.

ChatSpatial's public interface is a set of 20 schema-validated MCP tools. Those
tools orchestrate 65 spatial transcriptomics methods across 15 analytical
categories. In this page, **tool** means the MCP entry point you or an AI client
can call; **method** means an algorithm or analysis backend selected through a
parameter such as `method`, `analysis_type`, `plot_type`, or `subtype`.

---

## Quick Reference

| Category | Tools |
|----------|-------|
| Data | `load_data`, `preprocess_data`, `compute_embeddings`, `export_data`, `reload_data` |
| Spatial | `analyze_spatial_statistics`, `find_spatial_genes`, `identify_spatial_domains` |
| Cells | `annotate_cell_types`, `deconvolve_data`, `analyze_cell_communication` |
| Genes | `find_markers`, `compare_conditions`, `analyze_enrichment` |
| Dynamics | `analyze_velocity_data`, `analyze_trajectory_data`, `analyze_cnv` |
| Multi-sample | `integrate_samples`, `register_spatial_data` |
| Output | `visualize_data` |

---

## Data Management

### load_data

Load spatial transcriptomics data.

| Parameter | Type | Description |
|-----------|------|-------------|
| `data_path` | str | Path to file or folder |
| `data_type` | str | `visium`, `xenium`, `slide_seq`, `merfish`, `seqfish`, `generic` |
| `name` | str | Optional dataset name |

**Supported formats**: H5AD, 10X Visium folders, H5, MTX

---

### preprocess_data

Normalize, filter, and prepare data.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `normalization` | `pearson_residuals` | `log`, `sct`, `pearson_residuals`, `scvi`, `none` |
| `n_hvgs` | 2000 | Highly variable genes |
| `n_pcs` | 30 | Principal components |
| `n_neighbors` | 15 | Neighbor graph |
| `clustering_resolution` | 1.0 | Leiden clustering |
| `filter_genes_min_cells` | 3 | Min cells per gene |
| `filter_cells_min_genes` | 30 | Min genes per cell |
| `filter_mito_pct` | 20.0 | Max mitochondrial % |
| `scale` | False | Scale to unit variance before PCA |

**Advanced options**:

| Parameter | Default | Description |
|-----------|---------|-------------|
| `use_scrublet` | False | Enable doublet detection (for single-cell resolution data) |
| `normalize_target_sum` | None | Target counts per cell (None=median, 1e4=Visium, 1e6=MERFISH) |
| `remove_mito_genes` | True | Exclude mito genes from HVG |
| `batch_key` | `batch` | Batch column for batch-aware normalization |

---

### compute_embeddings

Compute dimensionality reduction and clustering.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `compute_pca` | True | Compute PCA |
| `compute_umap` | True | Compute UMAP |
| `compute_clustering` | True | Leiden clustering |
| `compute_spatial_neighbors` | True | Spatial graph |
| `n_pcs` | 30 | Principal components |
| `clustering_resolution` | 1.0 | Clustering resolution |
| `force` | False | Recompute if exists |

---

### export_data / reload_data

Export dataset for external scripts, reload after modifications.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `data_id` | required | Dataset ID |
| `path` | auto | Custom path (default: `~/.chatspatial/active/{data_id}.h5ad`) |

---

## Spatial Analysis

### analyze_spatial_statistics

Analyze spatial patterns and autocorrelation.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `analysis_type` | `neighborhood` | See types below |
| `cluster_key` | None | Required for group-based analyses |
| `genes` | None | Specific genes to analyze |
| `n_top_genes` | 20 | Top HVGs to analyze (if genes not specified) |
| `n_neighbors` | 8 | Spatial neighbors |

**Analysis types**:

| Type | Category | Requires cluster_key |
|------|----------|---------------------|
| `moran` | Gene | No |
| `local_moran` | Gene | No |
| `geary` | Gene | No |
| `getis_ord` | Gene | No |
| `bivariate_moran` | Gene | No |
| `neighborhood` | Group | Yes |
| `co_occurrence` | Group | Yes |
| `ripley` | Group | Yes |
| `join_count` | Group | Yes |
| `local_join_count` | Group | Yes |
| `centrality` | Network | Yes |
| `network_properties` | Network | Yes |
| `spatial_centrality` | Network | Yes |

---

### find_spatial_genes

Identify spatially variable genes.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `flashs` | `sparkx`, `flashs`, `spatialde` |
| `n_top_genes` | None | Top genes to return (None = all significant) |

---

### identify_spatial_domains

Find tissue domains and spatial niches.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `spagcn` | `spagcn`, `stagate`, `graphst`, `banksy`, `leiden`, `louvain` |
| `n_domains` | 7 | Expected number of domains |
| `resolution` | 0.5 | Clustering resolution |

---

## Cell Analysis

### annotate_cell_types

Assign cell types.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `tangram` | See methods below |
| `reference_data_id` | None | Reference dataset (for transfer methods) |
| `cell_type_key` | None | Cell type column in reference |
| `marker_genes` | None | Marker dict (for CellAssign) |
| `sctype_tissue` | None | scType tissue name, required unless custom markers are provided |
| `sctype_db_` | None | Local scType database path, or remote URL when explicitly allowed |
| `sctype_custom_markers` | None | Custom scType marker sets |
| `sctype_scaled` | True | Whether scType should treat the expression matrix as scaled |
| `sctype_allow_remote` | False | One-off opt-in to load scType remote R scripts and default marker database |
| `sctype_allow_runtime_r_install` | False | One-off opt-in to install missing R packages at runtime |

**scType remote resources**: by default, scType does not load remote R scripts or the remote default marker database. For one-off exploratory runs, pass `sctype_allow_remote=true`. For production or offline workflows, prefer local R scripts via `CHATSPATIAL_SCTYPE_R_DIR` and a local `sctype_db_` path.

```json
{
  "method": "sctype",
  "sctype_tissue": "Immune system",
  "sctype_allow_remote": true
}
```

**Methods**:

| Method | Requires Reference | Notes |
|--------|-------------------|-------|
| `tangram` | Yes | Spatial mapping |
| `scanvi` | Yes | Deep learning transfer |
| `cellassign` | No | Marker-based |
| `sctype` | No | Automatic (R) |
| `singler` | No | Reference-based (R) |
| `mllmcelltype` | No | LLM-based |

---

### deconvolve_data

Estimate cell type proportions per spot.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `flashdeconv` | See methods below |
| `reference_data_id` | required | Reference dataset |
| `cell_type_key` | required | Cell type column in reference |

**Methods**:

| Method | Speed | GPU | Notes |
|--------|-------|-----|-------|
| `flashdeconv` | Fast | No | Default, recommended |
| `cell2location` | Slow | Yes | High accuracy |
| `rctd` | Fast | No | R-based |
| `destvi` | Medium | Yes | scvi-tools |
| `stereoscope` | Slow | Yes | Alternative DL |
| `tangram` | Medium | Yes | Spatial mapping |
| `spotlight` | Fast | No | R-based |
| `card` | Fast | No | R-based, imputation |

---

### analyze_cell_communication

Analyze ligand-receptor interactions.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `fastccc` | `fastccc`, `liana`, `cellphonedb`, `cellchat_r` |
| `species` | required | `human`, `mouse`, `zebrafish` |
| `cell_type_key` | required | Cell type column |
| `liana_resource` | `consensus` | LR database (`mouseconsensus` for mouse) |

---

## Gene Analysis

### find_markers

Find differentially expressed genes.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `group_key` | required | Grouping column |
| `group1` | None | First group (None = each vs rest) |
| `group2` | None | Second group |
| `method` | `wilcoxon` | `wilcoxon`, `t-test`, `t-test_overestim_var`, `logreg`, `pydeseq2` |
| `n_top_genes` | 50 | Top genes per group |

---

### compare_conditions

Compare experimental conditions (pseudobulk DESeq2).

| Parameter | Default | Description |
|-----------|---------|-------------|
| `condition_key` | required | Condition column |
| `condition1` | required | Treatment group |
| `condition2` | required | Control group |
| `sample_key` | required | Sample/patient column |
| `cell_type_key` | None | Stratify by cell type |
| `n_top_genes` | 50 | Top DEGs |

---

### analyze_enrichment

Gene set enrichment analysis.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `species` | required | `human`, `mouse`, `zebrafish` |
| `method` | `spatial_enrichmap` | `spatial_enrichmap`, `pathway_gsea`, `pathway_ora`, `pathway_enrichr`, `pathway_ssgsea` |
| `gene_set_database` | `GO_Biological_Process` | See databases below |

**Databases**: `GO_Biological_Process`, `GO_Molecular_Function`, `GO_Cellular_Component`, `KEGG_Pathways`, `Reactome_Pathways`, `MSigDB_Hallmark`, `Cell_Type_Markers`

---

## Dynamics

### analyze_velocity_data

RNA velocity analysis.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `scvelo` | `scvelo`, `velovi` |
| `scvelo_mode` | `stochastic` | `deterministic`, `stochastic`, `dynamical` |

**Requires**: `spliced` and `unspliced` layers

---

### analyze_trajectory_data

Trajectory and pseudotime inference.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `cellrank` | `cellrank`, `palantir`, `dpt` |
| `root_cells` | None | Starting cells |

**Note**: CellRank requires velocity data

---

### analyze_cnv

Copy number variation detection.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `method` | `infercnvpy` | `infercnvpy`, `numbat` |
| `reference_key` | required | Cell type column |
| `reference_categories` | required | Normal cell types |

---

## Multi-Sample

### integrate_samples

Batch integration.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `data_ids` | required | List of dataset IDs |
| `method` | `harmony` | `harmony`, `bbknn`, `scanorama`, `scvi` |
| `batch_key` | `batch` | Batch column |

---

### register_spatial_data

Align spatial sections.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `source_id` | required | Source dataset |
| `target_id` | required | Target dataset |
| `method` | `paste` | `paste`, `stalign` |

---

## Visualization

### visualize_data

Create all plot types.

| Parameter | Default | Description |
|-----------|---------|-------------|
| `plot_type` | `feature` | See types below |
| `subtype` | None | Visualization variant |
| `feature` | None | Gene(s) or column to show |
| `basis` | `spatial` | `spatial`, `umap` |
| `cluster_key` | None | Grouping column |
| `colormap` | `coolwarm` | Color scheme |
| `dpi` | 300 | Resolution |
| `output_format` | `png` | `png`, `pdf`, `svg`, `eps`, `tiff`, `jpg` |

**Plot types and subtypes**:

| Type | Subtypes | Use |
|------|----------|-----|
| `feature` | — | Gene/metadata on spatial or UMAP |
| `expression` | `heatmap`, `violin`, `dotplot`, `correlation` | Aggregated expression |
| `deconvolution` | `spatial_multi`, `pie`, `dominant`, `diversity`, `umap`, `imputation` | Cell proportions |
| `communication` | `dotplot`, `tileplot`, `circle_plot` | LR interactions |
| `interaction` | — | Spatial LR pairs |
| `trajectory` | `pseudotime`, `circular`, `fate_map`, `gene_trends`, `fate_heatmap`, `palantir` | Pseudotime |
| `velocity` | `stream`, `phase`, `proportions`, `heatmap`, `paga` | RNA velocity |
| `statistics` | `neighborhood`, `co_occurrence`, `ripley`, `moran`, `centrality`, `getis_ord` | Spatial stats |
| `enrichment` | `barplot`, `dotplot` | Pathway results |
| `cnv` | `heatmap`, `spatial` | CNV results |
| `integration` | `batch`, `cluster`, `highlight` | Integration QC |

---

## GPU Acceleration

Set `use_gpu=True` for these methods:

| Category | Methods |
|----------|---------|
| Preprocessing | scVI normalization |
| Annotation | Tangram, scANVI |
| Deconvolution | Cell2location, DestVI, Stereoscope, Tangram |
| Domains | STAGATE, GraphST |
| Velocity | VeloVI |
| Integration | scVI |
| CNV | inferCNVpy |