bam-filter

Filter BAM, CRAM, and SAM records with Ruby expressions.

bam-filter is a Crystal command-line tool inspired by Brent Pedersen's Nim-based bam-filter. Expressions are evaluated with embedded mruby via Anyolite.

Installation

Download the binary from the GitHub Release.

From source:

git clone https://github.com/bio-cr/bam-filter
cd bam-filter
make
sudo make install

Usage

Usage: bam-filter [options] <bam_file>
    -e, --expression EXPR            eval code
    -r, --require PATH               Load Ruby script file before evaluating expression
    -o, --output PATH                Write output to FILE [standard output]
    -f, --fasta FASTA                Reference sequence FASTA FILE [null]
    -S, --sam                        Output SAM
    -b, --bam                        Output BAM
    -C, --cram                       Output CRAM (requires -f)
    -t, --threads NUM                Number of threads to use [0]
    --no-PG                          Do not add @PG line to the header
    -h, --help                       Show this help
    -v, --version                    Show version number

Examples

Write SAM records on chromosome 1 after position 200 with an AS tag greater than 35:

bam-filter -S -e 'chr == "chr1" && pos > 200 && tag_AS && tag_AS > 35' input.bam

Write BAM output:

bam-filter -e 'mapq >= 30 && !duplicate' -o filtered.bam input.bam

Write CRAM output:

bam-filter -C -f reference.fa -e 'proper_pair && !unmapped' -o filtered.cram input.bam

Load Ruby helper scripts before expression evaluation:

bam-filter -r helpers.rb -r filters.rb -e 'keep_record(mapq, tag_AS)' -o filtered.bam input.bam

Expressions

Expressions use Ruby syntax. A record is kept unless the final expression value is false, nil, numeric 0, or numeric 0.0.

Available fields:

name flag chr pos start stop mapq mchr mpos isize

Available flag booleans:

paired proper_pair unmapped mate_unmapped reverse mate_reverse
read1 read2 secondary qcfail duplicate supplementary

Auxiliary tags are available as tag_XX, where XX is a two-character SAM tag. Integer, float, string, character, and numeric B array tags can be used from Ruby expressions. Missing tags evaluate to nil, so guard comparisons explicitly:

bam-filter -e 'tag_AS && tag_AS > 35' input.bam

Array tags are exposed as Ruby arrays:

bam-filter -e 'tag_XB && tag_XB[0] == 1 && tag_XB.include?(3)' input.bam

Development

make
make test