single-cell-atac-fragment-import-processing

single-cell-atac-fragment-import-processing

Summary

Import aligned ATAC-seq fragment files into an AnnData object and generate a tile-based count matrix for downstream analysis. This preprocessing step converts BAM or fragment TSV inputs into a sparse, indexed matrix representation suitable for dimension reduction and clustering.

When to use

You have aligned single-cell ATAC-seq data as BAM files or fragment files (TSV format with genomic coordinates) and need to prepare it for spectral embedding, clustering, and peak calling. This is the entry point after alignment but before any dimension reduction or statistical analysis.

When NOT to use

• Input is already a peak-by-cell count matrix or feature table; use this only for raw fragment data.
• Fragment files are missing or corrupted; validate file integrity and coordinate format first.
• You need peak-level rather than tile-level resolution; defer peak calling until after clustering.

Inputs

• BAM files (aligned single-cell ATAC-seq reads)
• Fragment TSV files (tab-delimited: chr, start, end, barcode, count)
• Cell barcode whitelist (optional, for filtering)

Outputs

• AnnData object with tile matrix (.X as sparse CSR matrix)
• Cell metadata including barcode and QC metrics
• Tile feature names (genomic intervals)

How to apply

First, import fragment files using pp.import_fragments with paired-end mode enabled, which reads fragment coordinate triplets (chromosome, start, end) and cell barcodes into an AnnData object. Then generate a tile matrix using pp.add_tile_matrix with a paired-insertion counting strategy, which bins the genome into fixed-width tiles (default 500 bp) and counts fragment insertions per tile per cell. This creates a sparse feature matrix where rows are tiles and columns are cells. The tile-based approach is matrix-free, scaling efficiently to millions of cells without materializing the full dense matrix. Verify that the resulting AnnData object has nonzero counts in the tile matrix and that cell and tile dimensions match expectations before proceeding to spectral embedding.