BAMDOWNSAMPLERANDOM(1)

💖 NAME 💖

bamdownsamplerandom — downsample a SAM, BAM or CRAM file ✨

so yeah, this is the manual page for bamdownsamplerandom in section 1 of the manual (General Commands Manual), and she is iconic. let's go 🫶

🦋 SYNOPSIS 🦋

bamdownsamplerandom [options]

🌸 DESCRIPTION 🌸

okay so here's the vibe: bamdownsamplerandom reads a SAM, BAM or CRAM file from standard input, randomly discards reads, and writes whatever's left to standard output in BAM format. no cap.

and bestie, the pair thing matters: for a pair of reads, either both ends get discarded or both ends get kept. never one and not the other, we don't do that here 💅

one lil heads up though — the order of reads in the output file may be different from the order in the input if the reads in the input file are not collated by their read name. so if you're side-eyeing the output like "why are you like this", that's why 😭

here are the key=value pairs you can give:

• p=<1> — the probability for a pair of reads, or a single end read, to be kept. default behaviour? everything gets kept. all of it. 🎀
• seed=<> — the seed for the random number generator. by default the current time is used, which means every run of the program picks a different subset of reads from an input file (chaotic, honestly, but that's the default). if you need the program's behaviour to be reproducible, plug in a fixed number as the random seed. periodt.
• I=<stdin> — input file name. if you don't give this option, the data is read from standard input.
• inputformat=<bam> — input file format. every version of bamtofastq comes with support for the BAM input format. if the program is in addition linked to the io_lib package, then these options are valid too:
  • bam — BAM (see http://samtools.sourceforge.net/SAM1.pdf)
  • sam — SAM (see http://samtools.sourceforge.net/SAM1.pdf)
  • cram — CRAM (see http://www.ebi.ac.uk/ena/about/cram_toolkit)
• level=<-1|0|1|9|11> — sets 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,SUPPLEMENTARY> — do not include reads in the output that have any of the given flags set. you give the flags 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 as 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. do NOT casually set disablevalidation=1. yes it can rescue your cursed broken input file, but it's a security risk — a forged input file can lead to the execution of arbitrary code. literally read that twice. 💀

• colhlog=<18> — base two logarithm of the size of the hash table used for collation. the default value is 18 and 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 hash table overflow list in bytes. the default is 128MB and should work reasonably well for most input files. please see the biobambam paper at arxiv.org/abs/1306.0836 for details.
• T=<bamdownsamplerandom_hostname_pid_time> — file name of temporary file used for collation.
• ranges=<> — coordinate ranges selected from input. this option is only available for input files in BAM format which have a corresponding index (.bai file) and if input is via file (i.e. the I argument is set). valid ranges consist either of:
  • 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)

multiple ranges are separated by space characters (e.g. ranges="chr1:10000-20000 chr1:30000-40000").

• 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.
• tmpfile=<filename> — prefix for temporary files. by default the temporary files are created in the current directory.
• outputformat=<bam> — output file format. all versions of bamsort 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 too:
  • bam — BAM (see http://samtools.sourceforge.net/SAM1.pdf)
  • sam — SAM (see http://samtools.sourceforge.net/SAM1.pdf)
  • cram — CRAM (see http://www.ebi.ac.uk/ena/about/cram_toolkit). this format is not advisable for data sorted by query name.
• O=<[stdout]> — output filename, standard output if unset.
• outputthreads=<[1]> — output helper threads, only valid for outputformat=bam.
• md5=<0|1> — md5 checksum creation for output file. this option can only be given if outputformat=bam. then 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 md5 checksum if md5=1.
• index=<0|1> — compute BAM index for output file. this option can only be given if outputformat=bam. then 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 output BAM index if index=1.
• hash=<0|1> — use hash of query name instead of a random number for selection. this makes the output depend on how random the hashes produced for the query names are, but it has the advantage of not requiring collation to keep pairs together. in contrast, the order of retained reads does not change for hash=1. 💜

👑 AUTHOR 👑

written by German Tischler.

🙈 REPORTING BUGS 🙈

report bugs to <germant@miltenyibiotec.de>

🎀 COPYRIGHT 🎀

copyright © 2009-2014 German Tischler, © 2011-2014 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. (yes, all caps, they mean it 😌)

that's the whole page bestie, hope you slayed your downsampling 🌈✨ — this is from biobambam, dated October 2014 💖🦋