CellCharter Spatial Clustering Analysis Skill

Comprehensive assistance with CellCharter, a Python package for identifying, characterizing, and comparing spatial clusters from spatial-omics data including spatial transcriptomics, proteomics, epigenomics, and multiomics data.

When to Use This Skill

This skill should be triggered when:

Core Spatial Analysis Tasks

• Spatial clustering: Identifying cellular niches and spatial domains in tissue data
• Domain characterization: Analyzing properties of identified spatial clusters
• Cross-sample analysis: Comparing spatial domains across multiple samples or conditions
• Batch effect handling: Working with spatial data from different experiments or platforms

Data Types and Platforms

• Spatial transcriptomics: 10x Visium, Xenium, Nanostring CosMx, Vizgen MERSCOPE, Stereo-seq, DBiT-seq, MERFISH, seqFISH
• Spatial proteomics: Akoya CODEX, Lunaphore COMET, CyCIF, IMC, MIBI-TOF
• Spatial epigenomics: scVI-based analysis with Poisson distributions
• Multiomics data: Integration using MultiVI or concatenated model results

Specific Analysis Needs

• Neighborhood analysis: Cell-cell interactions and spatial relationships
• Shape metrics: Quantifying spatial domain morphology (linearity, elongation, purity)
• Differential analysis: Comparing spatial patterns between conditions
• Visualization: Creating plots of spatial domains and enrichment patterns

Technical Implementation

• Parameter optimization: Finding optimal number of spatial clusters
• Model configuration: Setting up Gaussian Mixture Models or other clustering approaches
• Data preprocessing: Spatial neighbor graphs and feature aggregation
• Performance optimization: GPU acceleration for large datasets

Quick Reference

Core Setup and Data Loading

Example 1 (python):

import squidpy as sq
import cellcharter as cc
import scanpy as sc
from lightning.pytorch import seed_everything
seed_everything(0)

Example 2 (python):

# Load example dataset
adata = cc.datasets.codex_mouse_spleen('./data/codex_mouse_spleen.h5ad')
adata

Spatial Graph Construction

Example 3 (python):

# Build spatial neighborhood graph
sq.gr.spatial_neighbors(adata, coord_type='generic', delaunay=True)
cc.gr.remove_long_links(adata)
cc.gr.aggregate_neighbors(adata, n_layers=3)

Clustering with AutoK

Example 4 (python):

# Find optimal number of clusters
model_params = {
    'random_state': 42,
    'trainer_params': {
        'accelerator': 'cpu',
        'enable_progress_bar': False
    },
}
models = cc.tl.ClusterAutoK(
    n_clusters=(2, 10),
    model_class=cc.tl.GaussianMixture,
    model_params=model_params,
    max_runs=5
)
models.fit(adata)

Shape Analysis

Example 5 (python):

# Compute shape metrics for spatial domains
cc.tl.elongation(adata, cluster_key='component')
cc.tl.linearity(adata, cluster_key='component')
cc.tl.purity(adata, cluster_key='component', library_key='sample')

Neighborhood Enrichment

Example 6 (python):

# Analyze cell-cell interactions
cc.gr.nhood_enrichment(adata, cluster_key='component')
cc.pl.nhood_enrichment(adata, cluster_key='component')

Differential Analysis

Example 7 (python):

# Compare neighborhoods between conditions
cc.gr.diff_nhood_enrichment(
    adata,
    cluster_key='component',
    condition_key='condition'
)

Visualization

Example 8 (python):

# Plot spatial domain boundaries
cc.pl.boundaries(
    adata,
    sample='sample1',
    library_key='sample',
    component_key='component'
)

Key Concepts

Spatial Clustering

• Spatial domains: Regions of tissue characterized by specific cellular compositions
• Neighborhood aggregation: Combining features from spatially adjacent cells
• Topological boundaries: Geometric boundaries defining spatial clusters

Shape Metrics

• Elongation: Ratio of minor to major axes of minimum bounding rectangle
• Linearity: Ratio of longest skeleton path to total skeleton length
• Purity: Ratio of cluster cells within boundary to total boundary cells

Graph Analysis

