Usage

Input BAMs should be collated by read name (e.g. samtools collate) so that all alignments of a read are processed together.

Quick start

C++

# Genome-aligned, name-collated BAM + annotation -> transcriptome-coordinate BAM.
# The input BAM is positional; -G/--guide is the annotation, -o/--out the output.
bramble genome.bam -G annotation.gtf -o transcriptome.bam

# Long reads: enable long-read evaluation (--lr), and pass the genome FASTA
# (-S/--genome) to recover soft-clipped ends.
bramble genome.bam -G annotation.gtf -o transcriptome.bam \
   --lr -S genome.fa -p 16

Rust

# Genome-aligned, name-collated BAM + annotation -> transcriptome-coordinate BAM.
# The input BAM is positional; -G/--guide is the annotation, -o/--out the output.
bramble-rs genome.bam -G annotation.gtf -o transcriptome.bam

# Long reads: enable long-read evaluation (--lr), and pass the genome FASTA
# (-S/--genome) to recover soft-clipped ends.
bramble-rs genome.bam -G annotation.gtf -o transcriptome.bam \
    --lr -S genome.fa -p 16

Full option reference

bramble <in.bam> [-G <annotation.gtf>] [-o <out.bam>] [-p <UINT>] [-S <genome.fa>]
 [--help] [--version] [--quiet] [--fr] [--rf] [--lr] [--lr-hq] [--strict]
 [--max-soft-clip <UINT>] [--max-junction-insertion <UINT>] [--max-junction-deletion <UINT>]
 [--max-error-exon <UINT>] [--similarity-threshold <FLOAT>]

Option	Description
`--help`	print the usage message and exit
`--version`	print just the version and exit
`--quiet`	turn off verbose mode (log bundle processing details)
`--fr`	assume stranded library (first-strand, read2 sense)
`--rf`	assume stranded library (second-strand, read1 sense)
`--lr`	preset: alignments are from long reads
`--lr-hq`	preset: alignments are from high-quality long reads
`--strict`	force strict boundary adherence
`--max-soft-clip`	maximum added soft clip
`--max-junction-insertion`	maximum allowed insertion at any splice junction
`--max-junction-deletion`	maximum allowed deletion at any splice junction
`--max-error-exon`	maximum allowed size of an insertion or deletion of an entire exon, for sequencing technologies that produce long indels
`--similarity-threshold`	candidate transcripts with similarity scores above this threshold are kept
`-G, --guide <file>`	reference annotation for guiding alignment projection (GTF/GFF)
`-S, --genome <file>`	genome sequence file for long-read clip rescue (FASTA format)
`-o, --out <file>`	output path/file name for the projected alignments (default: stdout)
`-p <int>`	number of threads (CPUs) to use (default: 1)

Rust library

bramble-rs is the Rust library at the core of bramble. This crate is I/O-free: it has no dependency on htslib / rust-htslib. You bring the alignments (from rust-htslib, noodles, minimap2-rs, etc.) as plain structs, and bramble returns projected alignments as plain structs. The companion bramble-cli crate wraps this library in a BAM-in/BAM-out command-line tool (the bramble-rs executable).

See the bramble-rs README for usage examples.