Tile matrix generation counting strategy selection

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