Spatial Integration

Input data

This walkthrough uses two mouse kidney Xenium datasets from Xuanyuan et al., Nature Communications, 2025, a Humphreys Lab study of spatial transcriptomics in kidney injury and repair.

Open the Xuanyuan et al. Nature Communications paper

mkdir -p xenium_kidney_spatial_integration
cd xenium_kidney_spatial_integration

curl -L -o GSM8325615_xenium_shamL_male_output.tar.gz "https://www.ncbi.nlm.nih.gov/geo/download/?acc=GSM8325615&format=file&file=GSM8325615%5Fxenium%5FshamL%5Fmale%5Foutput%2Etar%2Egz"
curl -L -o GSM8325623_xenium_day14L_male_output.tar.gz "https://www.ncbi.nlm.nih.gov/geo/download/?acc=GSM8325623&format=file&file=GSM8325623%5Fxenium%5Fday14L%5Fmale%5Foutput%2Etar%2Egz"

The first dataset is a sham male kidney sample and the second is a day 14 injury male kidney sample. They are provided through GEO as compressed Xenium output folders.

1. Prepare the spatial folders

Extract both archives and keep the Xenium output folder structure unchanged. CellPilot can load either the folder containing outs/ or the Xenium region output folder that contains experiment.xenium.

tar -xzf GSM8325615_xenium_shamL_male_output.tar.gz
tar -xzf GSM8325623_xenium_day14L_male_output.tar.gz

Each selected Xenium folder should contain experiment.xenium, cells.csv.gz or another supported cells file, cell_feature_matrix/, and analysis/. The same spatial integration workflow also applies to Visium HD: choose Visium HD in the platform menu and provide two Space Ranger output folders.

2. Load two spatial samples

1. Open CellPilot.
2. In the Data Type menu, choose Spatial analysis - Xenium.
3. Choose 2-sample integration.
4. Name the samples sham and day14.
5. Click Browse for each row and select the matching extracted Xenium output folder.
6. Click Load Xenium integration.

For Visium HD integration, follow the same steps but choose Spatial analysis - Visium HD and select two Space Ranger output folders.

3. Let CellPilot run spatial integration

CellPilot parses each sample's spatial coordinates for per-sample tissue views, then builds one expression dataset per sample and runs MNN batch correction through the RNA workflow. The integrated analysis includes normalization, MNN correction, PCA with block projection, UMAP, graph clustering, and marker detection.

When integration finishes, CellPilot shows the shared integrated UMAP and preserves per-sample spatial views so cluster colors and gene expression can be inspected back on each tissue section.

4. Inspect integrated clusters and spatial views

Use the integrated UMAP to inspect shared cell populations, then compare how those clusters are distributed in the sham and day 14 tissue views.

Tell me about cluster 6
Find markers for cluster 6
Plot Slc7a13
Violin plot Havcr1
Dotplot Slc7a13 Havcr1 Vcam1 by sample
Change color to green black red

The color command changes the active gene or dot plot color scale, so use it after creating a feature plot, violin plot, or dot plot.

5. Compare samples within a cluster

CellPilot can compare the two spatial samples within the same integrated cluster. The comparison uses normalized expression, a Wilcoxon rank-sum test, and Benjamini-Hochberg adjusted p-values.

Find differential genes for cluster 6 between sham and day14
Find differential genes for cluster 6 between sample 1 and sample 2

This is useful for identifying injury-associated genes in the same cell population across conditions.

6. Rename integrated clusters

After reviewing markers, rename clusters to biological labels. The labels are applied to the integrated UMAP and the per-sample spatial views.

Rename cluster 1 to PT
Rename cluster 6 to Injured PT
Rename cluster 10 to Fibroblasts

7. Adjust integration parameters

CellPilot can rerun clustering or UMAP from chat while preserving the sample labels and per-sample spatial views.

Rerun umap with min dist = 0.4
Recluster the cells using resolution = 2.0