GitHub
Back to all tutorials

Spatial analysis

Spatial Analysis - Xenium

This tutorial shows how to load a 10x Genomics Xenium dataset in CellPilot, inspect the spatial tissue view, overlay an aligned histology image, explore marker genes, and run spatial region analysis.

Input data

This walkthrough uses the 10x Genomics Xenium FFPE Human Breast Cancer preview dataset. CellPilot accepts a standard Xenium output folder directly. For this demo, download the Xenium output bundle for expression and cell coordinates, then download the H&E image and alignment matrix for the histology overlay.

Open the 10x Genomics Xenium breast dataset page

mkdir -p xenium_human_breast
cd xenium_human_breast

BASE=https://cf.10xgenomics.com/samples/xenium/1.0.1/Xenium_FFPE_Human_Breast_Cancer_Rep1
SAMPLE=Xenium_FFPE_Human_Breast_Cancer_Rep1

curl -O ${BASE}/${SAMPLE}_outs.zip
curl -O ${BASE}/${SAMPLE}_he_image.tif
curl -O ${BASE}/${SAMPLE}_he_imagealignment.csv

1. Prepare the Xenium folder

Unzip the Xenium output bundle and keep the standard folder structure. CellPilot can load either the folder that contains outs/ or the outs folder itself.

unzip ${SAMPLE}_outs.zip

The selected Xenium region folder should contain experiment.xenium, cells.csv.gz or another supported cells file, cell_feature_matrix/, and analysis/. CellPilot uses the cell file for spatial coordinates, the cell-feature matrix for gene expression, and the analysis folder for UMAP and cluster information when available.

2. Load the Xenium dataset

  1. Open CellPilot.
  2. In the Data Type menu, choose Spatial analysis - Xenium.
  3. Click Browse and select the unzipped Xenium output folder.
  4. Wait for CellPilot to read the cell-feature matrix, spatial coordinates, and analysis files.

When the dataset loads, CellPilot opens a spatial view with the Xenium cell coordinates. The Xenium loader uses a Xenium-specific spatial scale factor for histology alignment, so the histology image should be added through the image overlay dialog rather than treated as a pre-aligned image.

3. Add the histology image overlay

CellPilot supports a histology layout for Xenium data. The overlay is loaded separately from the Xenium output folder so users can inspect gene expression and clusters directly on the tissue morphology.

  1. Open the Spatial View.
  2. Click Add Histology Image.
  3. Select Xenium_FFPE_Human_Breast_Cancer_Rep1_he_image.tif as the histology image.
  4. Select Xenium_FFPE_Human_Breast_Cancer_Rep1_he_imagealignment.csv as the transformation matrix.
  5. Click Load Image and wait while CellPilot converts the TIFF into a tiled image for fast viewing.

The transformation matrix must be a 3x3 CSV. CellPilot applies the matrix to align the histology image with the Xenium spatial coordinates. Large TIFF files may take several minutes to process the first time.

4. If you use your own histology image

If your histology image comes from a confocal microscope or another imaging workflow, register it to the Xenium morphology coordinate system before loading it in CellPilot. Use Xenium Explorer or the Xenium browser image alignment workflow, then export the transformation matrix and load that CSV together with the image in CellPilot.

Open the 10x Genomics Xenium image alignment tutorial

5. Inspect spatial clusters and marker genes

Use the spatial tissue view to inspect where clusters appear in the tissue. Then use chat commands to find markers, plot genes, and adjust the color scale.

Tell me about cluster 6
Find markers for cluster 6
Plot EPCAM
Violin plot EPCAM
Dotplot EPCAM KRT19 COL1A1
Change color to green black red

For Xenium spatial data, CellPilot shows gene expression on the tissue coordinates. Dot plot commands can summarize expression by cluster, and the active gene plot can be viewed in the spatial layout.

6. Adjust analysis parameters

CellPilot can rerun core RNA-style analysis steps on the Xenium cell-feature matrix and keep the spatial coordinates available for tissue visualization.

Rerun the analysis by setting min gene = 20
Rerun umap with min dist = 0.4
Recluster the cells using resolution = 2.0

7. Impute unmeasured genes with a reference

If you have a matched or biologically relevant scRNA-seq reference, CellPilot can impute genes that were not measured in the Xenium panel. For this breast cancer dataset, you can use the 10x Genomics breast cancer scRNA-seq reference H5 file below.

curl -O https://cf.10xgenomics.com/samples/cell-exp/7.0.1/SC3pv3_GEX_Breast_Cancer_DTC_Aggr/SC3pv3_GEX_Breast_Cancer_DTC_Aggr_count_filtered_feature_bc_matrix.h5
  1. Load the Xenium dataset first.
  2. Choose the gene imputation option and select the downloaded scRNA-seq H5 reference.
  3. Ask CellPilot to impute a gene that is not in the Xenium panel.
Impute ERBB2 expression
Impute ESR1 expression
Impute PGR expression

CellPilot uses SpaGE-style reference mapping to predict the requested gene expression on the spatial tissue view.

8. Select a region and ask about it

In the Spatial View, draw or select a tissue region that you want to inspect. CellPilot can summarize the selected area, report marker genes, and help interpret the likely cell type composition of that region.

What is this region?
What cell types are in the selected region?
Find markers for the selected spatial region

9. Run cell-cell interaction analysis

After selecting at least two spatial regions, CellPilot can run ligand-receptor style cell-cell communication analysis across the selected tissue areas.

Run cell-cell interaction analysis across selected regions

10. Run BANKSY spatial region analysis

CellPilot can also identify tissue domains automatically with BANKSY region segmentation, which uses expression and spatial neighborhood structure. After regions are created, they can be viewed, renamed, and used for marker analysis.

Run BANKSY region segmentation
Show regions
What cell types are in region 1?
Rename region 1 to tumor
Find markers for the selected spatial region