Fragment file validation

fragment-file-validation

Summary

Validate that BAM-to-fragment file conversion produced a correctly formatted, non-empty compressed fragment file (BED.gz or .zst) with all required fields and QC metrics. This skill ensures data integrity before downstream analysis in SnapATAC2 single-cell ATAC-seq pipelines.

When to use

After invoking pp.make_fragment_file to convert a coordinate-sorted BAM file (e.g., from 10X ATAC or standard alignment) into a compressed fragment file. Use this skill to confirm the output file exists, is non-empty, contains valid BED format fields, and has computable QC metrics (duplication rate, read counts) before proceeding to matrix generation or downstream clustering.

When NOT to use

• Input is already a count matrix or peak-by-cell matrix (use directly for clustering/embedding, not fragment validation)
• Fragment file was generated by an external tool without BAM input (validation logic may differ; consult that tool's QC standards)
• Input is uncoordinate-sorted or contains unmapped reads (pre-filter or re-sort BAM before calling pp.make_fragment_file)

Inputs

• coordinate-sorted BAM file (e.g., from 10X ATAC sequencing or standard genomic alignment)
• SnapATAC2 AnnData object or file path for output destination

Outputs

• compressed fragment file (BED.gz or .zst format)
• fragment file with columns: chrom, start, end, barcode, count
• QC metrics: duplication rate per barcode, read count per barcode

How to apply

Decompress and inspect the output fragment file (BED.gz or .zst format) to verify it contains the expected four or five columns: chrom (chromosome), start (0-based start coordinate), end (end coordinate), barcode (cell barcode), and count (fragment count or quality metric). Check that the file is non-empty (contains at least header or data rows) and that all chromosomes and barcodes are valid. Compute or retrieve QC metrics including duplication rate (fraction of duplicate fragments per barcode) and total read counts per cell barcode, and confirm these values are reasonable (typically duplication rates < 50% for high-quality ATAC libraries). Validate that coordinates are sorted and non-overlapping within expected genomic ranges. If using 10X BAM input, confirm source='10x' parameter was set during pp.make_fragment_file invocation to ensure correct barcode extraction.

Related tools

• SnapATAC2 (Python/Rust package providing pp.make_fragment_file for BAM-to-fragment conversion and pp.import_fragments for fragment file loading and validation) — https://github.com/scverse/SnapATAC2
• precellar (Universal single-cell preprocessing package that outputs fragment files (.tsv.zst) for ATAC modalities; can serve as alternative BAM-to-fragment conversion pipeline) — https://github.com/regulatory-genomics/precellar

Examples

import snapatac2 as snap; import pandas as pd; frag = snap.pp.import_fragments('fragments.tsv.zst'); print(f'Total fragments: {len(frag)}'); print(f'Columns: {frag.columns.tolist()}'); print(f'Barcodes: {frag.barcode.nunique()}')

Evaluation signals

• Output file is non-empty and readable (e.g., zstd -d fragments.tsv.zst | head returns data)
• Fragment file contains exactly 4–5 whitespace-delimited columns matching BED format: chrom, start, end, barcode, count (or quality)
• All chromosome names match the reference genome used during alignment (e.g., chr1–chr22, chrX, chrY for human GRCh38)
• Coordinates are 0-based, start < end, and fall within expected genomic ranges for the reference
• QC metrics (duplication rate, read count per barcode) are computed and accessible; duplication rate typically < 50% and total reads per barcode > 0

Limitations

• Validation assumes input BAM was generated by a standard aligner (e.g., BWA, STAR) with valid coordinate sorting; unsorted or corrupted BAM files will produce invalid fragment files that validation may not fully catch.
• 10X barcode extraction (source='10x' parameter) is platform-specific; non-10X barcodes require custom parameters and validation logic may differ.
• QC metrics (duplication rate) are sensitive to sequencing depth and library complexity; high duplication rates may be expected in shallow or PCR-amplified libraries and do not necessarily indicate failure.
• Fragment file validation does not assess biological quality (e.g., TSS enrichment, FRiP score, or peak calling success), which are downstream metrics in the full SnapATAC2 pipeline.

Evidence

• [other] Generate fragment file output in compressed format (BED.gz or zst) containing fragment coordinates, cell barcodes, and quality metrics.: "Generate fragment file output in compressed format (BED.gz or zst) containing fragment coordinates, cell barcodes, and quality metrics."
• [other] Validate that the output file is non-empty and contains expected BED format fields (chrom, start, end, barcode, count).: "Validate that the output file is non-empty and contains expected BED format fields (chrom, start, end, barcode, count)."
• [other] Verify output file integrity and confirm QC metrics (duplication rate, read counts) are computed and accessible.: "Verify output file integrity and confirm QC metrics (duplication rate, read counts) are computed and accessible."
• [methods] BAM/Fragment file processing with pp.make_fragment_file, pp.import_fragments: "BAM/Fragment file processing with pp.make_fragment_file, pp.import_fragments"
• [intro] 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."