Bio::I...tTable(3pm)

💖 Bio::Index::BlastTable 💖

okay so bestie, welcome to Bio::Index::BlastTable — the Perl module (that's the 3pm manual, iykyk) that indexes tabular Blast reports (the -m 8 or -m 9 format girlies) and lets you grab stuff back out based on query accession(s). she's giving librarian energy but make it bioinformatics 💅

---

✨ NAME ✨

Bio::Index::BlastTable — indexes tabular Blast reports (-m 8 or -m 9 format) and supports retrieval based on query accession(s) 🦋

---

🌸 SYNOPSIS 🌸

no cap, here's the whole vibe:

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, "\n";
while ( my $hit = $blast_result->next_hit ) {
    print "Name ", $hit->name,"\n";
    while ( my $hsp = $hit->next_hsp ) {
        print "Score ", $hsp->score;
    }
    print "\n";
}

like. look at her go. ✨

---

💜 DESCRIPTION 💜

so this object lets you build an index on a tabular BLAST file (or, like, multiple files, she's flexible 🫶) and then gives you quick access to the blast report for that accession. that's the whole point, periodt.

she also lets you do ID parsing with a callback, which is honestly iconic:

$inx->id_parser(\&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\|(\d+)/;
   $1;
}

and here's the tea 🍓 — the indexer can index based on multiple IDs passed back from that callback. this is assuming, of course, that all the IDs are unique. (they gotta be unique bestie, no duplicates allowed, that's the rule 🙈)

Note: for best results 'use strict'. fr fr, just do it.

---

📬 FEEDBACK 📬

💌 Mailing Lists

user feedback is, like, 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, genuinely 🥹

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

🫂 Support

okay so please direct usage questions or support issues to the mailing list:

bioperl-l@bioperl.org

rather than to the module maintainer directly. like, no hate to the maintainer, but there are so many experienced and reponsive experts who will be able to 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 — the more context the better, bestie 💅

🐛 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://github.com/bioperl/bioperl-live/issues

go off, tell them everything. it's giving accountability ✨

---

👑 AUTHOR - Jason Stajich 👑

Email jason-at-bioperl-dot-org

---

🎀 APPENDIX 🎀

okay bestie, this is the part where we get into the actual lore. Every object method, every internal method (you'll spot them, they all start with _ like they're hiding from the group chat), fully explained. Buckle up 💖

---

✨ new

• Usage —

$index = Bio::Index::Abstract->new(
            -filename    => $dbm_file,
            -write_flag  => 0,
            -dbm_package => 'DB_File',
            -verbose     => 0);

• Function — hands you a brand-new index object. If you passed a filename, it calls open_dbm() on the spot, no hesitation. Heads up though: you'll usually only call Bio::Index::Abstract->new() directly when you're opening an index that already exists. It's giving "I'm just here to reopen, not to build" 💅
• Returns — a fresh new index object, slay ✨
• Args —
  • -filename — the name of the dbm index file.
  • -write_flag — TRUE if you need write access to the dbm file.
  • -dbm_package — the Perl dbm module to use for the index.
  • -verbose — print debugging output to STDERR if TRUE.

---

💥 Bio::Index::Blast implemented methods

fetch_report

• Title — fetch_report
• Usage — my $blastreport = $idx->fetch_report($id);
• Function — returns a Bio::SearchIO report object for one specific blast report. very demure, very mindful, very parsed 🧚
• Returns — Bio::SearchIO
• Args — a valid id

---

🫶 Require methods from Bio::Index::Abstract

_index_file

• Title — _index_file
• Usage — $index->_index_file( $file_name, $i )
• Function — the specialist function that indexes BLAST report file(s). It gets handed a filename and an integer by make_index over in its SUPER class. teamwork makes the dream work 🫶
• Example — (blank in the original, bestie, nothing to see)
• Returns — (also blank)
• Args — (still blank, it's giving minimalist)

id_parser

• Title — id_parser
• Usage — $index->id_parser( CODE )
• Function — stores or returns the code that record_id uses to parse the ID for a record out of a string. Super useful when you want a different parser for different flavours of blast dbs. If nothing's set, it returns \&default_id_parser (that's the next one down ⬇️). And if you supply your own id_parser subroutine, it should expect a fasta description line — and an entry gets added to the index for each string in the list it returns.
• Example — $index->id_parser( \&my_id_parser )
• Returns — a ref to CODE if you call it with no arguments
• Args — CODE

default_id_parser

• Title — default_id_parser
• Usage — $id = default_id_parser( $header )
• Function — the default Blast Query ID parser for Bio::Index::Blast.pm. It returns $1 from applying the regexp /^>\s*(\S+)/ to $header. regex girlies rise 🙈
• Returns — ID string
• Args — a header line string

---

👑 Bio::Index::Abstract methods

filename

• 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 you're setting it, or nothing at all if you're just getting it.

write_flag

• Title — write_flag
• Usage —

$value = $self->write_flag();
$self->write_flag($value);

• Function — gets or sets the value of write_flag, which is literally just "should the dbm file be opened with write access or not".
• Returns — the current value of write_flag (default is 0)
• Args — value of write_flag if setting, or none if getting.

dbm_package

• Usage —

$value = $self->dbm_package();
$self->dbm_package($value);

• Function — gets or sets the name of the Perl dbm module being used. If it's unset, it returns the value of the package variable $USE_DBM_TYPE; and if that's unset too, it picks the best dbm type available, choosing 'DB_File' over 'SDBM_File'. And fyi, Bio::Abstract::Index may work with other dbm file types too — no promises, but maybe 🦋
• Returns — the current value of dbm_package
• Args — value of dbm_package if setting, or none if getting.

get_stream

• Title — get_stream
• Usage — $stream = $index->get_stream( $id );
• Function — returns a file handle with the file pointer sitting at the appropriate place. It's the way to get the actual file contents and not an object. very raw, very unfiltered.

WARNING: you have to parse the record delimiter yourself. Abstract will not do this for you. So this code

$fh = $index->get_stream($myid);
while( <$fh> ) {
   # do something
}

will parse the entire file if you don't put a last statement in, like

while( <$fh> ) {
   /^\/\// && last; # end of record
   # do something
}

• Returns — a filehandle object
• Args — string representing the accession number
• Notes — this method should not be used without forethought. fr fr, think before you call 🧠

open_dbm

• Usage — $index->open_dbm()
• Function — opens the dbm file associated with the index object. Write access is only given if it's explicitly asked for, either by calling new(-write => 1) or by having set write_flag(1) on the index object. The type of dbm file opened is whatever dbm_package() returned, and the name of the file being opened comes from calling the filename() method.
• Example — $index->_open_dbm()
• Returns — 1 on success

_version

• Title — _version
• Usage — $type = $index->_version()
• Function — returns a string that identifies the version of an index module. It's used to permanently mark an index file as having been created by a particular version of the index module. Must be provided by the sub class — no skipping, bestie.
• Example — (blank)
• Returns — (blank)
• Args — none

_filename

• Title — _filename
• Usage — $index->_filename( FILE INT )
• Function — indexes the file
• Example — (blank)
• Returns — (blank)
• Args — (blank)

_file_handle

• Title — _file_handle
• Usage — $fh = $index->_file_handle( INT )
• Function — returns an open filehandle for the file index INT. When it opens a new filehandle it caches it in the @{$index->_filehandle} array, and if the filehandle you asked for is already open, it just returns it straight out of the array. efficient queen 👑
• Example — $fist_file_indexed = $index->_file_handle( 0 );
• Returns — ref to a filehandle
• Args — INT

_file_count

• Title — _file_count
• Usage — $index->_file_count( INT )
• Function — used by the index building sub in a sub class to keep track of how many files have been indexed. Sets or gets the number of files indexed depending on whether you call it with or without an argument.
• Example — (blank)
• Returns — INT
• Args — INT

add_record

• Title — add_record
• Usage — $index->add_record( $id, @stuff );
• Function — calls pack_record on @stuff, then adds the result of pack_record to the index database under the key $id. And if $id is a reference to an array, then a new entry gets added under a key corresponding to each element of that array. one id, many keys, the way that it just multiplies ✨
• Example — $index->add_record( $id, $fileNumber, $begin, $end )
• Returns — TRUE on success or FALSE on failure
• Args — ID LIST

pack_record

• 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 ever show up in any of the strings), and returns it.
• Example — $packed_string = $index->pack_record( $fileNumber, $begin, $end )
• Returns — STRING or undef
• Args — LIST

unpack_record

• Title — unpack_record
• Usage — $index->unpack_record( STRING )
• Function — splits the string you gave it 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

DESTROY

• Title — DESTROY
• Usage — called automatically when the index goes out of scope
• Function — closes the connection to the database and the handles to the sequence files. it's the goodbye hug 🤗
• Returns — NEVER (like, literally never, don't wait around for it)
• Args — NONE

---

okay that's the whole page, bestie, you're officially fluent 💖 this one was written by Jason Stajich, and it came from Perl v5.32.1 on 2021-08-15 — yes it's a little vintage, but vintage is just iconic with a longer track record 👑✨ go forth and index something 🦋