# Fragment Based Count Matrix Generation

> Use when you have a backed AnnData object containing processed fragment data (stored in .obsm['fragment_paired'] or .

- Skill: `holobiomicslab/fragment-based-count-matrix-generation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add holobiomicslab/fragment-based-count-matrix-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holobiomicslab/fragment-based-count-matrix-generation/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: CC-BY-4.0
- Author: HolobiomicsLab (https://skillmd.com/u/holobiomicslab)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holobiomicslab/fragment-based-count-matrix-generation

---


# fragment-based-count-matrix-generation

## Summary

Generate tile-based count matrices from single-cell ATAC-seq fragment data using paired-insertion counting strategy in SnapATAC2. This skill quantifies chromatin accessibility at fixed genomic intervals and produces dense or sparse count matrices suitable for downstream dimensionality reduction and clustering.

## When to use

You have a backed AnnData object containing processed fragment data (stored in .obsm['fragment_paired'] or .obsm['fragment_single']) from single-cell ATAC-seq and need to convert raw genomic fragments into a quantitative count matrix indexed by fixed genomic tiles for clustering, embedding, or differential analysis.

## When NOT to use

- Input data is already in the form of a peak-by-cell matrix or gene-by-cell matrix; use pp.make_peak_matrix or pp.make_gene_matrix instead.
- Fragment file has not been imported or processed; first convert BAM to fragment file using pp.make_fragment_file or pp.import_fragments.
- You need counts at peak regions rather than fixed tiles; use pp.make_peak_matrix with called or external peak coordinates.

## Inputs

- backed AnnData object with fragment data in .obsm['fragment_paired'] or .obsm['fragment_single']
- genomic fragment coordinates (chromosome, start, end, barcode)

## Outputs

- count matrix (n_obs × n_vars) indexed by genomic tiles and cell barcodes
- tile coordinate metadata (chromosome, start, end positions for each tile)
- sparse matrix with paired-insertion counts per cell per tile

## How to apply

Load the backed AnnData object containing fragment coordinates and invoke pp.add_tile_matrix with counting_strategy='paired_insertion' to aggregate fragment counts across non-overlapping genomic tiles (fixed intervals, typically 5 kb). The function processes paired-end fragments by counting insertions at each genomic position, then sums counts within each tile to generate a sparse count matrix with dimensions n_obs (cells) × n_vars (tiles). Verify the resulting matrix shape matches the number of cells and the expected number of tiles, and confirm that count values are non-zero and reasonably distributed across the tile-cell space (no unexpected sparsity or skew).

## Related tools

- **SnapATAC2** (Provides pp.add_tile_matrix function to generate tile-based count matrices from fragment data with paired-insertion counting strategy) — https://github.com/scverse/SnapATAC2
- **precellar** (Upstream preprocessing tool to convert raw fastq files and BAM alignments into fragment files compatible with SnapATAC2 count matrix generation) — https://github.com/regulatory-genomics/precellar
- **Python** (Host language for SnapATAC2 API and data manipulation)

## Examples

```
import snapatac2 as snap; adata = snap.read('fragments.h5ad', backed='r'); snap.pp.add_tile_matrix(adata, counting_strategy='paired_insertion'); print(adata.X.shape)
```

## Evaluation signals

- Count matrix shape (n_obs × n_vars) matches the number of cells and expected number of genomic tiles (e.g., ~600,000 tiles for 5 kb resolution across human genome).
- Matrix contains non-zero entries distributed across both cells and tiles; median non-zero count per cell is consistent with expected fragment complexity (typically 1,000–100,000 fragments per cell).
- No cells have zero counts across all tiles; no tiles have zero counts across all cells (or if present, they represent genuine biological absence, not data corruption).
- Sparsity (fraction of zero entries) is within expected range for ATAC-seq (typically 95–99% sparse); extremely dense or sparse matrices may indicate counting or filtering errors.
- Count distribution is right-skewed with a long tail, consistent with chromatin accessibility patterns (some tiles have high accessibility, most have low).

## Limitations

- Tile-based counting does not account for peak structure; accessibility hotspots may be smoothed across multiple tiles. For peak-aware analysis, use pp.make_peak_matrix instead.
- Fixed tile size (typically 5 kb) is a compromise between resolution and noise; smaller tiles increase sparsity, larger tiles sacrifice resolution. Choice should be motivated by downstream analysis goal and cell-type complexity.
- Paired-insertion counting assumes high-quality paired-end sequencing and correct fragment coordinate assignment; errors in fragment end prediction or barcode assignment will propagate into count matrix.
- SnapATAC2 scales to >10 million cells but matrix generation time and memory scale with both cell count and number of tiles; very large tile matrices may require disk-backed sparse formats.

## Evidence

- [other] SnapATAC2 provides a pp.add_tile_matrix function that generates count matrices from fragment data as part of its matrix operation workflow for single-cell ATAC-seq analysis.: "SnapATAC2 provides a pp.add_tile_matrix function that generates count matrices from fragment data as part of its matrix operation workflow for single-cell ATAC-seq analysis."
- [other] Invoke pp.add_tile_matrix with counting_strategy='paired_insertion' to quantify chromatin accessibility at fixed genomic intervals.: "Invoke pp.add_tile_matrix with counting_strategy='paired_insertion' to quantify chromatin accessibility at fixed genomic intervals."
- [other] Load backed AnnData object containing fragment data (stored in .obsm['fragment_paired'] or .obsm['fragment_single']).: "Load backed AnnData object containing fragment data (stored in .obsm['fragment_paired'] or .obsm['fragment_single'])."
- [readme] Blazingly fast preprocessing tools for BAM to fragment files conversion and count matrix generation.: "Blazingly fast preprocessing tools for BAM to fragment files conversion and count matrix generation."
- [methods] Matrix operation including pp.add_tile_matrix, pp.make_peak_matrix, pp.make_gene_matrix: "Matrix operation including pp.add_tile_matrix, pp.make_peak_matrix, pp.make_gene_matrix"