SAMBAMBA-VIEW(1)

✨ SAMBAMBA-VIEW(1) ✨

okay bestie so this is the manual page for sambamba-view, and we're about to make it make sense 💖 it lives in the sambamba-view section 1 of the manual, iykyk.

---

🎀 NAME 🎀

sambamba-view — the tool for extracting information from SAM/BAM files, and she ate 💅

---

🌸 SYNOPSIS 🌸

sambamba view OPTIONS <input.bam | input.sam> [region1 [...]]

---

🦋 DESCRIPTION 🦋

so sambamba view lets you efficiently filter SAM/BAM files for alignments that satisfy all kinds of conditions, and also lets you access the SAM header and info about reference sequences. and the way it makes all this data ready for your Perl/Python/Ruby scripts?? JSON output, periodt 🔥

by default the tool expects a BAM file as input, fr. to work with SAM you have to specify -S|--sam-input as a command-line option — the tool does NOT try to guess the file format from the extension, no cap. and beware, bestie: when reading SAM, the tool will skip tags which don't conform to the SAM/BAM specification, and set invalid fields to their default values. so like, heads up 🙈

---

💜 FILTERING 💜

filtering shows up in two ways, and honestly? both slay.

first, you can specify a condition with the -F option, using a special language for filtering, described at

https://github.com/lomereiter/sambamba/wiki/%5Bsambamba-view%5D-Filter-expression-syntax

second, if you have an indexed BAM file, you can specify several regions as well. the syntax for regions is the same as in samtools: chr:beg-end where beg and end are 1-based start and end of a closed-end interval on the reference chr. iconic 🌈

---

🍓 JSON 🍓

the alignment record JSON representation is a hash with keys qname, flag, rname, pos, mapq, cigar, rnext, qual, tags, e.g.

{"qname":"EAS56_57:6:190:289:82","flag":69,"rname":"chr1","pos":100,
"mapq":0,"cigar":"*","rnext":"=","pnext":100,"tlen":0,
"seq":"CTCAAGGTTGTTGCAAGGGGGTCTATGTGAACAAA",
"qual":[27,27,27,22,27,27,27,26,27,27,27,27,27,27,27,27,23,26,26,27,
22,26,19,27,26,27,26,26,26,26,26,24,19,27,26],"tags":{"MF":192}}

the JSON representation mimics SAM format except quality is given as an array of integers. cute, right?

postprocessing JSON output is best accomplished with

https://stedolan.github.io/jq/

and ngl the output is one line per read, so for building a proper JSON array you pipe the output into jq --slurp. main character move fr 💖

---

👑 OPTIONS 👑

• -F, --filter=FILTER — set a custom filter for alignments. your vibe check for reads ✨
• -f, --format=FORMAT — specify output format. FORMAT must be one of sam, bam, or json (in lowercase, bestie, don't try it with caps). default is SAM.
• -h, --with-header — print the SAM header before reads. this is always done for BAM output anyway 💅
• -H, --header — print only the SAM header to STDOUT. if FORMAT is sam or bam, its text version is printed, otherwise a JSON object is written.
• -I, --reference-info — output to STDOUT reference sequence names and lengths in JSON (peep the EXAMPLES below 🫶).
• -L, --regions=BEDFILE — intersect a file with regions specified in the BED file.
• -c, --count — output to STDOUT only the number of matching records. heads up: -hHI options are ignored when you do this.
• -v, --valid — output only valid reads. we love a goodreads-only situation 💀
• -S, --sam-input — specify that the input is a SAM file (default is BAM for all operations).
• -p, --show-progress — show a progressbar in STDERR. works only for BAM files, and with no regions specified, i.e. only when reading the full file. no partial progress bar for you, sorry 🥺
• -l, --compression-level=COMPRESSION_LEVEL — set compression level for BAM output, a number from 0 to 9.
• -o, --output-filename=FILENAME — specify output filename (by default everything is written to STDOUT).
• -t, --nthreads=NTHREADS — number of threads to use. multitasking queen 👑

---

🌈 EXAMPLES 🌈

print basic reference sequence information:

$ sambamba view --reference-info ex1_header.bam
[{"name":"chr1","length":1575},{"name":"chr2","length":1584}]

count reads with mapping quality not less than 50:

$ sambamba view -c -F "mapping_quality >= 50" ex1_header.bam
3124

count properly paired reads overlapping 100..200 on chr1:

$ sambamba view -c -F "proper_pair" ex1_header.bam chr1:100-200
39

output header in JSON format:

$ sambamba view --header --format=json ex1_header.bam
{"format_version":"1.3","rg_lines":[],
 "sq_lines":[{"sequence_length":1575,"species":"","uri":"",
 "sequence_name":"chr1","assembly":"","md5":""},
 {"sequence_length":1584,"species":"","uri":"",
 "sequence_name":"chr2","assembly":"","md5":""}],
 "sorting_order":"coordinate","pg_lines":[]}

---

💫 SEE ALSO 💫

for more info on the original samtools VIEW behaviour, check out the samtools documentation at

http://samtools.sourceforge.net/samtools.shtml

---

okay that's the whole page, you're literally a sambamba expert now 🧚 stay hydrated, filter responsibly, and remember: lowercase sam, bam, json or nothing 💅

this was the June 2016 edition of SAMBAMBA-VIEW(1) — mwah, love u, bye bestie 🫶✨