Cell Composition Analysis

Overview

This skill answers the fundamental question: What cell types exist at each spatial location, and in what proportions?

For spot-based data (Visium), this requires deconvolution to estimate cell type mixtures. For single-cell resolution data (Xenium/MERFISH), this requires direct cell type annotation.

Decision Tree: Which Approach?

START: User wants cell type information
    │
    ├─ Q: What is the data resolution?
    │   │
    │   ├─ Spot-based (Visium, Slide-seq)
    │   │   └─ Q: Do you have a reference scRNA-seq dataset?
    │   │       ├─ YES → Deconvolution (see below)
    │   │       └─ NO → Q: Do you have marker genes?
    │   │           ├─ YES → Marker-based annotation
    │   │           └─ NO → Use public atlas as reference
    │   │
    │   └─ Single-cell (Xenium, MERFISH, CosMx)
    │       └─ Q: Do you have a reference dataset?
    │           ├─ YES → Transfer learning (Tangram/scANVI)
    │           └─ NO → Marker-based or LLM annotation
    │
    └─ Execute appropriate workflow

Deconvolution Method Selection

Quick Reference Table

Detailed Method Guide

FlashDeconv (Recommended Default)

• Speed: Fastest (~seconds to minutes)
• Accuracy: Good for most applications
• When to use: Initial exploration, iterative analysis
• Limitations: Less accurate for rare cell types

RCTD (Publication Standard)

• Speed: Moderate (~minutes)
• Accuracy: Excellent, especially with doublet mode
• When to use: Final results, manuscript figures
• Modes:
  • doublet: High-resolution platforms (Visium HD, Slide-seq)
  • full: Standard Visium
  • multi: When spots may contain >2 cell types
• Note: R-based, requires rpy2

Cell2location (Large Scale)

• Speed: Slow but scalable (~hours)
• Accuracy: Excellent for complex tissues
• When to use: Large datasets, need uncertainty estimates
• Requirements: GPU recommended, scvi-tools

CARD (Spatial Imputation)

• Speed: Moderate
• Accuracy: Good
• Unique feature: Can impute cell-type-specific gene expression
• When to use: Need spatial expression patterns per cell type
• Note: R-based

Workflow: Deconvolution

Step 1: Prepare Reference Data

Requirements for reference scRNA-seq:

• Cell type annotations in adata.obs
• Sufficient cells per type (>50 recommended)
• Matching species and tissue type
• Quality-controlled and normalized

If no reference available:
1. Check CellxGene for public atlases
2. Use Tabula Sapiens (human) or Tabula Muris (mouse)
3. Consider marker-based annotation instead

Step 2: Validate Reference

Before deconvolution, verify:

• Cell type labels are present and clean
• No ambiguous categories (remove "unknown", "doublet")
• Sufficient cells per type
• Gene overlap with spatial data

Step 3: Run Deconvolution

Use deconvolve_data tool with:

• method: Selected method from decision tree
• reference_data_id: Loaded reference dataset
• cell_type_key: Column name with cell type labels

Step 4: Validate Results

Quality checks:

• Proportions sum to approximately 1
• Spatial patterns make biological sense
• Known cell type distributions match literature

Red flags:

• One cell type dominates everywhere → check reference quality
• Proportions don't vary spatially → possible normalization issue
• Expected cell types missing → check gene overlap

Step 5: Visualize

Essential visualizations:

1. Spatial pie charts: Overall composition per spot
2. Individual cell type maps: Spatial distribution of each type
3. Dominant cell type: Which type is most abundant at each spot
4. Diversity index: Cellular heterogeneity across tissue

Use visualize_data with plot_type="deconvolution".

Workflow: Direct Annotation (Single-Cell Resolution)

For Xenium/MERFISH data:

Option A: Transfer from Reference

1. Load reference scRNA-seq with cell type labels
2. Use annotate_cell_types with method="tangram" or "scanvi"
3. Validate transferred labels

Option B: Marker-Based

1. Define marker genes per cell type
2. Use annotate_cell_types with method="cellassign" or "marker"
3. Validate against known markers

Option C: LLM-Assisted (Experimental)

1. Identify cluster marker genes
2. Use mLLMCelltype for LLM-based annotation
3. Verify with domain knowledge

Common Issues and Solutions

Output Interpretation

Deconvolution produces:

• Proportions matrix: Cell type fractions per spot (stored in adata.obsm)
• Spatial patterns: Where each cell type is enriched
• Biological context: Cell type organization in tissue architecture

Use these results for:

• Understanding tissue composition
• Identifying cell type niches
• Downstream cell-cell communication analysis