Metadata-Version: 2.3
Name: edit-sam
Version: 0.1.0
Summary: Streaming editor for SAM, BAM, and CRAM files.
License: MIT
Author: Ben Skubi
Author-email: skubi@ohsu.edu
Requires-Python: >=3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: click
Requires-Dist: pysam
Description-Content-Type: text/markdown

# 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
```bash
pip install pysam click edit-sam
```

## Usage Syntax

```bash
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.

```bash
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.

```bash
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.

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