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 67 spatial transcriptomics methods across 13 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

Mitochondrial QC uses a boolean adata.var["mt"] annotation when supplied, including for Ensembl identifiers. Without annotations, gene symbols beginning with MT- or MT. are recognized case-insensitively. Gene identifiers are not renamed. The same annotations govern HVG exclusion and spatial-gene filtering; raw-layer annotations cover genes absent from the active matrix.

If no mitochondrial genes are identified, mitochondrial percentages are unavailable, not zero. Requested mitochondrial filtering is skipped with a warning. The result reports n_mt_genes, mito_annotation_source, mito_qc_available, and mito_filter_applied; unavailable percentage summaries are omitted. Supply a boolean annotation before saving/loading the input H5AD, or disable mitochondrial filtering for panels without mitochondrial genes.

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)
`gene_selection`	`hvg`	`hvg` (top `n_top_genes` HVGs) or `all` (every gene; `moran` and `geary` only)
`n_neighbors`	8	Spatial neighbors

With gene_selection="all", Moran’s I or Geary’s C is computed for every gene of the expression matrix. The result returns the top genes only; the full per-gene table (I or C, pval_norm, FDR pval_norm_fdr, and rank, 1 = strongest autocorrelation) is stored in adata.uns[results_key] (moranI or gearyC) and exported with the dataset.

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_compat`	`spagcn-1.2.7`	SpaGCN behavior: `spagcn-1.2.7` or `modern`

SpaGCN runs in spagcn-1.2.7 mode by default and reproduces the labels of the published SpaGCN 1.2.7 implementation, whose cluster centers stay fixed during training. modern trains the centers with the DEC Student’s t kernel; the SpaGCN hyperparameters were tuned for 1.2.7, so this mode gives different domains.

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	Label -> marker genes (for CellAssign and marker_score)
`cluster_label`	None	Cluster or domain column (for mLLMCellType and marker_score)
`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
`marker_score`	No	Labels groups of `cluster_label` by marker-gene scores
`threshold`	No	Labels observations by a cutoff on a numeric obs column

marker_score: for each label of marker_genes, in the given order, every group of cluster_label is scored by the mean log-normalized expression (log1p of counts scaled to 10,000 per observation) of the label’s marker genes present in the data. Absent markers are skipped with a warning; a label with no marker present is an error. The marker_score_n_top (default 2) highest-scoring groups receive the label. With marker_score_exclusion="rank_then_drop" (default) groups already labeled are dropped from that top list, so a label can receive fewer groups; with "drop_then_rank" they are removed before ranking. Other groups receive marker_score_unassigned_label (default Other). The result reports group_labels, group_scores and markers_used, and the score table is stored in adata.uns["<output_key>_group_scores"].

{
  "method": "marker_score",
  "cluster_label": "spatial_domains_leiden",
  "marker_genes": {
    "TC": ["KRT14", "KRT5", "MKI67", "PCNA", "TOP2A"],
    "LE": ["VIM", "FN1", "COL1A1", "COL1A2", "SPARC", "TGFBI"]
  },
  "output_key": "tc_le_region"
}

threshold: labels each observation threshold_pass_label (default pass) when <value> <threshold_comparison> threshold_value holds and threshold_fail_label (default fail) otherwise; observations without a value stay unlabeled. deconvolve_data writes one proportion column per cell type, deconvolution_<method>_<cell type>, which can be thresholded directly.

{
  "method": "threshold",
  "threshold_key": "deconvolution_rctd_Tumor_cells",
  "threshold_value": 0.15,
  "threshold_comparison": ">=",
  "threshold_pass_label": "tumor_enriched",
  "threshold_fail_label": "low_tumor",
  "output_key": "tumor_class"
}

Both methods write their labels to output_key (default cell_type_marker_score or cell_type_threshold).

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

FlashDeconv uses deterministic gene weighting and automatically scales spatial regularization to the data. Set flashdeconv_lambda_spatial to a non-negative number to choose the strength explicitly (0 disables smoothing). flashdeconv_sketch_dim controls the expected gene weights, not a projected embedding dimension. Results report the backend version, resolved regularization, selected gene count, and solver convergence.

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)
`subset_key`	None	obs column that restricts the analysis to some observations
`subset_categories`	None	Values of `subset_key` to keep (set with `subset_key`)

subset_key and subset_categories run every method on the selected observations only, for example the tumor-core and leading-edge spots of pooled sections labeled by their dominant deconvolved cell type:

{
  "method": "cellchat_r",
  "species": "human",
  "cell_type_key": "dominant_celltype_flashdeconv",
  "subset_key": "tc_le_region",
  "subset_categories": ["TC", "LE"]
}

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
`exclude_gene_classes`	`[]`	Any of `immunoglobulin`, `ribosomal`, `mitochondrial`, `hla`
`exclude_gene_patterns`	`[]`	Gene-name wildcards removed before testing, e.g. `MALAT1`

Excluded genes are removed before ranking, so they are never reported as markers; the result reports how many genes each class or pattern removed. The class rules are the same as for analyze_cnv.

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
`gene_positions`	`auto`	`provided` (adata.var), `annotate` (bundled table), `auto` (provided if present, else annotate)
`species`	`human`	`human` (GRCh38) or `mouse` (GRCm39) table for `annotate`
`exclude_gene_classes`	`[]`	Any of `immunoglobulin`, `ribosomal`, `mitochondrial`, `hla`
`exclude_gene_patterns`	`[]`	Gene-name wildcards removed from the CNV input, e.g. `IGH*`
`cluster_cells`	False	Leiden clustering of the CNV profiles
`query_categories`	None	Categories of `reference_key` to cluster; others get no cluster label

Gene positions: infercnvpy needs the chromosome, start and end of every gene. When adata.var lacks them, ChatSpatial annotates them from bundled Ensembl release 110 tables (GRCh38 or GRCm39, chromosomes 1-22/1-19, X and Y; the annotation behind the 10x Genomics 2024-A references). Genes are matched on the Ensembl gene ID when adata.var holds one (gene_ids, gene_id, ensembl_id, ensembl_gene_id, or Ensembl IDs as gene names), and the rest on the gene symbol. The result reports how many genes matched each way, and the positions are written to adata.var.

Gene exclusion: excluded genes are removed from the CNV input only; the dataset keeps them. Class rules match gene names case-insensitively: immunoglobulin covers the V, D, J and constant segments of the IGH, IGK and IGL loci (IG[HKL][VDJC]*, IGH[AGMDE]*, except IGHMBP2), JCHAIN, IGLL1 and IGLL5; ribosomal covers RPL* and RPS* except RPS6K* and RPS19BP1; mitochondrial covers MT-*; hla covers HLA-* and mouse H2-*.

Query clustering: inference always uses every observation with reference_categories as the baseline. With query_categories, only those observations are clustered, so tumor clones are not mixed with the reference.

{
  "reference_key": "tumor_class",
  "reference_categories": ["low_tumor"],
  "exclude_gene_classes": ["immunoglobulin", "ribosomal", "mitochondrial", "hla"],
  "cluster_cells": true,
  "query_categories": ["tumor_enriched"]
}

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
`batch_correction`	True	False concatenates the samples without correction

With batch_correction=false, the samples are pooled without batch correction and need not be preprocessed: the pooled dataset keeps the genes present in every sample, their counts in layers["counts"] (from each sample’s layers["counts"], else X; adata.raw only when neither holds counts), X = log1p of the counts scaled to 10,000 per observation, every obs column and the spatial coordinates; batch_key holds the source dataset ID. Use it to pool sections for cell communication.

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