edit-sam: edit and analyze SAM/BAM/CRAM files

A high-performance utility for executing arbitrary Python logic on SAM/BAM/CRAM alignment streams. It enables in-flight header modification, tag injection, filtering, and sidecar metadata extraction without breaking unix pipes.

Key Features

• Hot-Injected Logic: Execute multiple Python statements on every pysam.AlignedSegment object.
• Persistent Namespace: Variables created in one alignment iteration persist to the next, allowing for stateful counters or cross-read comparisons.
• Header Provenance: Automatically appends a @PG line to the SAM header containing the exact command-line execution string for reproducibility.
• Zero-Copy Sidecars: Export specific Python variables to a JSON Lines (JSONL) file for downstream analysis without re-parsing the BAM.
• Performance Optimized: Native support for htslib multi-threading and uncompressed BAM streaming (-u) for high-speed piping.

Gemini said BAM Stream Processor (stream.py) A high-performance utility for executing arbitrary Python logic on SAM/BAM/CRAM alignment streams. It enables in-flight header modification, tag injection, filtering, and sidecar metadata extraction without breaking unix pipes.

Key Features Hot-Injected Logic: Execute multiple Python statements on every pysam.AlignedSegment object.

Persistent Namespace: Variables created in one alignment iteration persist to the next, allowing for stateful counters or cross-read comparisons.

Header Provenance: Automatically appends a @PG line to the SAM header containing the exact command-line execution string for reproducibility.

Zero-Copy Sidecars: Export specific Python variables to a JSON Lines (JSONL) file for downstream analysis without re-parsing the BAM.

Performance Optimized: Native support for htslib multi-threading and uncompressed BAM streaming (-u) for high-speed piping.

Installation

pip install pysam click edit-sam

Usage Syntax

edit-sam [OPTIONS] "COMMAND_1" "COMMAND_2" ...

Core Options

• -i, --input: Path to input (defaults to stdin).
• -o, --output: Path to output (defaults to stdout).
• -O, --output-format: Force SAM, BAM, or CRAM.
• -u, --uncompressed: Disable compression for faster piping.
• -l, --locals-out: Path to write exported variables as JSONL.
• -k, --export-key: Variable names to include in the JSONL output.

Examples

1. Composite Tag Injection

Concatenate CB and UB tags into a single XZ tag for multi-factor deduplication.

edit-sam -i in.bam -o out.bam \
"cb = seg.get_tag('CB') if seg.has_tag('CB') else ''" \
"ub = seg.get_tag('UB') if seg.has_tag('UB') else ''" \
"seg.set_tag('XZ', f'{cb}-{ub}') if cb and ub else None"

2. QC Metrics Extraction

Extract mapping quality to a sidecar file.

edit-sam -i in.bam -l mq_report.json -k all_mqs \
"if 'all_mqs' not in locals(): all_mqs = []" \
"all_mqs.append(seg.mapping_quality)" \

3. Regex Read Filtering

Use the built-in re module to modify flags based on read-name patterns.

edit-sam -i in.bam -o - -u \
"if re.search(r'^[A-Z]00', seg.query_name): seg.is_qcfail = True"