• Spatial connectivity: Networks representing cell-cell spatial relationships
• Neighborhood enrichment: Statistical analysis of cell type co-occurrence
• Differential enrichment: Comparing spatial patterns between conditions

Model Types

• Gaussian Mixture Model (GMM): Primary clustering method using TorchGMM
• TRVAE: Modified scArches model for spatial proteomics data
• ClusterAutoK: Automated selection of optimal cluster numbers

Reference Files

This skill includes comprehensive documentation in references/:

Analysis Documentation

• analysis_functions.md (8 pages): Detailed function documentation for shape analysis (elongation, linearity, purity), clustering methods (ClusterAutoK, TRVAE), and statistical computations
• analysis_tools.md (1 page): Overview of all available tools including boundary computation, clustering, and shape metrics

Graph and Network Analysis

• graph_analysis.md (1 page): High-level overview of graph functions for neighborhood analysis and connectivity
• graph_functions.md (7 pages): Detailed documentation of graph operations including link removal, enrichment analysis, and neighbor aggregation

API and Plotting

• api_reference.md (1 page): Complete API overview with graph, tools, and plotting modules
• plotting_functions.md (7 pages): Comprehensive plotting documentation for boundaries, enrichment, shape metrics, and stability analysis

Getting Started

• getting_started.md (1 page): Installation instructions, background information, and supported data types
• tutorials.md: Tutorial content for learning CellCharter workflows

Working with This Skill

For Beginners

1. Start with: getting_started.md for installation and basic concepts
2. Learn workflow: Follow tutorials to understand typical analysis pipelines
3. Basic analysis: Begin with simple clustering and visualization examples

For Intermediate Users

1. Parameter optimization: Use ClusterAutoK for automated cluster number selection
2. Shape analysis: Implement domain characterization with elongation, linearity, and purity metrics
3. Neighborhood analysis: Explore cell-cell interactions using enrichment functions

For Advanced Users

1. Multi-sample integration: Handle batch effects across multiple samples
2. Custom models: Implement specialized clustering approaches beyond default GMM
3. Large-scale analysis: Optimize performance for datasets with millions of cells
4. Differential analysis: Compare spatial patterns between experimental conditions

Navigation Tips

• Function reference: Use analysis_functions.md and graph_functions.md for detailed parameter descriptions
• Quick lookup: api_reference.md provides compact function overviews
• Visualization guidance: plotting_functions.md contains all plotting options and customization
• Workflow examples: Tutorials demonstrate end-to-end analysis pipelines

Common Workflows

Basic Spatial Clustering

1. Load data and build spatial graph
2. Aggregate neighborhood features
3. Apply clustering with optimal K selection
4. Visualize results

Advanced Domain Characterization

1. Perform spatial clustering
2. Compute shape metrics
3. Analyze neighborhood enrichment
4. Compare across conditions

Multi-sample Analysis

1. Process individual samples
2. Apply batch correction if needed
3. Identify consensus spatial domains
4. Perform differential analysis

Resources

references/

Organized documentation extracted from official sources containing:

• Detailed function parameters and return values
• Real code examples with proper syntax highlighting
• Links to original documentation for further reading
• Structured table of contents for quick navigation

Installation Requirements

• Python >= 3.8
• PyTorch >= 1.12.0
• scvi-tools (for spatial transcriptomics/epigenomics)
• Modified scArches TRVAE (for spatial proteomics)
• Squidpy for spatial operations

Supported Platforms

• GPU acceleration: NVIDIA CUDA support for large datasets
• Memory optimization: Scalable to millions of cells
• Multiple data types: Flexible input format support

Notes

• CellCharter uses TorchGMM (maintained fork of PyCave) for stable Gaussian Mixture Model implementation
• The toolkit is designed for both single-sample and multi-sample spatial analysis
• Shape metrics provide quantitative characterization of spatial domain morphology
• Neighborhood enrichment analysis can be performed with statistical significance testing

Updating

To refresh this skill with updated documentation:

1. Re-run the documentation scraper with the same configuration
2. The skill will be rebuilt with the latest API changes and examples
3. Reference files maintain original structure and cross-references