.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::SearchIO::blastxml 3pm"
.TH Bio::SearchIO::blastxml 3pm "2014-07-13" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::SearchIO::blastxml \- A SearchIO implementation of NCBI Blast XML parsing.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Bio::SearchIO;
\&    my $searchin = Bio::SearchIO\->new(\-format => \*(Aqblastxml\*(Aq,
\&                                     \-file   => \*(Aqt/data/plague_yeast.bls.xml\*(Aq);
\&
\&    while( my $result = $searchin\->next_result ) {
\&        ....
\&    }
\&
\&    # one can also request that the parser NOT keep the XML data in memory
\&    # by using the tempfile initialization flag.
\&
\&    $searchin = Bio::SearchIO\->new(\-tempfile => 1,
\&                                     \-format => \*(Aqblastxml\*(Aq,
\&                                     \-file   => \*(Aqt/data/plague_yeast.bls.xml\*(Aq);
\&
\&    while( my $result = $searchin\->next_result ) {
\&       ....
\&    }
\&
\&    # PSI\-BLAST parsing (default is normal BLAST)
\&    $searchin = Bio::SearchIO\->new(
\&                     \-format => \*(Aqblastxml\*(Aq,
\&                     \-blasttype => \*(Aqpsiblast\*(Aq,
\&                                     \-file   => \*(Aqt/data/plague_yeast.bls.xml\*(Aq);
\&
\&    while( my $result = $searchin\->next_result ) {
\&       ....
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object implements a \s-1NCBI\s0 Blast \s-1XML\s0 parser.  It requires \s-1XML::SAX\s0; it is
also recommended (for faster parsing) that XML::SAX::ExpatXS or XML::LibXML
be installed.  Either 'XML::SAX::ExpatXS' or 'XML::LibXML::SAX::Parser' should
be set as the default parser in ParserDetails.ini.  This file is located in the
\&\s-1SAX\s0 subdirectory of \s-1XML\s0 in your local perl library (normally in the 'site'
directory).
.PP
Two different \s-1XML\s0 handlers currently exist to deal with logical differences
between how normal \s-1BLAST\s0 reports and PSI-BLAST reports are logically parsed into
BioPerl objects; this is explicitly settable using the \fB\-blasttype\fR parameter.
The default is for parsing a normal \s-1BLAST\s0 report ('blast'), but if one is
expecting PSI-BLAST report parsing, \-blasttype \fBmust\fR be set explicitly to
\&'psiblast'. This is due to a lack of any information in the \s-1XML\s0 output which
tells the parser the report is derived from a PSI-BLAST run vs. a normal \s-1BLAST\s0
run.
.PP
There is one additional initialization flag from the SearchIO defaults. That is
the \fB\-tempfile\fR flag. If specified as true, then the parser will write out each
report to a temporary filehandle rather than holding the entire report as a
string in memory. The reason this is done in the first place is \s-1NCBI\s0 reports
have an uncessary <?xml version=\*(L"1.0\*(R"?> at the beginning of each report
and RPS-BLAST reports have an additional unnecessary RPS-BLAST tag at the top of
each report. So we currently have implemented the work around by preparsing the
file (yes it makes the process slower, but it works). We are open to suggestions
on how to optimize this in the future.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
In addition to parts of the Bio:: hierarchy, this module uses:
.PP
.Vb 1
\& XML::SAX
.Ve
.PP
It is also recommended that XML::SAX::ExpatXS be installed and made the default
\&\s-1XML::SAX\s0 parser using , along with the Expat library () for faster parsing.
XML::SAX::Expat is not recommended; XML::SAX::ExpatXS is considered the current
replacement for XML::SAX:Expat and is actively being considered to replace
XML::SAX::Expat. XML::SAX::Expat will work, but only if you have local copies of
the \s-1NCBI BLAST\s0 DTDs. This is due to issues with \s-1NCBI\s0's \s-1BLAST XML\s0 format. The
DTDs and the web address to obtain them are:
.PP
.Vb 2
\&  NCBI_BlastOutput.dtd
\&  NCBI_BlastOutput.mod.dtd
\&
\&  http://www.ncbi.nlm.nih.gov/data_specs/dtd/
.Ve
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "Mailing Lists"
User feedback is an integral part of the evolution of this and other
Bioperl modules. Send your comments and suggestions preferably to
the Bioperl mailing list.  Your participation is much appreciated.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
rather than to the module maintainer directly. Many experienced and
reponsive experts will be able look at the problem and quickly
address it. Please include a thorough description of the problem
with code and data examples if at all possible.
.SS "Reporting Bugs"
.IX Subsection "Reporting Bugs"
Report bugs to the Bioperl bug tracking system to help us keep track
of the bugs and their resolution. Bug reports can be submitted via the
web:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Jason Stajich"
.IX Header "AUTHOR - Jason Stajich"
Email jason\-at\-bioperl.org
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 9
\& Title   : new
\& Usage   : my $searchio = Bio::SearchIO\->new(\-format => \*(Aqblastxml\*(Aq,
\&                                            \-file   => \*(Aqfilename\*(Aq,
\&                                            \-tempfile => 1);
\& Function: Initializes the object \- this is chained through new in SearchIO
\& Returns : Bio::SearchIO::blastxml object
\& Args    : One additional argument from the format and file/fh parameters.
\&           \-tempfile    => boolean.  Defaults to false.  Write out XML data
\&                           to a temporary filehandle to send to PerlSAX parser.
.Ve
.SS "_initialize"
.IX Subsection "_initialize"
.Vb 3
\& Title   : _initialize
\& Usage   : private
\& Function: Initializes the object \- this is chained through new in SearchIO
.Ve
.SS "next_result"
.IX Subsection "next_result"
.Vb 5
\& Title   : next_result
\& Usage   : my $hit = $searchio\->next_result;
\& Function: Returns the next Result from a search
\& Returns : Bio::Search::Result::ResultI object
\& Args    : none
.Ve
.SS "result_count"
.IX Subsection "result_count"
.Vb 8
\& Title   : result_count
\& Usage   : $num = $stream\->result_count;
\& Function: Gets the number of Blast results that have been successfully parsed
\&           at the point of the method call.  This is not the total # of results
\&           in the file.
\& Returns : integer
\& Args    : none
\& Throws  : none
.Ve
.SS "use_tempfile"
.IX Subsection "use_tempfile"
.Vb 6
\& Title   : use_tempfile
\& Usage   : $obj\->use_tempfile($newval)
\& Function: Get/Set boolean flag on whether or not use a tempfile
\& Example :
\& Returns : value of use_tempfile
\& Args    : newvalue (optional)
.Ve
.SS "blasttype"
.IX Subsection "blasttype"
.Vb 8
\& Title   : blasttype
\& Usage   : $obj\->blasttype($newtype)
\& Function: Get/Set BLAST report type.
\& Returns : BLAST report type
\& Args    : case\-insensitive string of types BLAST or PSIBLAST (default: BLAST)
\& Note    : this is used to determine how reports are \*(Aqchunked\*(Aq (in cases
\&           where multiple queries are submitted) and which XML handler
\&           to use when parsing the report(s)
.Ve