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 66 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
`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

PCA, neighbor, UMAP, and clustering parameters belong to compute_embeddings; preprocess_data does not accept or retain them.

preprocess_data does not compute PCA, UMAP, clustering, or neighbor graphs. Call compute_embeddings explicitly before cluster- or embedding-dependent tools.

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)
`max_genes_tested`	None	Optional runtime cap applied after filters; keeps the highest-expressed genes for testing
`test_only_hvg`	True	Restrict testing to highly variable genes
`filter_mt_genes`	True	Exclude mitochondrial genes before testing
`filter_ribo_genes`	False	Exclude ribosomal genes before testing

n_top_genes limits the ranked result returned to the caller; max_genes_tested limits the genes supplied to the statistical backend. Use the latter to bound SpatialDE runtime without changing the meaning of the output limit. FlashS is the default Python-native backend and is part of the standard installation; SpatialDE is installed with chatspatial[spatial-genes].

identify_spatial_domains¶

Find tissue domains and spatial niches.

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

SpaGCN, STAGATE, and AESTETIK kmeans/bgm use n_domains. BANKSY and the Leiden/Louvain paths are resolution-driven; adjust banksy_cluster_resolution or resolution instead of expecting an exact domain count. GraphST may use graphst_n_clusters when an explicit count is required. GraphST and STAGATE publish their reusable embeddings as X_graphst and X_stagate in adata.obsm. The legacy Louvain choice is retained for compatibility and falls back to Leiden when the obsolete Louvain extension is unavailable.

AESTETIK fuses a precomputed expression embedding, a precomputed per-spot morphology embedding, and the spatial neighborhood grid. It reads both representations from adata.obsm and does not extract morphology features from tissue images. It also needs discrete lattice coordinates in adata.obs, either x_array/y_array or the Visium array_row/array_col columns.

Parameter	Default	Description
`aestetik_transcriptomics_key`	`X_pca`	obsm key with the expression embedding
`aestetik_morphology_key`	`X_pca_morphology`	obsm key with the morphology embedding
`aestetik_morphology_weight`	1.5	Morphology weight in the joint loss
`aestetik_window_size`	3	Odd side length of the neighborhood grid
`aestetik_clustering_method`	`kmeans`	`bgm`, `kmeans`, `louvain`, `leiden`. `kmeans`/`bgm` use `n_domains`; `leiden`/`louvain` use `resolution`
`aestetik_latent_dim`	16	Latent embedding dimension
`aestetik_max_epochs`	100	Training epochs
`aestetik_random_seed`	2023	Random seed

Install with pip install 'chatspatial[aestetik]' (Python < 3.14). Method reference: Representation learning for multi-modal spatially resolved transcriptomics data, Bioinformatics (2026).

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.

{
  "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`	Variable	Optional	R/spacexr by default; CUDA-oriented rctd-py backend
`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

RCTD backend options:

Parameter	Default	Description
`rctd_backend`	`r`	`r` for spacexr or `python` for rctd-py
`rctd_mode`	`full`	`full`, `doublet`, or `multi`
`rctd_device`	`auto`	`auto`, `cpu`, or `cuda`; Python backend only
`rctd_batch_size`	`auto`	Automatic or positive spot batch size; Python backend only
`rctd_dtype`	`float64`	`float64` for parity or `float32` to reduce GPU memory; Python backend only
`rctd_sigma_override`	None	Fix sigma instead of estimating it; Python backend only
`rctd_max_cores`	4	Worker limit; R backend only

Install the Python backend with uv pip install 'chatspatial[rctd-python]'. It preserves the main deconvolution_rctd result contract and also stores mode-specific annotations such as rctd_status, rctd_converged, and doublet/multi outputs. The first run downloads an approximately 400 MB likelihood table to ~/.cache/rctd. Use rctd-py primarily on CUDA systems. CPU cold starts can be slower than spacexr because PyTorch compilation fallback and sigma calibration dominate small runs; rctd_sigma_override skips calibration but not compilation startup.

analyze_cell_communication¶

Analyze ligand-receptor interactions.

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

LIANA is the portable default and supports human, mouse, and zebrafish. FastCCC and CellPhoneDB currently require human data. Install LIANA and CellPhoneDB with chatspatial[cell-communication], FastCCC with chatspatial[fastccc], or all three through chatspatial[full]. The maintained FastCCC runtime is composable with trajectory; it does not include the unused HTML report layer or depend on Jinja2.

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

Results are grouped per comparison rather than flattened across groups. Each row reports both groups’ mean expression alongside the fold change, so effect size can be interpreted in expression context.

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
`cellrank_n_states`	5	Number of CellRank macrostates
`cellrank_stability_threshold`	0.96	Minimum stability for a macrostate to count as terminal

Note: CellRank requires velocity data and Python 3.12 or newer. When no state reaches cellrank_stability_threshold, ChatSpatial falls back to macrostate-based pseudotime and returns a warning. Palantir and DPT do not need velocity; if root_cells is omitted, the automatically selected root and any unreachable cells are reported in the tool warnings.

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	Two or more distinct 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; must differ from `target_id`
`target_id`	required	Target dataset; must differ from `source_id`
`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 for continuous values. Categorical features automatically use a qualitative palette such as `tab10` or `tab20`.
`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; heatmaps scale per gene by default
`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¶

GPU acceleration is available for these methods. Most use use_gpu=True; the rctd-py backend instead uses rctd_device="cuda":

Category	Methods
Preprocessing	scVI normalization
Annotation	Tangram, scANVI
Deconvolution	Cell2location, DestVI, Stereoscope, Tangram, RCTD (rctd-py backend)
Domains	STAGATE, GraphST
Velocity	VeloVI
Integration	scVI
CNV	inferCNVpy