GitHub
Back to all tutorials

Spatial analysis

Spatial Analysis - Visium HD

This tutorial shows how to load a 10x Genomics Visium HD dataset in CellPilot, add the Space Ranger-aligned tissue image, inspect full-transcriptome spatial expression, and use sketch-based clustering for large tissue datasets.

Input data

This walkthrough uses the 10x Genomics Visium HD Spatial Gene Expression Library, Mouse Kidney (FFPE) dataset analyzed with Space Ranger. Download the Space Ranger output files from the 10x dataset page, then download the tissue image below for the histology overlay.

Open the 10x Genomics Visium HD mouse kidney dataset page

mkdir -p visiumhd_mouse_kidney
cd visiumhd_mouse_kidney

curl -O https://cf.10xgenomics.com/samples/spatial-exp/4.0.1/Visium_HD_Mouse_Kidney/Visium_HD_Mouse_Kidney_tissue_image.btf

CellPilot is designed to accept the standard Space Ranger output folder directly. For your own data, select the folder produced by spaceranger count; no command-line renaming is needed.

1. Prepare the Space Ranger folder

Unzip or organize the downloaded Space Ranger output without changing the internal folder structure. CellPilot can load the sample folder, its outs folder, segmented_outputs, binned_outputs, or a square_* binned folder.

When available, CellPilot uses segmented_outputs first. This mode reads cell_segmentations.geojson for cell boundaries and filtered_feature_cell_matrix/ or filtered_feature_cell_matrix.h5 for expression. If segmented outputs are not present, CellPilot loads binned outputs such as binned_outputs/square_008um/ with tissue positions and a filtered feature-barcode matrix.

2. Load the Visium HD dataset

  1. Open CellPilot.
  2. In the Data Type menu, choose Spatial analysis - Visium HD.
  3. Choose Single sample.
  4. Click Browse and select the Space Ranger output folder.
  5. Wait for CellPilot to read the feature matrix, spatial coordinates, and analysis files.

For segmented Visium HD data, CellPilot can show polygon cell boundaries. For binned data, CellPilot uses the tissue position coordinates for spatial visualization.

3. Add the histology image overlay

Visium HD histology images are treated as pre-aligned when they are the same image used during Space Ranger processing. For this demo image, no transformation matrix is required.

  1. Open the Spatial View.
  2. Click Add Histology Image.
  3. Select Visium_HD_Mouse_Kidney_tissue_image.btf as the histology image.
  4. Leave the transformation matrix empty.
  5. Click Load Image and wait while CellPilot prepares the tiled image for viewing.

If you use a different microscope image than the one used for Space Ranger, align it first with Loupe Browser and Space Ranger. Follow the Visium HD manual alignment workflow, export the alignment, and rerun Space Ranger or provide a matching 3x3 transformation matrix CSV if you want CellPilot to transform the image directly.

Open the 10x Genomics Visium HD Loupe alignment tutorial

4. Inspect spatial clusters and marker genes

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

Tell me about cluster 6
Find markers for cluster 6
Plot Nphs2
Violin plot Nphs2
Dotplot Nphs2 Podxl
Change color to green black red

Visium HD is full transcriptome, so gene imputation is not needed for this workflow. Gene plots are shown on the spatial coordinates and can be interpreted with the tissue image overlay.

5. Adjust analysis parameters with sketching

For large Visium HD datasets, CellPilot uses sketch-based UMAP and clustering when reanalysis or reclustering is requested. The sketch workflow samples representative cells, fits UMAP on the sketch, clusters the sketch with Louvain, and transfers cluster labels back to all cells. This keeps large tissue datasets responsive while preserving rare populations.

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

When the sketch pipeline runs, CellPilot recomputes enough PCA dimensions for rare-cell capture, uses the sketch UMAP/clusters for the display, and keeps the spatial coordinates aligned to the filtered cells.

6. 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

7. 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

8. Run BANKSY spatial region analysis

CellPilot can 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 cortex
Find markers for the selected spatial region