Bam To Fragment File Conversion

BAM-to-fragment-file conversion

Summary

Convert coordinate-sorted BAM files into compressed fragment files (BED.gz or .zst format) containing fragment coordinates, cell barcodes, and quality metrics. This preprocessing step is essential for downstream single-cell ATAC-seq analysis in SnapATAC2.

When to use

When you have coordinate-sorted BAM files from single-cell ATAC-seq experiments (e.g., 10X Genomics scATAC-seq) and need to generate a compressed fragment file for efficient downstream analysis. Use this step before matrix generation, clustering, or peak calling in SnapATAC2.

When NOT to use

• Input BAM file is not coordinate-sorted; use samtools sort -c to validate or re-sort first.
• Fragment file already exists and has been validated; re-running is redundant unless BAM has been re-aligned.
• Working with RNA-seq or other modalities that do not generate fragment-level data (use pp.import_fragments for pre-existing fragment files instead).

Inputs

• coordinate-sorted BAM file
• BAM file with cell barcode information in header (for 10X or tagged BAM)

Outputs

• compressed fragment file (BED.gz or .zst format)
• fragment coordinates with cell barcodes and quality metrics

How to apply

Load the coordinate-sorted BAM file and invoke pp.makefragmentfile with source='10x' if the input is a 10X BAM file, or with default settings for standard BAM inputs. The function processes alignments, extracts fragment coordinates (chromosome, start, end), assigns cell barcodes from the BAM header, and computes quality metrics including duplication rate. Output is generated in compressed format (BED.gz or zst) with standard BED fields plus barcode and count columns. Validate output by confirming the file is non-empty, contains properly formatted BED columns, and that QC metrics (duplication rate, read counts per cell) are accessible for downstream QC decisions.

Related tools

• SnapATAC2 (Python/Rust framework providing pp.makefragmentfile function for BAM-to-fragment conversion with built-in quality metrics and barcode extraction) — https://github.com/scverse/SnapATAC2
• precellar (Alternative universal preprocessing package that automates BAM-to-fragment conversion for multiple single-cell genomics platforms via alignment and fragment file generation) — https://github.com/regulatory-genomics/precellar
• samtools (Utility for BAM file validation, sorting, and inspection before fragment file conversion)

Examples

import snapatac2 as sa; sa.pp.make_fragment_file('sorted.bam', output='fragments.tsv.zst', source='10x')

Evaluation signals

• Output file is non-empty and has expected file size relative to input BAM (typically 10–30% of BAM size after compression).
• Fragment file contains all mandatory BED format fields: chromosome, start position, end position, cell barcode, and read count (5 columns minimum).
• QC metrics (duplication rate, total fragment count, fragments per cell) are computed and accessible; median fragments per cell is > 0.
• Barcode distribution across fragments is non-uniform and reflects expected cell count (e.g., 500–10,000 unique barcodes for 10X experiment).
• File integrity check: fragment file can be read back into SnapATAC2 using pp.import_fragments without errors; no corrupted records.

Limitations

• Requires BAM file to be coordinate-sorted; name-sorted or unsorted BAM will produce incorrect or incomplete output.
• Quality metrics (duplication rate, mapping quality) depend on BAM flags and tags being correctly set during alignment; unreliable if input BAM is from non-standard pipelines.
• Performance scales linearly with BAM file size; very large BAM files (>100 GB) may require sufficient disk space and RAM for intermediate processing.
• Cell barcode extraction assumes standard barcoding convention (e.g., 10X CB tag in BAM); non-standard barcode formats or missing tags will result in lost or misassigned barcodes.

Evidence

• [intro] BAM-to-fragment-file conversion is a preprocessing step in SnapATAC2: "Blazingly fast preprocessing tools for BAM to fragment files conversion and count matrix generation."
• [methods] pp.makefragmentfile is the primary function for converting BAM to fragment files: "BAM/Fragment file processing with pp.makefragmentfile, pp.import_fragments"
• [other] Output should be validated as compressed BED format with expected fields: "Generate fragment file output in compressed format (BED.gz or zst) containing fragment coordinates, cell barcodes, and quality metrics."
• [other] Workflow includes QC metric computation and file validation: "Verify output file integrity and confirm QC metrics (duplication rate, read counts) are computed and accessible."
• [other] 10X BAM files require source parameter specification: "Invoke pp.makefragmentfile with source='10x' if the input is a 10X BAM file, or with default settings for standard BAM inputs."

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HolobiomicsLab
• Source: HolobiomicsLab/asb-skill-collections
• License: Apache-2.0
• Homepage: https://holobiomicslab.cnrs.fr

Install and usage instructions live in the source repository linked above.