How bio-cr/bam-filter works
Purpose and CLI Entry Point
bam-filter is a Crystal command-line stream filter for SAM, BAM, and CRAM alignment records. Users supply Ruby expressions that decide whether each record is retained. The executable entry point and command orchestration are in:
• src/bam-filter.cr
• src/ke.cr
Processing Pipeline
The main flow is: parse CLI options → open alignment input → configure output format/reference/threads → load optional Ruby scripts → evaluate the expression for every record → write retained records with an updated header. Input and output may be standard streams or paths, with BAM as the default output mode and explicit SAM/CRAM modes.
Primary implementation boundary:
• src/bam-filter.cr
Embedded Ruby Evaluation Boundary
Filtering logic is intentionally delegated from Crystal to embedded mruby through Anyolite. The application exposes alignment-record fields, SAM flags, and auxiliary tags as Ruby-visible values, then applies Ruby truthiness plus the documented numeric-zero behavior to decide retention. -r/--require scripts are loaded before the per-record expression, enabling reusable domain filters.
Relevant code:
• src/bam-filter.cr
• src/ke.cr
Alignment Format and Header Handling
The tool operates on HTS alignment formats: SAM, BAM, and CRAM. CRAM output requires a FASTA reference, while thread count is passed through as a runtime option for underlying alignment I/O. Output generation also controls whether a @PG program-header line is appended, making header mutation part of the output boundary.
Relevant paths:
• src/bam-filter.cr
• test/moo.bam
• test/moo.cram
Record Data Model Exposed to Expressions
Each record is mapped into a compact Ruby-facing API: core mapping fields (chr, pos, mapq, mate coordinates, etc.), boolean flag predicates, and tag_XX auxiliary-tag access. Tags include scalar values and numeric B arrays; missing tags become nil. This conversion layer is architecture-defining because it isolates native alignment representation from user-authored Ruby.
Relevant paths:
• src/ke.cr
• test/array-tags.sam
Build, Distribution, and Runtime Environment
Crystal is the primary runtime and build target, with dependencies declared through the Crystal shard ecosystem. The repository supports native builds via Make, containerized execution/build through Docker, and GitHub Actions CI/build workflows. Releases are intended to distribute a standalone command-line binary rather than a web service.
Relevant paths:
• shard.yml
• Makefile
• Dockerfile
• .github/workflows/ci.yml
• .github/workflows/build.yml
Verification Assets
The test corpus covers SAM/BAM/CRAM reading, reference-backed CRAM handling, expression thresholds, Ruby helper loading, and array-tag behavior. Tests act as compatibility constraints for the Ruby-to-record data boundary and multi-format pipeline.
Relevant paths:
• test.sh
• test/filters.rb
• test/thresholds.rb
• test/moo.fa
Main entry points: bam-filter.cr CLI options · test.sh Format and expression tests · Makefile Native build · ke.cr Anyolite bridge
Components 19
CLI runtime
- bam-filter CLI · Parses options and orchestrates record filtering.
src/bam-filter.cr - CLI options · Selects input/output, format, reference, threads, scripts, and expression.
src/bam-filter.cr - Record filter loop · Evaluates every record and writes retained records.
src/bam-filter.cr
Embedded Ruby
- Anyolite bridge · Maps native records into Ruby-visible values.
src/ke.cr - Required Ruby scripts · Reusable filters loaded before the expression.
src/bam-filter.cr - Filter expression · Ruby truthiness and numeric-zero behavior determine retention.
src/bam-filter.cr - Ruby record API · Core fields, flag predicates, scalar tags, and B arrays.
src/ke.cr
Alignment I/O
- SAM/BAM/CRAM input · Reads a path or standard input.
src/bam-filter.cr - FASTA reference · Required for CRAM output.
src/bam-filter.cr - Alignment output · Writes a path or standard output; BAM is the default.
src/bam-filter.cr - Output header · Optionally appends a @PG program line.
src/bam-filter.cr
Build & delivery
- Crystal dependencies
shard.yml - Native build
Makefile - Container build/runtime
Dockerfile - CI verification
.github/workflows/ci.yml - Binary release build · Produces the standalone command binary.
.github/workflows/build.yml
Other components
- Format and expression tests · Compatibility coverage for formats, scripts, thresholds, and tags.
test.sh - Ruby test helpers
test/filters.rb - CRAM reference fixture
test/moo.fa
Connections 20
- bam-filter CLI → CLI options: parses
- CLI options → SAM/BAM/CRAM input: opens
- CLI options → Alignment output: configures format and threads
- CLI options → Required Ruby scripts: loads -r scripts
- SAM/BAM/CRAM input → Record filter loop: records
- Record filter loop → Anyolite bridge: projects record
- Anyolite bridge → Ruby record API: exposes
- Required Ruby scripts → Filter expression: extends evaluation context
- Ruby record API → Filter expression: evaluated against
- Filter expression → Record filter loop: retention decision
- Record filter loop → Alignment output: retained records
- Output header → Alignment output: writes updated header
- FASTA reference → Alignment output: required for CRAM
- Crystal dependencies → Native build: resolves dependencies
- Native build → bam-filter CLI: builds binary
- Container build/runtime → bam-filter CLI: runs/builds
- CI verification → Format and expression tests: runs
- Binary release build → Native build: builds
- Format and expression tests → Ruby test helpers: loads
- Format and expression tests → CRAM reference fixture: uses for CRAM