NAME

       Bio::SearchIO::blastxml - A SearchIO implementation of NCBI Blast XML parsing.

SYNOPSIS

           use Bio::SearchIO;
           my $searchin = Bio::SearchIO->new(-format => 'blastxml',
                                            -file   => 't/data/plague_yeast.bls.xml');

           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 => 'blastxml',
                                            -file   => 't/data/plague_yeast.bls.xml');

           while( my $result = $searchin->next_result ) {
              ....
           }

           # PSI-BLAST parsing (default is normal BLAST)
           $searchin = Bio::SearchIO->new(
                            -format => 'blastxml',
                            -blasttype => 'psiblast',
                                            -file   => 't/data/plague_yeast.bls.xml');

           while( my $result = $searchin->next_result ) {
              ....
           }

DESCRIPTION

       This object implements a NCBI Blast XML parser.  It requires XML::SAX; 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 SAX subdirectory of XML in your
       local perl library (normally in the 'site' directory).

       Two different XML handlers currently exist to deal with logical differences between how
       normal BLAST reports and PSI-BLAST reports are logically parsed into BioPerl objects; this
       is explicitly settable using the -blasttype parameter.  The default is for parsing a
       normal BLAST report ('blast'), but if one is expecting PSI-BLAST report parsing,
       -blasttype must be set explicitly to 'psiblast'. This is due to a lack of any information
       in the XML output which tells the parser the report is derived from a PSI-BLAST run vs. a
       normal BLAST run.

       There is one additional initialization flag from the SearchIO defaults. That is the
       -tempfile 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 NCBI reports have an uncessary <?xml
       version="1.0"?> 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.

DEPENDENCIES

       In addition to parts of the Bio:: hierarchy, this module uses:

        XML::SAX

       It is also recommended that XML::SAX::ExpatXS be installed and made the default XML::SAX
       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 NCBI BLAST DTDs. This is due to issues with
       NCBI's BLAST XML format. The DTDs and the web address to obtain them are:

         NCBI_BlastOutput.dtd
         NCBI_BlastOutput.mod.dtd

         http://www.ncbi.nlm.nih.gov/data_specs/dtd/

FEEDBACK

   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.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       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.

   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:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Jason Stajich

       Email jason-at-bioperl.org

APPENDIX

       The rest of the documentation details each of the object methods.  Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $searchio = Bio::SearchIO->new(-format => 'blastxml',
                                                   -file   => 'filename',
                                                   -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.

   _initialize
        Title   : _initialize
        Usage   : private
        Function: Initializes the object - this is chained through new in SearchIO

   next_result
        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

   result_count
        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

   use_tempfile
        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)

   blasttype
        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 'chunked' (in cases
                  where multiple queries are submitted) and which XML handler
                  to use when parsing the report(s)