.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "Bio::Index::BlastTable 3pm"
.TH Bio::Index::BlastTable 3pm "2020-10-28" "perl v5.30.3" "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::Index::BlastTable \- Indexes tabular Blast reports (\-m 8 or \-m 9 format) and
supports retrieval based on query accession(s)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 6
\&    use strict;
\&    use Bio::Index::BlastTable;
\&    my ($indexfile,$file1,$file2,$query);
\&    my $index = Bio::Index::BlastTable\->new(\-filename => $indexfile,
\&                                                          \-write_flag => 1);
\&    $index\->make_index($file1,$file2);
\&
\&    my $data = $index\->get_stream($query);
\&
\&    my $blast_result = $index\->fetch_report($query);
\&    print "query is ", $blast_result\->query_name, "\en";
\&    while ( my $hit = $blast_result\->next_hit ) {
\&        print "Name ", $hit\->name,"\en";
\&        while ( my $hsp = $hit\->next_hsp ) {
\&            print "Score ", $hsp\->score;
\&        }
\&        print "\en";
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This object allows one to build an index on a tabular \s-1BLAST\s0 file (or files)
and provide quick access to the blast report for that accession.  This also
allows for \s-1ID\s0 parsing using a callback:
.PP
.Vb 3
\&   $inx\->id_parser(\e&get_id);
\&   # make the index
\&   $inx\->make_index($file_name);
\&
\&   # here is where the retrieval key is specified
\&   sub get_id {
\&      my $line = shift;
\&      $line =~ /^>.+gi\e|(\ed+)/;
\&      $1;
\&   }
.Ve
.PP
The indexer is capable of indexing based on multiple IDs passed back from the
callback; this is assuming of course all IDs are unique.
.PP
Note: for best results 'use strict'.
.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-dot-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 5
\&  Usage   : $index = Bio::Index::Abstract\->new(
\&                \-filename    => $dbm_file,
\&                \-write_flag  => 0,
\&                \-dbm_package => \*(AqDB_File\*(Aq,
\&                \-verbose     => 0);
\&
\&  Function: Returns a new index object.  If filename is
\&            specified, then open_dbm() is immediately called.
\&            Bio::Index::Abstract\->new() will usually be called
\&            directly only when opening an existing index.
\&  Returns : A new index object
\&  Args    : \-filename    The name of the dbm index file.
\&            \-write_flag  TRUE if write access to the dbm file is
\&                         needed.
\&            \-dbm_package The Perl dbm module to use for the
\&                         index.
\&            \-verbose     Print debugging output to STDERR if
\&                         TRUE.
.Ve
.SS "Bio::Index::Blast implemented methods"
.IX Subsection "Bio::Index::Blast implemented methods"
.SS "fetch_report"
.IX Subsection "fetch_report"
.Vb 6
\& Title   : fetch_report
\& Usage   : my $blastreport = $idx\->fetch_report($id);
\& Function: Returns a Bio::SearchIO report object
\&           for a specific blast report
\& Returns : Bio::SearchIO
\& Args    : valid id
.Ve
.SS "Require methods from Bio::Index::Abstract"
.IX Subsection "Require methods from Bio::Index::Abstract"
.SS "_index_file"
.IX Subsection "_index_file"
.Vb 8
\&  Title   : _index_file
\&  Usage   : $index\->_index_file( $file_name, $i )
\&  Function: Specialist function to index BLAST report file(s).
\&            Is provided with a filename and an integer
\&            by make_index in its SUPER class.
\&  Example :
\&  Returns :
\&  Args    :
.Ve
.SS "id_parser"
.IX Subsection "id_parser"
.Vb 10
\&  Title   : id_parser
\&  Usage   : $index\->id_parser( CODE )
\&  Function: Stores or returns the code used by record_id to
\&            parse the ID for record from a string.  Useful
\&            for (for instance) specifying a different
\&            parser for different flavours of blast dbs.
\&            Returns \e&default_id_parser (see below) if not
\&            set. If you supply your own id_parser
\&            subroutine, then it should expect a fasta
\&            description line.  An entry will be added to
\&            the index for each string in the list returned.
\&  Example : $index\->id_parser( \e&my_id_parser )
\&  Returns : ref to CODE if called without arguments
\&  Args    : CODE
.Ve
.SS "default_id_parser"
.IX Subsection "default_id_parser"
.Vb 7
\&  Title   : default_id_parser
\&  Usage   : $id = default_id_parser( $header )
\&  Function: The default Blast Query ID parser for Bio::Index::Blast.pm
\&            Returns $1 from applying the regexp /^>\es*(\eS+)/
\&            to $header.
\&  Returns : ID string
\&  Args    : a header line string
.Ve
.SS "Bio::Index::Abstract methods"
.IX Subsection "Bio::Index::Abstract methods"
.SS "filename"
.IX Subsection "filename"
.Vb 7
\& Title   : filename
\& Usage   : $value = $self\->filename();
\&           $self\->filename($value);
\& Function: Gets or sets the name of the dbm index file.
\& Returns : The current value of filename
\& Args    : Value of filename if setting, or none if
\&           getting the value.
.Ve
.SS "write_flag"
.IX Subsection "write_flag"
.Vb 9
\& Title   : write_flag
\& Usage   : $value = $self\->write_flag();
\&           $self\->write_flag($value);
\& Function: Gets or sets the value of write_flag, which
\&           is whether the dbm file should be opened with
\&           write access.
\& Returns : The current value of write_flag (default 0)
\& Args    : Value of write_flag if setting, or none if
\&           getting the value.
.Ve
.SS "dbm_package"
.IX Subsection "dbm_package"
.Vb 2
\& Usage   : $value = $self\->dbm_package();
\&           $self\->dbm_package($value);
\&
\& Function: Gets or sets the name of the Perl dbm module used.
\&           If the value is unset, then it returns the value of
\&           the package variable $USE_DBM_TYPE or if that is
\&           unset, then it chooses the best available dbm type,
\&           choosing \*(AqDB_File\*(Aq in preference to \*(AqSDBM_File\*(Aq.
\&           Bio::Abstract::Index may work with other dbm file
\&           types.
\&
\& Returns : The current value of dbm_package
\& Args    : Value of dbm_package if setting, or none if
\&           getting the value.
.Ve
.SS "get_stream"
.IX Subsection "get_stream"
.Vb 4
\& Title   : get_stream
\& Usage   : $stream = $index\->get_stream( $id );
\& Function: Returns a file handle with the file pointer
\&           at the approprite place
\&
\&           This provides for a way to get the actual
\&           file contents and not an object
\&
\&           WARNING: you must parse the record deliminter
\&           *yourself*. Abstract won\*(Aqt do this for you
\&           So this code
\&
\&           $fh = $index\->get_stream($myid);
\&           while( <$fh> ) {
\&              # do something
\&           }
\&           will parse the entire file if you do not put in
\&           a last statement in, like
\&
\&           while( <$fh> ) {
\&              /^\e/\e// && last; # end of record
\&              # do something
\&           }
\&
\& Returns : A filehandle object
\& Args    : string represents the accession number
\& Notes   : This method should not be used without forethought
.Ve
.SS "open_dbm"
.IX Subsection "open_dbm"
.Vb 8
\&  Usage   : $index\->open_dbm()
\&  Function: Opens the dbm file associated with the index
\&            object.  Write access is only given if explicitly
\&            asked for by calling new(\-write => 1) or having set
\&            the write_flag(1) on the index object.  The type of
\&            dbm file opened is that returned by dbm_package().
\&            The name of the file to be is opened is obtained by
\&            calling the filename() method.
\&
\&  Example : $index\->_open_dbm()
\&  Returns : 1 on success
.Ve
.SS "_version"
.IX Subsection "_version"
.Vb 9
\&  Title   : _version
\&  Usage   : $type = $index\->_version()
\&  Function: Returns a string which identifes the version of an
\&            index module.  Used to permanently identify an index
\&            file as having been created by a particular version
\&            of the index module.  Must be provided by the sub class
\&  Example :
\&  Returns :
\&  Args    : none
.Ve
.SS "_filename"
.IX Subsection "_filename"
.Vb 6
\&  Title   : _filename
\&  Usage   : $index\->_filename( FILE INT )
\&  Function: Indexes the file
\&  Example :
\&  Returns :
\&  Args    :
.Ve
.SS "_file_handle"
.IX Subsection "_file_handle"
.Vb 10
\&  Title   : _file_handle
\&  Usage   : $fh = $index\->_file_handle( INT )
\&  Function: Returns an open filehandle for the file
\&            index INT.  On opening a new filehandle it
\&            caches it in the @{$index\->_filehandle} array.
\&            If the requested filehandle is already open,
\&            it simply returns it from the array.
\&  Example : $fist_file_indexed = $index\->_file_handle( 0 );
\&  Returns : ref to a filehandle
\&  Args    : INT
.Ve
.SS "_file_count"
.IX Subsection "_file_count"
.Vb 9
\&  Title   : _file_count
\&  Usage   : $index\->_file_count( INT )
\&  Function: Used by the index building sub in a sub class to
\&            track the number of files indexed.  Sets or gets
\&            the number of files indexed when called with or
\&            without an argument.
\&  Example :
\&  Returns : INT
\&  Args    : INT
.Ve
.SS "add_record"
.IX Subsection "add_record"
.Vb 10
\&  Title   : add_record
\&  Usage   : $index\->add_record( $id, @stuff );
\&  Function: Calls pack_record on @stuff, and adds the result
\&            of pack_record to the index database under key $id.
\&            If $id is a reference to an array, then a new entry
\&            is added under a key corresponding to each element
\&            of the array.
\&  Example : $index\->add_record( $id, $fileNumber, $begin, $end )
\&  Returns : TRUE on success or FALSE on failure
\&  Args    : ID LIST
.Ve
.SS "pack_record"
.IX Subsection "pack_record"
.Vb 8
\&  Title   : pack_record
\&  Usage   : $packed_string = $index\->pack_record( LIST )
\&  Function: Packs an array of scalars into a single string
\&            joined by ASCII 034 (which is unlikely to be used
\&            in any of the strings), and returns it.
\&  Example : $packed_string = $index\->pack_record( $fileNumber, $begin, $end )
\&  Returns : STRING or undef
\&  Args    : LIST
.Ve
.SS "unpack_record"
.IX Subsection "unpack_record"
.Vb 7
\&  Title   : unpack_record
\&  Usage   : $index\->unpack_record( STRING )
\&  Function: Splits the sting provided into an array,
\&            splitting on ASCII 034.
\&  Example : ( $fileNumber, $begin, $end ) = $index\->unpack_record( $self\->db\->{$id} )
\&  Returns : A 3 element ARRAY
\&  Args    : STRING containing ASCII 034
.Ve
.SS "\s-1DESTROY\s0"
.IX Subsection "DESTROY"
.Vb 6
\& Title   : DESTROY
\& Usage   : Called automatically when index goes out of scope
\& Function: Closes connection to database and handles to
\&           sequence files
\& Returns : NEVER
\& Args    : NONE
.Ve