Bio::SearchIO::blastxml(3pm)				User Contributed Perl Documentation			      Bio::SearchIO::blastxml(3pm)

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)

perl v5.14.2							    2012-03-02					      Bio::SearchIO::blastxml(3pm)