.\" Man page generated from reStructuredText.
.
.TH PBBARCODE 1 "December 2015" "" ""
.SH NAME
pbbarcode \- annotate PacBio sequencing reads with barcode information
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH DESCRIPTION
.sp
The \fBpbbarcode\fP package provides
utilities for annotating individual ZMWs directly from a bas.h5 file,
emitting fast[a|q] files for each barcode, labeling alignments stored
in a cmp.h5 file, and calling consensus on small amplicons (requires
\fBpbdagcon\fP(1))
.sp
At the moment, Barcodes can be scored in two different ways:
\fBsymmetric\fP and \fBpaired\fP\&. Symmetric mode supports barcode designs
with two identical barcodes on both sides of a SMRTbell, e.g., for
barcodes (A, B), molecules are labeled as A\-\-A or B\-\-B. The \fBpaired\fP
mode supports designs with two distinct barcodes on each side of the
molecule, but neither barcode appears without its mate. The minimum
example is given with the following barcodes: (ALeft, ARight, BLeft,
BRight), where the following barcode sets are checked: ALeft\-\-ARight,
BLeft\-\-BRight.
.sp
It is important to highlight that a barcode FASTA file specifies a
list of available barcodes to evaluate. Depending on the scoring mode,
the barcodes are grouped together in different ways. For instance, in
the \fBsymmetric\fP case, the number of possible barcode outcomes are
simply the number of barcodes that are supplied to the routine in the
FASTA file (see below for usage) plus an additional \fBNULL\fP barcode
indicating that no barcode could be evaluated (denoted by:
\(aq\-\-\(aq). Labels like this (A\-\-A) are used in the final outputs. In the
\fBpaired\fP mode, the number of possible barcode outcomes are half the
number of the sequences in the FASTA file plus the \fBNULL\fP
barcode. The \fBNULL\fP barcode indicates that no attempt was made to
score the molecule or it was filtered out by the user\(aqs criteria. The
majority of cases when a molecule is not scored are related to not
observing any adapters. If a user has executed a "hot\-start" run, the
user can try the \(aq\-\-scoreFirst\(aq parameter to attempt to label the
first adapter\(aqs barcode. This increases the yield of the labeleing
procedure at the expense of some probably false positives.
.sp
The software is implemented as a standard python package. Barcodes are
labeled according to the following high\-level logic. For each
molecule, all adapters are found. For each adapter, we align (using
standard Smith\-Watterman alignment) each barcode and its reverse
complement to flanking sequence of the adapter. If two complete
flanking sequences are available, we divide by 2, else 1 if only one
flanking sequence was available (average score at adapter). This
allows the scores across adapters to be on the same scale (chimera
detection). Depending on the \fBmode\fP, we then determine which
barcode(s) are maximally scoring. We store the two maximally scoring
barcodes, the sum of their alignment scores across the adapters. The
average barcode score then can be given approximately by:
total\-score/number\-of\-adapters. At the moment, the alignment
parameters are fixed at:
.TS
center;
|l|l|.
_
T{
type
T}	T{
score
T}
_
T{
insertion
T}	T{
\-1
T}
_
T{
deletion
T}	T{
\-1
T}
_
T{
mismatch
T}	T{
\-2
T}
_
T{
match
T}	T{
2
T}
_
.TE
.SS Input and output
.SS labelZmws
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B usage: pbbarcode labelZmws [\-h] [\-\-outDir OUTDIR] [\-\-outFofn OUTFOFN]
[\-\-adapterSidePad ADAPTERSIDEPAD]
[\-\-insertSidePad INSERTSIDEPAD]
[\-\-scoreMode {symmetric,paired}]
[\-\-maxAdapters MAXADAPTERS] [\-\-scoreFirst]
[\-\-startTimeCutoff STARTTIMECUTOFF]
[\-\-nZmws NZMWS] [\-\-nProcs NPROCS]
[\-\-saveExtendedInfo]
barcode.fasta input.fofn
.UNINDENT
.sp
Creates a barcode.h5 file from base h5 files.
.INDENT 0.0
.TP
.B positional arguments:
barcode.fasta         Input barcode fasta file
input.fofn            Input base fofn
.TP
.B optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-outDir \ OUTDIR
Where to write the newly created barcode.h5 files.
(default: /home/UNIXHOME/jbullard/projects/software/bioinformatics/tools/pbbarcode/doc)
.TP
.BI \-\-outFofn \ OUTFOFN
Write to outFofn (default: barcode.fofn)
.TP
.BI \-\-adapterSidePad \ ADAPTERSIDEPAD
Pad with adapterSidePad bases (default: 4)
.TP
.BI \-\-insertSidePad \ INSERTSIDEPAD
Pad with insertSidePad bases (default: 4)
.UNINDENT
.INDENT 7.0
.TP
.B \-\-scoreMode {symmetric,paired}
The mode in which the barcodes should be scored.
(default: symmetric)
.UNINDENT
.INDENT 7.0
.TP
.BI \-\-maxAdapters \ MAXADAPTERS
Only score the first maxAdapters (default: 20)
.TP
.B \-\-scoreFirst
Whether to try to score the leftmost barcode in a
trace. (default: False)
.TP
.BI \-\-startTimeCutoff \ STARTTIMECUTOFF
Reads must start before this value in order to be
included when scoreFirst is set. (default: 10.0)
.TP
.BI \-\-nZmws \ NZMWS
Use the first n ZMWs for testing (default: \-1)
.TP
.BI \-\-nProcs \ NPROCS
How many processes to use (default: 8)
.TP
.B \-\-saveExtendedInfo
Whether to save extended information tothe barcode.h5
files; this information is useful for debugging and
chimera detection (default: False)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fBlabelZmws\fP command takes an input.fofn representing a set of
bas.h5 files to operate on. Additionally, it takes a barcode.fasta
file. Depending on \fBscoreMode\fP, the FASTA file will be processed in
different ways. Specifically, in \fBpaired\fP mode, each two consecutive
barcodes in the file are considered a set.
.sp
The parameters, \fBadapterSidePad\fP and \fBinsertSidePad\fP represents
how many bases should be considered on each side of the putative
barcode. These parameters are constrained such that:
\fB|adapterSidePad| + |insertSidePad| + |barcode| < 65\fP\&.
.sp
Users have the option to specify a different output location
for the various outputs. Specifically, for each bas.h5 file in
input.fofn, a bc.h5 (barcode hdf5) file is generated. These files are
listed in the file \fBoutFofn\fP which is typically just called
\fBbarcode.fofn\fP\&. See below for a description of the barcode hdf5
file.
.SS labelAlignments
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B usage: pbbarcode labelAlignments [\-h]
[\-\-minAvgBarcodeScore MINAVGBARCODESCORE]
[\-\-minNumBarcodes MINNUMBARCODES]
[\-\-minScoreRatio MINSCORERATIO]
barcode.fofn aligned_reads.cmp.h5
.UNINDENT
.sp
Adds information about barcode alignments to a cmp.h5 file from a previous
call to "labelZmws".
.INDENT 0.0
.TP
.B positional arguments:
barcode.fofn          input barcode fofn file
aligned_reads.cmp.h5  cmp.h5 file to add barcode labels
.TP
.B optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-minAvgBarcodeScore \ MINAVGBARCODESCORE
ZMW Filter: exclude ZMW if average barcode score is
less than this value (default: 0.0)
.TP
.BI \-\-minNumBarcodes \ MINNUMBARCODES
ZMW Filter: exclude ZMW if number of barcodes observed
is less than this value (default: 1)
.TP
.BI \-\-minScoreRatio \ MINSCORERATIO
ZMW Filter: exclude ZMWs whose best score divided by
the 2nd best score is less than this ratio (default:
1.0)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fBlabelAlignments\fP command takes as input a barcode.fofn computed
from a call to \fBlabelZMWs\fP and a cmp.h5 file where the barcode
information is written to. See below for a description of the cmp.h5
file additions.
.SS emitFastqs
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B usage: pbbarcode emitFastqs [\-h] [\-\-outDir output.dir] [\-\-subreads]
[\-\-unlabeledZmws] [\-\-trim TRIM] [\-\-fasta]
[\-\-minMaxInsertLength MINMAXINSERTLENGTH]
[\-\-hqStartTime HQSTARTTIME]
[\-\-minReadScore MINREADSCORE]
[\-\-minAvgBarcodeScore MINAVGBARCODESCORE]
[\-\-minNumBarcodes MINNUMBARCODES]
[\-\-minScoreRatio MINSCORERATIO]
input.fofn barcode.fofn
.UNINDENT
.sp
Takes a bas.h5 fofn and a barcode.h5 fofn and produces a fast[a|q] file for
each barcode.
.INDENT 0.0
.TP
.B positional arguments:
input.fofn            input base or CCS fofn file
barcode.fofn          input barcode.h5 fofn file
.TP
.B optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.UNINDENT
.INDENT 7.0
.TP
.B \-\-outDir output.dir   output directory to write fastq files (default: /home/
UNIXHOME/jbullard/projects/software/bioinformatics/too
ls/pbbarcode/doc)
.UNINDENT
.INDENT 7.0
.TP
.B \-\-subreads
whether to produce fastq files for the subreads;the
default is to use the CCS reads. This option
onlyapplies when input.fofn has both consensus and raw
reads,otherwise the read type from input.fofn will be
returned. (default: False)
.TP
.B \-\-unlabeledZmws
whether to emit a fastq file for the unlabeled ZMWs.
These are the ZMWs where no adapters are found
typically (default: False)
.TP
.BI \-\-trim \ TRIM
trim off barcodes and any excess constant sequence
(default: 20)
.TP
.B \-\-fasta
whether the files produced should be FASTA files
asopposed to FASTQ (default: False)
.TP
.BI \-\-minMaxInsertLength \ MINMAXINSERTLENGTH
ZMW Filter: exclude ZMW if the longest subreadis less
than this amount (default: 0)
.TP
.BI \-\-hqStartTime \ HQSTARTTIME
ZMW Filter: exclude ZMW if start time of HQ
regiongreater than this value (seconds) (default: inf)
.TP
.BI \-\-minReadScore \ MINREADSCORE
ZMW Filter: exclude ZMW if readScore is less thanthis
value (default: 0)
.TP
.BI \-\-minAvgBarcodeScore \ MINAVGBARCODESCORE
ZMW Filter: exclude ZMW if average barcode score is
less than this value (default: 0.0)
.TP
.BI \-\-minNumBarcodes \ MINNUMBARCODES
ZMW Filter: exclude ZMW if number of barcodes observed
is less than this value (default: 1)
.TP
.BI \-\-minScoreRatio \ MINSCORERATIO
ZMW Filter: exclude ZMWs whose best score divided by
the 2nd best score is less than this ratio (default:
1.0)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fBemitFastqs\fP command takes as input both an input.fofn for the
bas.h5 files as well as a barcode.fofn from a call to labelZmws. The
optional parameter \fBoutDir\fP dictates where the files will be
written. For each detected barcode, a fast[a|q] file will be emitted
with all of the reads for that barcode. The \fBtrim\fP parameter
dictates how much of the read should be trimmed off. The default
parameter for \fBtrim\fP is the length of the barcode (which is stored
in the barcode hdf5 files). At the moment, all barcodes in the barcode
FASTA file must be the same length, therefore only a constant trim
value is supported. In practice, one can aggressively trim in order to
ensure that extra bases aren\(aqt left on the ends of reads. Finally, the
\fBsubreads\fP parameter dictates whether subreads or CCS reads should
be returned with the default being the appropriate reads according to
the input file type, either CCS or subreads. This parameter is only
inspected if the input.fofn contains both CCS and subread data, if the
input.fofn contains only subread or CCS data then that is returned
irrespective of the state of the the \fBsubreads\fP parameter and a
warning is issued.
.SS consensus
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B usage: pbbarcode consensus [\-h] [\-\-subsample SUBSAMPLE] [\-\-nZmws NZMWS]
[\-\-outDir OUTDIR] [\-\-keepTmpDir]
[\-\-ccsFofn CCSFOFN] [\-\-nProcs NPROCS]
[\-\-noQuiver]
[\-\-minMaxInsertLength MINMAXINSERTLENGTH]
[\-\-hqStartTime HQSTARTTIME]
[\-\-minReadScore MINREADSCORE]
[\-\-minAvgBarcodeScore MINAVGBARCODESCORE]
[\-\-minNumBarcodes MINNUMBARCODES]
[\-\-minScoreRatio MINSCORERATIO]
[\-\-barcode BARCODE [BARCODE ...]]
input.fofn barcode.fofn
.UNINDENT
.sp
Compute consensus sequences for each barcode.
.INDENT 0.0
.TP
.B positional arguments:
input.fofn            input bas.h5 fofn file
barcode.fofn          input bc.h5 fofn file
.TP
.B optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-subsample \ SUBSAMPLE
Subsample ZMWs (default: 1)
.TP
.BI \-\-nZmws \ NZMWS
Take n ZMWs (default: \-1)
.TP
.BI \-\-outDir \ OUTDIR
Use this directory to output results (default: .)
.UNINDENT
.sp
\-\-keepTmpDir
\-\-ccsFofn CCSFOFN     Obtain CCS data from ccsFofn instead of input.fofn
.INDENT 7.0
.INDENT 3.5
(default: )
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.BI \-\-nProcs \ NPROCS
Use nProcs to execute. (default: 16)
.UNINDENT
.sp
\-\-noQuiver
\-\-minMaxInsertLength MINMAXINSERTLENGTH
.INDENT 7.0
.INDENT 3.5
ZMW Filter: exclude ZMW if the longest subreadis less
than this amount (default: 0)
.UNINDENT
.UNINDENT
.INDENT 7.0
.TP
.BI \-\-hqStartTime \ HQSTARTTIME
ZMW Filter: exclude ZMW if start time of HQ
regiongreater than this value (seconds) (default: inf)
.TP
.BI \-\-minReadScore \ MINREADSCORE
ZMW Filter: exclude ZMW if readScore is less thanthis
value (default: 0)
.TP
.BI \-\-minAvgBarcodeScore \ MINAVGBARCODESCORE
ZMW Filter: exclude ZMW if average barcode score is
less than this value (default: 0.0)
.TP
.BI \-\-minNumBarcodes \ MINNUMBARCODES
ZMW Filter: exclude ZMW if number of barcodes observed
is less than this value (default: 1)
.TP
.BI \-\-minScoreRatio \ MINSCORERATIO
ZMW Filter: exclude ZMWs whose best score divided by
the 2nd best score is less than this ratio (default:
1.0)
.UNINDENT
.INDENT 7.0
.TP
.B \-\-barcode BARCODE [BARCODE ...]
Use this to extract consensus for just one barcode.
(default: None)
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.sp
The \fBemitFastqs\fP command takes as input both an input.fofn for the
bas.h5 files as well as a barcode.fofn from a call to labelZmws. The
results are a FASTA file with an entry for each barcode containing the
consensus amplicon sequence. This mode utilizes \fBQuiver\fP and
\fBpbdagcon\fP to compute consensus.
.sp
In cases where the amplicon is fewer than 2.5k bases, using CCS data
is quite helpful. The \fB\-\-ccsFofn\fP allows one to pass directly the
ccs files. In many cases, both the CCS and raw basecalls are in the
same file so you can check by passing the same parameter to input.fofn
as to ccsFofn.
.SS Dependencies
.sp
The pbbarcode package depends on a standard pbcore installation
(\fI\%https://github.com/PacificBiosciences/pbcore\fP). If one wishes to use
the \fBconsensus\fP tool, \fBpbdagcon\fP needs to be installed
(\fI\%https://github.com/PacificBiosciences/pbdagcon\fP).
.SS Barcode HDF5 File
.sp
The barcode hdf5 file, \fBbc.h5\fP, represents a simple data store for
barcode calls and their scores for each ZMW. Generally, a user need
not interact with barcode hdf5 files, but can use the results stored in
either the resulting cmp.h5 file or fast[a|q] files. The barcode hdf5
file contains the following structure:
.sp
/BarcodeCalls/best \- (nZMWs, 6)[32\-bit integer] dataset with the
following columns:
.INDENT 0.0
.INDENT 3.5
\fBholeNumber,nAdapters,barcodeIdx1,barcodeScore1,barcodeIdx2,barcodeScore2\fP
.UNINDENT
.UNINDENT
.sp
Additionally, the \fBbest\fP dataset has the following attributes:
.TS
center;
|l|l|.
_
T{
movieName
T}	T{
m120408_042614_richard_c100309392550000001523011508061222_s1_p0
T}
_
T{
columnNames
T}	T{
holeNumber,nAdapters,barcodeIdx1,barcodeScore1,barcodeIdx2,
barcodeScore2
T}
_
T{
scoreMode
T}	T{
[symmetric|paired]
T}
_
T{
barcodes
T}	T{
\(aqbc_1\(aq, \(aqbc_2\(aq, ...., \(aqbc_N\(aq
T}
_
.TE
.sp
The two barcodeIdx1 and barcodeIdx2 columns are indices into
\fBbarcodes\fP attribute. The \fBscoreMode\fP is scoring mode used to
align the barcodes. The \fBbarcodes\fP attribute correspond to the
barcode.fasta sequence names.
.sp
Additionally, in some circumstances, it is useful to retain the entire
history of the scoring, i.e., each barcode scored to each adapter
across all ZMWs. In oder to retain this information, one must call:
.INDENT 0.0
.INDENT 3.5
\fBpbbarcode labelZmws \-\-saveExtendedInfo ...\fP
.UNINDENT
.UNINDENT
.sp
In this mode, the resultant HDF5 file will have an additional dataset
under the BarcodeCalls group, named: \fBall\fP\&. This dataset has the
following format:
.sp
/BarcodeCalls/all \- (nbarcodes * nadapters[zmw_i], 4) forall i in 1 ... nZMWs
.INDENT 0.0
.INDENT 3.5
\fB\(gaholeNumber, adapterIdx, barcodeIdx, score\(ga\fP
.UNINDENT
.UNINDENT
.sp
The \fBadapterIdx\fP is the index of the adapter along the molecule,
i.e., adapterIdx 1 is the first adapter scored.
.SS Additions to the compare HDF5 (cmp.h5) File
.sp
In addition to the barcode hdf5 file, a call to \fBlabelAlignments\fP
will annotate a cmp.h5 file. This annotation is stored in ways
consistent with the cmp.h5 file format. Specifically, a new group:
.nf
/BarcodeInfo/
.in +2
ID   (nBarcodeLabels + 1, 1)[32\-bit integer]
Name (nBarcodeLabels + 1, 1)[variable length string]
.in -2
.fi
.sp
.sp
In addition to the /BarcodeInfo/ group, the key dataset which assigns
alignments to barcodes is located at:
.sp
/AlnInfo/Barcode (nAlignments, 3)[32\-bit integer] with the following
columns:
.INDENT 0.0
.INDENT 3.5
\fBindex,count,bestIndex,bestScore,secondBestIndex,secondBestScore\fP
.UNINDENT
.UNINDENT
.sp
Here index refers to the index into the \fBName\fP vector, score
corresponds to the sum of the scores for the barcodes, and finally,
count refers to the number of adapters found in the molecule.
.\" Generated by docutils manpage writer.
.