Troubleshooting Guide

Overview

This skill helps diagnose and resolve common issues in ChatSpatial analysis.

Quick Diagnosis Tree

Q: What type of problem?
│
├─ Analysis fails with error
│   └─ See: Error Messages section
│
├─ Analysis runs but results look wrong
│   └─ See: Result Validation section
│
├─ Performance issues (slow/memory)
│   └─ See: Performance section
│
└─ Dependency/installation problems
    └─ See: Environment section

Error Messages

Data Loading Errors

Diagnostic steps:

1. Verify file exists: ls -la <path>
2. Check file size: du -h <path>
3. Try reading header only to test format

Preprocessing Errors

Method-Specific Errors

Deconvolution

Cell Communication

Trajectory/Velocity

Result Validation

Unexpected Clustering Results

Symptoms:

• Too few/many clusters
• Clusters don't match histology
• Known cell types not separated

Solutions:

1. Adjust resolution parameter (higher = more clusters)
2. Try different clustering methods
3. Verify preprocessing quality
4. Check for batch effects

Poor Deconvolution Results

Symptoms:

• All spots have same composition
• Proportions don't sum to 1
• Expected cell types missing

Diagnostic checklist:

• Reference and spatial data normalized consistently?
• Sufficient gene overlap (>2000 genes)?
• Reference cell types well-defined?
• Spatial data quality passed QC?

Meaningless Communication Results

Symptoms:

• Random interactions without biological sense
• Same interactions everywhere
• Missing expected pathways

Solutions:

1. Verify cell type annotations are correct
2. Check species setting matches data
3. Try different communication database
4. Increase minimum expression threshold

Performance Issues

Memory Problems

Symptoms:

• MemoryError
• System becomes unresponsive
• Kernel crashes

Solutions by data size:

Specific techniques:

1. Subsample for exploration:
   sc.pp.subsample(adata, n_obs=50000)

2. Use sparse matrices:
   adata.X = scipy.sparse.csr_matrix(adata.X)

3. Process in chunks:
   Use batch processing for large datasets

Slow Execution

Common causes and solutions:

Environment Issues

Python Dependencies

Check installation:

python -c "import scanpy; print(scanpy.__version__)"
python -c "import squidpy; print(squidpy.__version__)"

Common fixes:

pip install --upgrade scanpy squidpy
pip install scvi-tools  # For deep learning methods

R Dependencies (rpy2)

Check R availability:

import rpy2.robjects as ro
print(ro.r('R.version.string'))

Install R packages:

# In R console
install.packages("Seurat")
BiocManager::install("RCTD")
devtools::install_github("sqjin/CellChat")

Common rpy2 issues:

1. R_HOME not set:
   export R_HOME=/path/to/R

2. Library path issues:
   Check .libPaths() in R

3. Version mismatch:
   Ensure rpy2 matches R version

GPU/CUDA Issues

Check GPU availability:

import torch
print(torch.cuda.is_available())
print(torch.cuda.device_count())

Common fixes:

• Update CUDA drivers
• Install correct torch version for CUDA
• Use CPU fallback: use_gpu=False

Data Format Issues

AnnData Structure Problems

Verify structure:

print(adata)
print(adata.obs.columns.tolist())
print(adata.var.columns.tolist())
print(list(adata.obsm.keys()))
print(list(adata.layers.keys()))

Common fixes:

Coordinate System Issues

Spatial coordinates check:

if 'spatial' in adata.obsm:
    print(adata.obsm['spatial'].shape)
    print(adata.obsm['spatial'][:5])

Common problems:

• Coordinates in wrong units
• Flipped/rotated coordinates
• Missing spatial key

Getting Help

Information to Provide

When reporting issues, include:

1. Error message: Full traceback
2. Data description: n_cells, n_genes, platform
3. Command used: Exact parameters
4. Environment: Python version, package versions

Quick Diagnostic Commands

# Dataset summary
print(f"Cells: {adata.n_obs}, Genes: {adata.n_vars}")
print(f"Spatial: {'spatial' in adata.obsm}")
print(f"Layers: {list(adata.layers.keys())}")
print(f"Obs columns: {adata.obs.columns.tolist()[:10]}")