BAMCOLLATE2(1)

📦 version 2.0.185, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 BAMCOLLATE2 💖

okay so bestie, gather round, because bamcollate2 from the General Commands Manual is literally about to change your whole pipeline 💅 and yes she is that girl.

bamcollate2 — collate reads in a SAM, BAM or CRAM file by name 🦋

✨ SYNOPSIS ✨

bamcollate2 [options]

🌸 DESCRIPTION 🌸

so like, bamcollate2 reads a SAM, BAM or CRAM file from standard input, collates the reads/alignments it finds by name, and writes the whole thing back out to standard output in BAM format. no cap. that's the vibe. 🫶

here are the key=value pairs you can hand her:

  • collate=<0|1|2|3> — the big one, the main character. valid values are:
    • 3 — collate read pairs and attach post ranks (that's the line numbers of alignments in the output file) to each read. for pairs, this adds the prefix a_b_ to a pair when the first read of the pair shows up in line a and the second one in line b of the output file — e.g. the name HS5 gets changed to 20_21_HS5 for both ends if read 1 appears in line 20 and read 2 in line 21. for single end reads it adds the prefix a_ to the name, where a is the rank (line number) of the read in the output file. and the pre rank (line number in the input file) is attached to each read by putting it in the zz auxiliary field as an eight byte number array, similar to the functionality of bamrank. iconic behaviour honestly ✨
    • 2 — collate read pairs and attach ranks (line numbers of alignments in the source file) to each read. for pairs this adds the prefix a_b_ to a pair when the first read of the pair appears in line a and the second one in line b of the source file, e.g. the name HS5 is changed to 25_32_HS5 for both ends if read 1 appears in line 25 and read 2 in line 32. for single end reads it adds the prefix a_ to the name where a is the rank (line number) of the read in the source file.
    • 1 — collate read pairs 💞
    • 0 — do not collate, keep reads in the original order (chaos, but valid)
  • filename=<stdin> — input file name. if you don't give this option, data is read from standard input, which is the default. periodt.
  • inputformat=<bam> — input file format. all versions of bamcollate2 come with support for the BAM input format. if the program is in addition linked to the io_lib package, then these options are valid:
  • level=<-1|0|1|9|11> — set the compression level of the output BAM file. valid values are:
    • -1 — zlib/gzip default compression level
    • 0 — uncompressed
    • 1 — zlib/gzip level 1 (fast) compression
    • 9 — zlib/gzip level 9 (best) compression

and if libmaus has been compiled with support for igzip (see https://software.intel.com/en-us/articles/igzip-a-high-performance-deflate-compressor-with-optimizations-for-genomic-data), then there's one more valid value:

  • 11 — igzip compression 🚀
  • exclude=<SECONDARY> — do not include reads in the output that have any of the given flags set. the flags are given separated by commas. valid flags are:
    • PAIRED — read was paired in sequencing
    • PROPER_PAIR — read has been mapped as part of a proper pair
    • UNMAP — read was not mapped
    • MUNMAP — mate of read was not mapped
    • REVERSE — read was mapped to the reverse strand
    • MREVERSE — mate of read was mapped to the reverse strand
    • READ1 — read was first read of a pair during sequencing
    • READ2 — read was second read of a pair during sequencing
    • SECONDARY — alignment is secondary, i.e. an alternative mapping to the primary alignment in the same file
    • QCFAIL — read was marked as having failed quality control
    • DUP — read is marked as a duplicate of another read in the same file (see bammarkduplicates)
    • SUPPLEMENTARY — read is marked as supplementary alignment
  • disablevalidation=<0> — valid values are:
    • 0 — run input file validation on alignments (this is the default)
    • 1 — do not check the validity of the input file. this may help for some broken input files, but it is a security risk as it can lead to the execution of arbitrary code through a forged input file.
🚨 bestie NO. disablevalidation=1 is giving "I trust this random file with my life". it can literally execute arbitrary code from a forged input file. be so serious rn. 😭
  • colhlog=<18> — base two logarithm of the size of the hash table used for collation. the default value is 18 and it should work reasonably well for most input files. please see the biobambam paper at arxiv.org/abs/1306.0836 for details 📖
  • colsbs=<128M> — size of the hash table overflow list in bytes. the default is 128M and it should work reasonably well for most input files. please see the biobambam paper at arxiv.org/abs/1306.0836 for details ✨
  • T=<bamcollate2_hostname_pid_time> — file name of the temporary file used for collation
  • ranges=<> — coordinate ranges selected from input. this option is only available for input files in BAM and CRAM format which have a corresponding index file (.bai for BAM, .crai for CRAM) and if input is via file (i.e. the filename argument is set). valid ranges consist of either:
    • whole reference sequence — a whole reference sequence (e.g. "chr1")
    • half open interval on reference sequence — an interval on a reference sequence half open on the right (e.g. "chr1:50000" which means alignments overlapping chr1 from position 50000 to the end of chr1)
    • interval on reference sequence — an interval on a reference sequence (e.g. "chr1:50000-60000" which means alignments overlapping positions 50000 to 60000 on chr1)

for BAM input, multiple ranges are separated by space characters (e.g. ranges="chr1:10000-20000 chr1:30000-40000"). CRAM input supports a single range only. 👑

  • reference= — file name of the reference for CRAM input files. if this key is unset, then the CRAM file header will be scanned for obtaining a reference file name.
  • md5=<0|1> — md5 checksum creation for the output file. valid values are:
    • 0 — do not compute checksum. this is the default.
    • 1 — compute checksum. if the md5filename key is set, then the checksum is written to the given file. if md5filename is unset, then no checksum will be computed.
  • md5filename — file name for the md5 checksum if md5=1.
  • index=<0|1> — compute BAM index for the output file. valid values are:
    • 0 — do not compute BAM index. this is the default.
    • 1 — compute BAM index. if the indexfilename key is set, then the BAM index is written to the given file. if indexfilename is unset, then no BAM index will be computed.
  • indexfilename — file name for the BAM index if index=1.
  • readgroups — comma separated list of read group identifiers to be kept. if not given, all records will be kept. read group filtering is only available if collate=0 and collate=1 (i.e. this key is ignored for collate=2 and collate=3).
  • mapqthres — mapping quality threshold. this option is only available for collate=1 (i.e. it is ignored for collate=0 and collate>1). if this key is set, reads are kept if the mapping quality field is at least the given value. for paired end reads it is sufficient for a read or its mate to have a mapping quality above the threshold.
  • reset — reduce alignments to an unmapped state (see bamreset). this key is only valid for collate=0, collate=1 or collate=3. the default value is 0 for collate=0 and collate=1 and 1 for collate=3.
  • classes — types of alignment lines to be kept. this key is only valid for collate=1. by default all alignments are kept. the value for this key is a comma separated list consisting of a subset of the following options:
    • F — keep first mates of complete pairs
    • F2 — keep second mates of complete pairs
    • O — keep first mates of orphaned pairs (i.e. such that the other mate is not in the input file)
    • O2 — keep second mates of orphaned pairs (i.e. such that the other mate is not in the input file)
    • S — keep single end reads
  • resetheadertext — file name for replacement SAM header. by default the header of the input SAM/BAM/CRAM file is used (and filtered in case of reset=1).
  • resetaux=<0|1> — remove auxiliary fields if resetaux=1. this key is only available for reset=1. if reset=1 then the default is to remove all aux fields.
  • auxfilter=<> — comma separated list of aux tags to be kept if reset=1 and resetaux=0. if the key is not set then all tags are kept.
  • outputformat=<bam> — output file format. all versions of bamcollate2 come with support for the BAM output format. if the program is in addition linked to the io_lib package, then these options are valid:
  • O=<[stdout]> — output filename, standard output if unset.
  • outputthreads=<[1]> — output helper threads, only valid for outputformat=bam.
  • verbose=<1> — valid values are:
    • 1 — print progress report on standard error
    • 0 — do not print progress report
  • replacereadgroupnames=<> — file name containing a list of read group mappings. each line in the file corresponds to one read group ID replacement and contains two columns separated by the tab symbol (ASCII code 9). the first column contains the source identifier which will be replaced by the value of the second column in the output file. this option is only valid for collate<2. by default no read group identifier mapping is performed.

🎀 AUTHOR 🎀

written by German Tischler. we stan. 💜

😭 REPORTING BUGS 😭

report bugs to <germant@miltenyibiotec.de> — she wants to hear from you fr fr.

copyright © 2009-2015 German Tischler, © 2011-2015 Genome Research Limited. license GPLv3+: GNU GPL version 3 http://gnu.org/licenses/gpl.html

this is free software: you are free to change and redistribute it. there is NO WARRANTY, to the extent permitted by law. 🫶

and that's the whole thing bestie — this page came to you from BIOBAMBAM, dated February 2015, and honestly? she ate. go collate something iconic. 💅✨🦋

📦 where this page comes from