debian/bbmap.1

+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.8.
+.TH BBMAP "1" "March 2019" "bbmap 38.43" "User Commands"
+.SH NAME
+bbmap \- Fast and accurate splice\-aware read aligner.
+.SH SYNOPSIS
+To index:
+.IP
+.B bbmap.sh
+ref=<reference fasta>
+.P
+To map:
+.IP
+.B bbmap.sh
+in=<reads> out=<output sam>
+.P
+To map without writing an index:
+.IP
+.B bbmap.sh
+ref=<reference fasta> in=<reads> out=<output sam> nodisk
+.SH OPTIONS
+in=stdin will accept reads from standard in, and out=stdout will write to
+standard out, but file extensions are still needed to specify the format of the
+input and output files e.g. in=stdin.fa.gz will read gzipped fasta from
+standard in; out=stdout.sam.gz will write gzipped sam.
+.SS Indexing Parameters (required when building the index):
+.TP
+nodisk=f
+Set to true to build index in memory and write nothing
+to disk except output.
+.TP
+ref=<file>
+Specify the reference sequence.  Only do this ONCE,
+when building the index (unless using 'nodisk').
+.TP
+build=1
+If multiple references are indexed in the same directory,
+each needs a unique numeric ID (unless using 'nodisk').
+.TP
+k=13
+Kmer length, range 8\-15.  Longer is faster but uses more memory.
+Shorter is more sensitive.
+.IP
+If indexing and mapping are done in two steps, K should
+be specified each time.
+.TP
+path=<.>
+Specify the location to write the index, if you don't
+want it in the current working directory.
+.TP
+usemodulo=f
+Throw away ~80% of kmers based on remainder modulo a
+number (reduces RAM by 50% and sensitivity slightly).
+Should be enabled both when building the index AND
+when mapping.
+.TP
+rebuild=f
+Force a rebuild of the index (ref= should be set).
+.SS Input Parameters:
+.TP
+build=1
+Designate index to use.  Corresponds to the number
+specified when building the index.
+.TP
+in=<file>
+Primary reads input; required parameter.
+.TP
+in2=<file>
+For paired reads in two files.
+.TP
+interleaved=auto
+True forces paired/interleaved input; false forces
+single\-ended mapping. If not specified, interleaved
+status will be autodetected from read names.
+.TP
+fastareadlen=500
+Break up FASTA reads longer than this.  Max is 500 for
+BBMap and 6000 for BBMapPacBio.
+Only works for FASTA
+input (use 'maxlen' for FASTQ input).
+The default for
+\fBbbmap.sh\fR is 500, and for \fBmapPacBio.sh\fR is 6000.
+.TP
+unpigz=f
+Spawn a pigz (parallel gzip) process for faster
+decompression than using Java.
+Requires pigz to be installed.
+.TP
+touppercase=t
+(tuc) Convert lowercase letters in reads to upper case
+(otherwise they will not match the reference).
+.SS Sampling Parameters:
+.TP
+reads=\-1
+Set to a positive number N to only process the first N
+reads (or pairs), then quit.
+\fB\-1\fR means use all reads.
+.TP
+samplerate=1
+Set to a number from 0 to 1 to randomly select that
+fraction of reads for mapping. 1 uses all reads.
+.TP
+skipreads=0
+Set to a number N to skip the first N reads (or pairs),
+then map the rest.
+.SS Mapping Parameters:
+.TP
+fast=f
+This flag is a macro which sets other paramters to run
+faster, at reduced sensitivity.
+Bad for RNA\-seq.
+.TP
+slow=f
+This flag is a macro which sets other paramters to run
+slower, at greater sensitivity.
+\&'vslow' is even slower.
+.TP
+maxindel=16000
+Don't look for indels longer than this. Lower is faster.
+.IP
+Set to >=100k for RNAseq with long introns like mammals.
+.TP
+strictmaxindel=f
+When enabled, do not allow indels longer than 'maxindel'.
+.IP
+By default these are not sought, but may be found anyway.
+.TP
+tipsearch=100
+Look this far for read\-end deletions with anchors
+shorter than K, using brute force.
+.TP
+minid=0.76
+Approximate minimum alignment identity to look for.
+.IP
+Higher is faster and less sensitive.
+.TP
+minhits=1
+Minimum number of seed hits required for candidate sites.
+.IP
+Higher is faster.
+.TP
+local=f
+Set to true to use local, rather than global, alignments.
+.IP
+This will soft\-clip ugly ends of poor alignments.
+.TP
+perfectmode=f
+Allow only perfect mappings when set to true (very fast).
+.TP
+semiperfectmode=f
+Allow only perfect and semiperfect (perfect except for
+N's in the reference) mappings.
+.TP
+threads=auto
+(t) Set to number of threads desired.  By default, uses
+all cores available.
+.TP
+ambiguous=best
+(ambig) Set behavior on ambiguously\-mapped reads (with
+.IP
+multiple top\-scoring mapping locations).
+.IP
+best    (use the first best site)
+.IP
+toss    (consider unmapped)
+.IP
+random  (select one top\-scoring site randomly)
+.IP
+all     (retain all top\-scoring sites)
+.TP
+samestrandpairs=f
+(ssp) Specify whether paired reads should map to the
+same strand or opposite strands.
+.TP
+requirecorrectstrand=t
+(rcs) Forbid pairing of reads without correct strand
+orientation.
+.IP
+Set to false for long\-mate\-pair libraries.
+.TP
+killbadpairs=f
+(kbp) If a read pair is mapped with an inappropriate
+insert size or orientation, the read with the lower
+mapping quality is marked unmapped.
+.TP
+pairedonly=f
+(po) Treat unpaired reads as unmapped.  Thus they will
+be sent to 'outu' but not 'outm'.
+.TP
+rcomp=f
+Reverse complement both reads prior to mapping (for LMP
+outward\-facing libraries).
+.TP
+rcompmate=f
+Reverse complement read2 prior to mapping.
+.TP
+pairlen=32000
+Set max allowed distance between paired reads.
+.IP
+(insert size)=(pairlen)+(read1 length)+(read2 length)
+.TP
+rescuedist=1200
+Don't try to rescue paired reads if avg. insert size
+greater than this.
+Lower is faster.
+.TP
+rescuemismatches=32
+Maximum mismatches allowed in a rescued read.  Lower
+is faster.
+.TP
+averagepairdist=100
+(apd) Initial average distance between paired reads.
+.IP
+Varies dynamically; does not need to be specified.
+.TP
+deterministic=f
+Run in deterministic mode.  In this case it is good
+to set averagepairdist.
+BBMap is deterministic
+without this flag if using single\-ended reads,
+or run singlethreaded.
+.TP
+bandwidthratio=0
+(bwr) If above zero, restrict alignment band to this
+fraction of read length.
+Faster but less accurate.
+.TP
+bandwidth=0
+(bw) Set the bandwidth directly.
+fraction of read length.
+Faster but less accurate.
+.TP
+usejni=f
+(jni) Do alignments faster, in C code.
+.TP
+maxsites2=800
+Don't analyze (or print) more than this many alignments
+per read.
+.TP
+ignorefrequentkmers=t
+(ifk) Discard low\-information kmers that occur often.
+.TP
+excludefraction=0.03
+(ef) Fraction of kmers to ignore.  For example, 0.03
+will ignore the most common 3% of kmers.
+.TP
+greedy=t
+Use a greedy algorithm to discard the least\-useful
+kmers on a per\-read basis.
+.TP
+kfilter=0
+If positive, potential mapping sites must have at
+least this many consecutive exact matches.
+.SS Quality and Trimming Parameters:
+.TP
+qin=auto
+Set to 33 or 64 to specify input quality value ASCII
+offset. 33 is Sanger, 64 is old Solexa.
+.TP
+qout=auto
+Set to 33 or 64 to specify output quality value ASCII
+offset (only if output format is fastq).
+.TP
+qtrim=f
+Quality-trim ends before mapping.  Options are:"
+\&'f' (false), 'l' (left), 'r' (right), and 'lr' (both).
+.TP
+untrim=f
+Undo trimming after mapping.  Untrimmed bases will be
+soft\-clipped in cigar strings.
+.TP
+trimq=6
+Trim regions with average quality below this
+(phred algorithm).
+.TP
+mintrimlength=60
+(mintl) Don't trim reads to be shorter than this.
+.TP
+fakefastaquality=\-1
+(ffq) Set to a positive number 1\-50 to generate fake
+quality strings for fasta input reads.
+.TP
+ignorebadquality=f
+(ibq) Keep going, rather than crashing, if a read has
+out\-of\-range quality values.
+.TP
+usequality=t
+Use quality scores when determining which read kmers
+to use as seeds.
+.TP
+minaveragequality=0
+(maq) Do not map reads with average quality below this.
+.TP
+maqb=0
+If positive, calculate maq from this many initial bases.
+.SS Output Parameters:
+.TP
+out=<file>
+Write all reads to this file.
+.TP
+outu=<file>
+Write only unmapped reads to this file.  Does not
+include unmapped paired reads with a mapped mate.
+.TP
+outm=<file>
+Write only mapped reads to this file.  Includes
+unmapped paired reads with a mapped mate.
+.TP
+mappedonly=f
+If true, treats 'out' like 'outm'.
+.TP
+bamscript=<file>
+(bs) Write a shell script to <file> that will turn
+the sam output into a sorted, indexed bam file.
+.TP
+ordered=f
+Set to true to output reads in same order as input.
+Slower and uses more memory.
+.TP
+overwrite=f
+(ow) Allow process to overwrite existing files.
+.TP
+secondary=f
+Print secondary alignments.
+.TP
+sssr=0.95
+(secondarysitescoreratio) Print only secondary alignments
+with score of at least this fraction of primary.
+.TP
+ssao=f
+(secondarysiteasambiguousonly) Only print secondary
+alignments for ambiguously\-mapped reads.
+.TP
+maxsites=5
+Maximum number of total alignments to print per read.
+Only relevant when secondary=t.
+.TP
+quickmatch=f
+Generate cigar strings more quickly.
+.TP
+trimreaddescriptions=f
+(trd) Truncate read and ref names at the first whitespace,
+assuming that the remainder is a comment or description.
+.TP
+ziplevel=2
+(zl) Compression level for zip or gzip output.
+.TP
+pigz=f
+Spawn a pigz (parallel gzip) process for faster
+compression than Java.
+.TP
+machineout=f
+Set to true to output statistics in machine\-friendly
+\&'key=value' format.
+.TP
+printunmappedcount=f
+Print the total number of unmapped reads and bases.
+.IP
+If input is paired, the number will be of pairs
+for which both reads are unmapped.
+.TP
+showprogress=0
+If positive, print a '.' every X reads.
+.TP
+showprogress2=0
+If positive, print the number of seconds since the
+last progress update (instead of a '.').
+.TP
+renamebyinsert=f
+Renames reads based on their mapped insert size.
+.SS Bloom\-Filtering Parameters (bloomfilter.sh is the standalone version).
+.TP
+bloom=f
+Use a Bloom filter to ignore reads not sharing kmers
+with the reference.
+This uses more memory, but speeds
+mapping when most reads don't match the reference.
+.TP
+bloomhashes=2
+Number of hash functions.
+.TP
+bloomminhits=3
+Number of consecutive hits to be considered matched.
+.TP
+bloomk=31
+Bloom filter kmer length.
+.TP
+bloomserial=t
+Use the serialized Bloom filter for greater loading
+speed, if available.
+If not, generate and write one.
+.SS Post\-Filtering Parameters:
+.TP
+idfilter=0
+Independant of minid; sets exact minimum identity
+allowed for alignments to be printed.
+Range 0 to 1.
+.TP
+subfilter=\-1
+Ban alignments with more than this many substitutions.
+.TP
+insfilter=\-1
+Ban alignments with more than this many insertions.
+.TP
+delfilter=\-1
+Ban alignments with more than this many deletions.
+.TP
+indelfilter=\-1
+Ban alignments with more than this many indels.
+.TP
+editfilter=\-1
+Ban alignments with more than this many edits.
+.TP
+inslenfilter=\-1
+Ban alignments with an insertion longer than this.
+.TP
+dellenfilter=\-1
+Ban alignments with a deletion longer than this.
+.TP
+nfilter=\-1
+Ban alignments with more than this many ns.  This
+includes nocall, noref, and off scaffold ends.
+.SS Sam flags and settings:
+.TP
+noheader=f
+Disable generation of header lines.
+.TP
+sam=1.4
+Set to 1.4 to write Sam version 1.4 cigar strings,
+with = and X, or 1.3 to use M.
+.TP
+saa=t
+(secondaryalignmentasterisks) Use asterisks instead of
+bases for sam secondary alignments.
+.TP
+cigar=t
+Set to 'f' to skip generation of cigar strings (faster).
+.TP
+keepnames=f
+Keep original names of paired reads, rather than
+ensuring both reads have the same name.
+.TP
+intronlen=999999999
+Set to a lower number like 10 to change 'D' to 'N' in
+cigar strings for deletions of at least that length.
+.TP
+rgid=
+Set readgroup ID.  All other readgroup fields
+can be set similarly, with the flag rgXX=
+.TP
+mdtag=f
+Write MD tags.
+.TP
+nhtag=f
+Write NH tags.
+.TP
+xmtag=f
+Write XM tags (may only work correctly with ambig=all).
+.TP
+amtag=f
+Write AM tags.
+.TP
+nmtag=f
+Write NM tags.
+.TP
+xstag=f
+Set to 'xs=fs', 'xs=ss', or 'xs=us' to write XS tags
+for RNAseq using firststrand, secondstrand, or
+unstranded libraries.  Needed by Cufflinks.
+JGI mainly uses 'firststrand'.
+.TP
+stoptag=f
+Write a tag indicating read stop location, prefixed by YS:i:
+.TP
+lengthtag=f
+Write a tag indicating (query,ref) alignment lengths,
+prefixed by YL:Z:
+.TP
+idtag=f
+Write a tag indicating percent identity, prefixed by YI:f:
+.TP
+inserttag=f
+Write a tag indicating insert size, prefixed by X8:Z:
+.TP
+scoretag=f
+Write a tag indicating BBMap's raw score, prefixed by YR:i:
+.TP
+timetag=f
+Write a tag indicating this read's mapping time, prefixed by X0:i:
+.TP
+boundstag=f
+Write a tag indicating whether either read in the pair
+goes off the end of the reference, prefixed by XB:Z:
+.TP
+notags=f
+Turn off all optional tags.
+.SS Histogram and statistics output parameters:
+.TP
+scafstats=<file>
+Statistics on how many reads mapped to which scaffold.
+.TP
+refstats=<file>
+Statistics on how many reads mapped to which reference
+file; only for BBSplit.
+.TP
+sortscafs=t
+Sort scaffolds or references by read count.
+.TP
+bhist=<file>
+Base composition histogram by position.
+.TP
+qhist=<file>
+Quality histogram by position.
+.TP
+aqhist=<file>
+Histogram of average read quality.
+.TP
+bqhist=<file>
+Quality histogram designed for box plots.
+.TP
+lhist=<file>
+Read length histogram.
+.TP
+ihist=<file>
+Write histogram of insert sizes (for paired reads).
+.TP
+ehist=<file>
+Errors\-per\-read histogram.
+.TP
+qahist=<file>
+Quality accuracy histogram of error rates versus
+quality score.
+.TP
+indelhist=<file>
+Indel length histogram.
+.TP
+mhist=<file>
+Histogram of match, sub, del, and ins rates by
+read location.
+.TP
+gchist=<file>
+Read GC content histogram.
+.TP
+gcbins=100
+Number gchist bins.  Set to 'auto' to use read length.
+.TP
+gcpairs=t
+Use average GC of paired reads.
+.TP
+idhist=<file>
+Histogram of read count versus percent identity.
+.TP
+idbins=100
+Number idhist bins.  Set to 'auto' to use read length.
+.TP
+statsfile=stderr
+Mapping statistics are printed here.
+.SS Coverage output parameters (these may reduce speed and use more RAM):
+.TP
+covstats=<file>
+Per\-scaffold coverage info.
+.TP
+rpkm=<file>
+Per\-scaffold RPKM/FPKM counts.
+.TP
+covhist=<file>
+Histogram of # occurrences of each depth level.
+.TP
+basecov=<file>
+Coverage per base location.
+.TP
+bincov=<file>
+Print binned coverage per location (one line per X bases).
+.TP
+covbinsize=1000
+Set the binsize for binned coverage output.
+.TP
+nzo=t
+Only print scaffolds with nonzero coverage.
+.TP
+twocolumn=f
+Change to true to print only ID and Avg_fold instead of
+all 6 columns to the 'out=' file.
+.TP
+32bit=f
+Set to true if you need per\-base coverage over 64k.
+.TP
+strandedcov=f
+Track coverage for plus and minus strand independently.
+.TP
+startcov=f
+Only track start positions of reads.
+.TP
+secondarycov=t
+Include coverage of secondary alignments.
+.TP
+physcov=f
+Calculate physical coverage for paired reads.
+This includes the unsequenced bases.
+.TP
+delcoverage=t
+(delcov) Count bases covered by deletions as covered.
+True is faster than false.
+.TP
+covk=0
+If positive, calculate kmer coverage statistics.
+.SS Java Parameters:
+.TP
+\fB\-Xmx\fR
+This will set Java's memory usage,
+overriding autodetection.
+\fB\-Xmx20g\fR will specify 20 gigs of RAM, and \fB\-Xmx800m\fR
+will specify 800 megs.  The max is typically 85% of
+physical memory.  The human genome requires around 24g,
+or 12g with the 'usemodulo' flag.  The index uses
+roughly 6 bytes per reference base.
+.TP
+\fB\-eoom\fR
+This flag will cause the process to exit if an
+out\-of\-memory exception occurs.
+Requires Java 8u92+.
+.TP
+\fB\-da\fR
+Disable assertions.
+.SH SEE ALSO
+Please read bbmap/docs/guides/BBMapGuide.txt for more information.
+.SH AUTHOR
+Written by Brian Bushnell, from Dec. 2010 \- present
+.P
+Please contact Brian Bushnell at bbushnell@lbl.gov if you encounter
+any problems, or post at: http://seqanswers.com/forums/showthread.php?t=41057
+.P
+This manpage was written by Andreas Tille for the Debian distribution and can be used for any other usage of the program.

debian/bbmap.links

+usr/lib/debian-med/bin/bbmap.sh		usr/bin/bbmap.sh
+usr/lib/debian-med/bin/bloomfilter.sh	usr/bin/bloomfilter.sh

debian/control

@@ -6,7 +6,8 @@ Priority: optional
 Build-Depends: debhelper (>= 12~),
                javahelper,
                default-jdk,
-               libmpj-java
+               libmpj-java,
+               rename
 Standards-Version: 4.3.0
 Vcs-Browser: https://salsa.debian.org/med-team/bbmap
 Vcs-Git: https://salsa.debian.org/med-team/bbmap.git
@@ -16,6 +17,7 @@ Package: bbmap
 Architecture: all
 Depends: ${java:Depends},
          ${misc:Depends}
+Recommends: pigz
 Description: short read aligner and other bioinformatic tools
  BBMap: Short read aligner for DNA and RNA-seq data. Capable of handling
  arbitrarily large genomes with millions of scaffolds. Handles Illumina,
@@ -46,5 +48,5 @@ Description: short read aligner and other bioinformatic tools - JNI library
  PacBio, 454, and other reads; very high sensitivity and tolerant of
  errors and numerous large indels.
  .
- This package contains the architecture dependent library for the bbmap
+ This package contains the architecture dependant library for the bbmap
  tools.

debian/createmanpages

+#!/bin/sh
+MANDIR=debian
+mkdir -p $MANDIR
+
+VERSION=`dpkg-parsechangelog | awk '/^Version:/ {print $2}' | sed -e 's/^[0-9]*://' -e 's/-.*//' -e 's/[+~]dfsg$//'`
+NAME=`grep "^Description:" debian/control | sed 's/^Description: *//' | head -n1`
+PROGNAME=`grep "^Package:" debian/control | sed 's/^Package: *//' | head -n1`
+
+AUTHOR=".SH AUTHOR\nThis manpage was written by $DEBFULLNAME for the Debian distribution and
+can be used for any other usage of the program.
+"
+
+# If program name is different from package name or title should be
+# different from package short description change this here
+progname=${PROGNAME}
+help2man --no-info --no-discard-stderr --help-option=" " \
+         --name="$NAME" \
+            --version-string="$VERSION" ${progname} > $MANDIR/${progname}.1
+echo $AUTHOR >> $MANDIR/${progname}.1
+
+echo "$MANDIR/*.1" > debian/manpages
+
+cat <<EOT
+Please enhance the help2man output.
+The following web page might be helpful in doing so:
+    http://liw.fi/manpages/
+EOT

debian/lintian-overrides

+# see https://lists.debian.org/debian-med/2018/06/msg00043.html
+bbmap: script-with-language-extension usr/bin/*.*

debian/manpages

+debian/*.1

debian/rules

@@ -34,10 +34,14 @@ override_dh_install:
 	    if [ "$${scr}" != "calcmem.sh" ] ; then \
 		sed -e 's:^CP=".DIR""current/":CP=/usr/share/java/bbmap.jar:' \
 		    -e 's:source ".DIR""/calcmem.sh":source "/usr/share/$(DEB_SOURCE)/calcmem":' \
-		    $${scr} > $(PKGBINDIR)/`basename $${scr} .sh` ; \
+		    $${scr} > $(PKGBINDIR)/$${scr} ; \
 	    fi ; \
 	done
 
 override_dh_fixperms:
 	dh_fixperms
 	chmod +x $(PKGBINDIR)/*
+
+override_dh_installman:
+	dh_installman
+	rename 's/\.1$$/.sh.1/' debian/$(DEB_SOURCE)/usr/share/man/man1/*.1