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.