scRNA-seq Integration

Input data

This walkthrough uses three 10x Genomics PBMC 3' GEM-X H5 files from human donors 2, 3, and 4. CellPilot also supports 10x MatrixMarket folders for scRNA-seq integration.

mkdir -p pbmc_gemx_integration
cd pbmc_gemx_integration

curl -O https://cf.10xgenomics.com/samples/cell-exp/9.0.0/5k_Human_Donor2_PBMC_3p_gem-x_5k_Human_Donor2_PBMC_3p_gem-x/5k_Human_Donor2_PBMC_3p_gem-x_5k_Human_Donor2_PBMC_3p_gem-x_count_sample_filtered_feature_bc_matrix.h5
curl -O https://cf.10xgenomics.com/samples/cell-exp/9.0.0/5k_Human_Donor3_PBMC_3p_gem-x_5k_Human_Donor3_PBMC_3p_gem-x/5k_Human_Donor3_PBMC_3p_gem-x_5k_Human_Donor3_PBMC_3p_gem-x_count_sample_filtered_feature_bc_matrix.h5
curl -O https://cf.10xgenomics.com/samples/cell-exp/9.0.0/5k_Human_Donor4_PBMC_3p_gem-x_5k_Human_Donor4_PBMC_3p_gem-x/5k_Human_Donor4_PBMC_3p_gem-x_5k_Human_Donor4_PBMC_3p_gem-x_count_sample_filtered_feature_bc_matrix.h5

1. Load multiple samples

1. Open CellPilot.
2. In the Data Type menu, choose scRNA-seq.
3. Choose Multiple samples.
4. Set the sample count to 3.
5. Name the samples Donor2, Donor3, and Donor4.
6. Select the matching H5 file for each donor.
7. Click Load integration.

Sample names must be unique. CellPilot uses these names later for per-sample UMAP cards, cell fraction plots, dotplots, violin plots, and differential expression comparisons.

2. Let CellPilot run MNN integration

For scRNA-seq integration, CellPilot builds one bakana dataset per sample and runs a shared RNA workflow with MNN batch correction. The pipeline includes normalization, feature selection, MNN correction, PCA with block projection, UMAP, graph clustering, and marker detection. CellPilot sets the integrated UMAP min_dist to 0.4 by default for multi-sample analysis.

When integration finishes, CellPilot shows an integrated UMAP and keeps per-sample cell indices so the same clusters can be viewed and compared by donor.

3. Inspect integrated clusters

Use the integrated UMAP to inspect shared cell populations across all donors. Then ask CellPilot for cluster markers and rename clusters after reviewing canonical PBMC genes.

Tell me about cluster 2
Find markers for cluster 2
Plot MS4A1
Violin plot MS4A1
Dotplot MS4A1 CD3D LST1 NKG7 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.

4. Compare sample composition

CellPilot can summarize the fraction of each integrated cluster contributed by each donor. This is useful for checking batch balance and donor-specific shifts in cell population abundance.

Plot cell fraction by sample
Show cell proportion by sample

5. Find differential genes between donors

After integration, CellPilot can compare two samples within the same cluster. The comparison uses normalized expression, tests genes with a Wilcoxon rank-sum test, adjusts p-values with Benjamini-Hochberg correction, and returns a table plus volcano-style results.

Find differential genes for cluster 2 between Donor2 and Donor3
Find differential genes for cluster 2 between sample 1 and sample 2
Find differential genes for cluster 5 between Donor3 and Donor4

Use the donor names you entered during loading, or use sample 1 and sample 2 for the first two datasets.

6. Rename clusters

After reviewing marker genes, rename clusters to biological labels. The labels are applied to the integrated UMAP and downstream plots.

Rename cluster 0 to CD4 T cells
Rename cluster 2 to B cells
Rename cluster 5 to Monocytes

7. Adjust integration parameters

CellPilot can rerun core analysis steps from chat while preserving the integration structure and per-sample views.

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