scATAC-seq Integration

Input data

This walkthrough uses two 10x Genomics adult mouse cortex scATAC-seq datasets: Chromium Controller and Chromium X. CellPilot accepts standard Cell Ranger ATAC output folders directly. The download and rename commands below are only needed for these public demo files, because the downloaded files include the sample ID in every filename.

Dataset pages: Chromium Controller and Chromium X.

mkdir -p mouse_cortex_atac_controller mouse_cortex_atac_chromium_x

cd mouse_cortex_atac_controller
BASE=https://cf.10xgenomics.com/samples/cell-atac/2.1.0/8k_mouse_cortex_ATACv2_nextgem_Chromium_Controller
SAMPLE=8k_mouse_cortex_ATACv2_nextgem_Chromium_Controller
curl -O ${BASE}/${SAMPLE}_filtered_peak_bc_matrix.tar.gz
curl -O ${BASE}/${SAMPLE}_fragments.tsv.gz
curl -O ${BASE}/${SAMPLE}_fragments.tsv.gz.tbi
curl -O ${BASE}/${SAMPLE}_peak_annotation.tsv
curl -O ${BASE}/${SAMPLE}_singlecell.csv
curl -O ${BASE}/${SAMPLE}_summary.csv
curl -O ${BASE}/${SAMPLE}_web_summary.html
tar -xzf ${SAMPLE}_filtered_peak_bc_matrix.tar.gz
mv ${SAMPLE}_fragments.tsv.gz fragments.tsv.gz
mv ${SAMPLE}_fragments.tsv.gz.tbi fragments.tsv.gz.tbi
mv ${SAMPLE}_peak_annotation.tsv peak_annotation.tsv
mv ${SAMPLE}_singlecell.csv singlecell.csv
mv ${SAMPLE}_summary.csv summary.csv
mv ${SAMPLE}_web_summary.html web_summary.html

cd ../mouse_cortex_atac_chromium_x
BASE=https://cf.10xgenomics.com/samples/cell-atac/2.1.0/8k_mouse_cortex_ATACv2_nextgem_Chromium_X
SAMPLE=8k_mouse_cortex_ATACv2_nextgem_Chromium_X
curl -O ${BASE}/${SAMPLE}_filtered_peak_bc_matrix.tar.gz
curl -O ${BASE}/${SAMPLE}_fragments.tsv.gz
curl -O ${BASE}/${SAMPLE}_fragments.tsv.gz.tbi
curl -O ${BASE}/${SAMPLE}_peak_annotation.tsv
curl -O ${BASE}/${SAMPLE}_singlecell.csv
curl -O ${BASE}/${SAMPLE}_summary.csv
curl -O ${BASE}/${SAMPLE}_web_summary.html
tar -xzf ${SAMPLE}_filtered_peak_bc_matrix.tar.gz
mv ${SAMPLE}_fragments.tsv.gz fragments.tsv.gz
mv ${SAMPLE}_fragments.tsv.gz.tbi fragments.tsv.gz.tbi
mv ${SAMPLE}_peak_annotation.tsv peak_annotation.tsv
mv ${SAMPLE}_singlecell.csv singlecell.csv
mv ${SAMPLE}_summary.csv summary.csv
mv ${SAMPLE}_web_summary.html web_summary.html

1. Load ATAC samples

1. Open CellPilot.
2. In the Data Type menu, choose scATAC-seq.
3. Choose Multiple samples.
4. Set the sample count to 2.
5. Name the samples Controller and ChromiumX.
6. Browse to the prepared folder for each sample.
7. Click Load ATAC integration.

Each folder should contain the standard Cell Ranger ATAC-style filtered_peak_bc_matrix folder and, when available, fragments.tsv.gz, fragments.tsv.gz.tbi, and peak_annotation.tsv.

2. Let CellPilot run Harmony integration

CellPilot uses a JavaScript implementation of Harmony for scATAC-seq integration, rewritten for the in-app pipeline from the Harmony algorithm described by the immunogenomics/harmony project. This allows CellPilot to perform batch correction inside the desktop app without requiring users to write R or Python code.

The integration procedure is:

1. Create a unified peak set by merging peaks across samples.
2. Remap each sample's peak-by-cell matrix onto the unified peak set.
3. Concatenate the remapped matrices and store sample labels for each cell.
4. Select top accessible features, run TF-IDF normalization, and compute LSI with randomized SVD.
5. Skip the first LSI component, which is often depth-associated, and run Harmony on the remaining LSI dimensions.
6. Harmony iteratively assigns cells to soft clusters with a sample-diversity penalty, then uses ridge regression to remove sample-associated effects from the embedding.
7. Run UMAP and Louvain clustering on the Harmony-corrected embeddings.

3. Inspect integrated clusters

After integration finishes, CellPilot shows the integrated UMAP and keeps the sample identity for every cell. Use the shared UMAP to identify accessible chromatin states that are present in both samples.

Tell me about cluster 2
Find markers for cluster 2
Rename cluster 2 to excitatory neurons
Rename cluster 5 to oligodendrocytes

Marker detection in ATAC integration mode uses the unified peak matrix, so marker results are reported as marker peaks.

4. Compare samples within a cluster

CellPilot can compare accessibility between the two samples inside a selected integrated cluster. This is useful for checking whether the same cell type has sample-specific open chromatin changes.

Find differential peaks for cluster 2 between Controller and ChromiumX
Find differential peaks for cluster 5 between sample 1 and sample 2

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

5. Plot gene activity and coverage

If peak_annotation.tsv is present, CellPilot can summarize accessibility near genes and display gene activity on the integrated UMAP. For this mouse cortex dataset, useful starting genes include Slc17a7, Gad1, Gad2, Snap25, Rbfox3, Aqp4, and Mbp.

Plot Slc17a7
Plot gene activity for Gad1
Dotplot Slc17a7 Gad1 Mbp
Coverage plot Slc17a7
Change color to green black red

The color command changes the active gene activity, dot plot, or coverage color scale, so run it after creating the plot you want to recolor.

6. Review sample balance

Use the integrated UMAP and the per-sample UMAP cards to confirm that major biological populations are shared across the Controller and Chromium X samples after Harmony correction. When a gene activity or coverage plot is active, CellPilot keeps the same integrated clusters while showing the signal in each sample view.

Plot gene activity for Slc17a7
Coverage plot Slc17a7
Dotplot Slc17a7 Gad1 Mbp

7. Adjust integration parameters

CellPilot can rerun core ATAC integration steps from chat. UMAP commands rerun the corrected embedding visualization, and clustering commands rerun Louvain clustering using the Harmony-corrected LSI space.

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

8. Notes for your own data

For your own Cell Ranger ATAC output, select the output folder directly. You do not need to rename files if your folder already follows the standard Cell Ranger ATAC structure. The renaming commands above are only for the public 10x demo downloads.

Standalone scATAC-seq integration does not include RNA expression, so this tutorial does not include peak-to-gene linkage or TF motif sections. Those analyses are covered in the multiome workflows where paired RNA and ATAC data are available.