tile-matrix-generation-counting-strategy-selection
Summary
Select and apply an appropriate counting strategy (e.g., paired-insertion counting) when generating a tile matrix from ATAC-seq fragment data in SnapATAC2. This skill bridges fragment-level preprocessing and downstream spectral embedding by converting raw alignments into a discrete feature matrix suitable for dimension reduction.
When to use
After importing fragment files into AnnData using pp.import_fragments and before performing spectral embedding (tl.spectral) or other dimension reduction. Apply this skill when you have paired-end ATAC-seq data with properly formatted fragment coordinates and need to represent chromatin accessibility as a tile-by-cell count matrix for clustering and visualization.
When NOT to use
- Input is already a peak-by-cell or gene-by-cell count matrix (use directly for embedding instead).
- Fragment data contains single-end reads without paired mate information (requires alternative counting strategy or realignment).
- Analysis goal is peak-level rather than genome-wide accessibility profiling (use pp.make_peak_matrix instead).
Inputs
- AnnData object with imported fragment data (adata with obs column containing cell barcodes and var containing genomic coordinates from pp.import_fragments)
- Reference genome assembly or chrom.sizes file defining tile boundaries
Outputs
- AnnData object with tile matrix added as a sparse count matrix (adata.X or named layer)
- Tile coordinates in adata.var indexed by genomic position (chr:start-end)
How to apply
Use SnapATAC2's pp.add_tile_matrix function with paired-insertion counting strategy, which counts the number of Tn5 insertions falling within non-overlapping genomic tiles (typically 5 kb). The paired-insertion strategy correctly handles paired-end reads by counting each valid fragment pair once, avoiding double-counting and artificial noise from single-end artefacts. This produces a sparse, binary or count matrix indexed by tile coordinates and cell barcodes. Validate that the resulting matrix has non-zero coverage across cell populations and that tile counts correlate with expected chromatin accessibility patterns before proceeding to embedding.
Related tools
- SnapATAC2 (Primary framework providing pp.add_tile_matrix function and paired-insertion counting strategy implementation) — https://github.com/scverse/SnapATAC2
- pp.import_fragments (Upstream preprocessing function that loads raw fragment files into AnnData before tile matrix generation) — https://github.com/scverse/SnapATAC2
- tl.spectral (Downstream dimension reduction tool applied to the tile matrix for embedding) — https://github.com/scverse/SnapATAC2
- AnnData (Data container that stores tile matrix, cell metadata, and tile coordinates)
Examples
import snapatac2 as snap; adata = snap.pp.add_tile_matrix(adata, n_jobs=8); print(adata.X.shape, adata.var_names[:5])
Evaluation signals
- Tile matrix dimensions match expected number of tiles (e.g., ~600k tiles for 5 kb resolution on hg38) and number of cells in fragment import.
- Sparsity of tile matrix is consistent with ATAC-seq (typically 95–99% zeros); very dense or very sparse matrices suggest counting errors.
- Cell-level coverage statistics (total insertions per cell) are comparable across cell populations and match fragment import statistics.
- UMAP or spectral embedding computed on tile matrix visually separates known cell types or clusters consistent with published reference (e.g., pbmc10k_multiome tutorial).
- Tile matrix correlates with known peak regions from parallel peak-calling experiments (e.g., peaks called with tl.macs3 should overlap high-coverage tiles).
Limitations
- Tile size (typically 5 kb) is a fixed hyperparameter that cannot be easily adjusted post-hoc; very small tiles may be too sparse, very large tiles may obscure fine-grained chromatin structure.
- Paired-insertion strategy requires high-quality fragment files with correct mate pairing; incorrectly paired or single-end-only fragments will be discarded or cause errors.
- SnapATAC2's tile matrix is memory-resident in AnnData format; scaling to >10 million cells requires sparse matrix compression and may require high-memory compute nodes.
- Tile counts are sensitive to sequencing depth and library quality; samples with vastly different coverage may require explicit normalization before downstream analysis.
Evidence
- [other] Generate tile matrix using pp.add_tile_matrix with paired-insertion counting strategy: "Generate tile matrix using pp.add_tile_matrix with paired-insertion counting strategy."
- [methods] Fragment file processing and matrix operations are core workflow steps: "Fragment file processing with pp.make_fragment_file, pp.import_fragments; Matrix operation including pp.add_tile_matrix, pp.make_peak_matrix, pp.make_gene_matrix"
- [intro] End-to-end pipeline workflow includes preprocessing and matrix generation before dimension reduction: "End-to-end analysis pipeline for single-cell ATAC-seq data, including preprocessing, dimension reduction, clustering, data integration, peak calling"
- [intro] Blazingly fast preprocessing enables count matrix generation as part of core workflow: "Blazingly fast preprocessing tools for BAM to fragment files conversion and count matrix generation."
- [readme] SnapATAC2 scales to millions of cells with efficient preprocessing: "Scale to more than 10 million cells."