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

💖 Bio::Index::Blast 💖

(that's the Bio::I...::Blast(3pm) you just pulled up — the truncation is just the terminal being dramatic 💅)

---

✨ NAME ✨

Bio::Index::Blast — it indexes Blast reports and lets you pull them back out by query accession(s). It's giving glorified filing cabinet but make it bioinformatics 🧬

---

🎀 SYNOPSIS 🎀

okay bestie, here's the whole vibe in code form:

use strict;
use Bio::Index::Blast;

my ($indexfile,$file1,$file2,$query);
my $index = Bio::Index::Blast->new(-filename => $indexfile,
                                   -write_flag => 1);
$index->make_index($file1,$file2);

my $fh = $index->get_stream($query);

my $blast_report = Bio::SearchIO->new(-noclose => 1,
                                      -format  => 'blast',
                                      -fh      => $fh);
my $result = $blast_report->next_result;
print $result->algorithm, "\n";
my $hit = $result->next_hit;
print $hit->description, "\n";
my $hsp = $hit->next_hsp;
print $hsp->bits, "\n";

make the index, grab the stream, feed it to Bio::SearchIO, then just walk down result → hit → hsp like it's a lil staircase 🪜✨

---

🌸 DESCRIPTION 🌸

So basically, this object lets you build an index on a blast file (or a whole stack of blast files, no judgment) and then get quick access to the blast report for that accession. Instant. Iconic. No re-parsing the whole file like a peasant 😭

It also lets you do ID parsing with a callback, like this:

$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 those IDs are unique. (iykyk 🫶)

Note: for best results 'use strict'.

yes bestie, it said it, I'm just relaying it — use strict is the moment, always 💅

---

💌 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. fr fr 🥹

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. There are so many experienced and responsive 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 receipts the better 📎✨

🐛 Reporting Bugs

Report bugs to the Bioperl bug tracking system so we can 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, they want to know 💀

---

👑 AUTHOR - Jason Stajich 👑

Email: jason-at-bioperl-dot-org

shoutout to Jason, main character energy, no cap 🌟

---

✨ k part 1 done — part 2 is literally right there bestie, keep scrolling 🌈

📎 APPENDIX 📎

okay bestie, this is the deep-lore part — the rest of the documentation details each of the object methods, and just so you know, internal methods are usually preceded with a _. 🫶

---

🌟 new 🌟

• Usage:

$index = Bio::Index::Abstract->new(
            -filename    => $dbm_file,
            -write_flag  => 0,
            -dbm_package => 'DB_File',
            -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.

---

💅 Bio::Index::Blast implemented methods 💅

these ones are the Blast-specific glow-ups, bestie

🔥 fetch_report 🔥

• 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

🔥 fetch_result 🔥

• Title: fetch_result
• Usage: my $blastreport = $idx->fetch_result($id);
• Function: Returns a Bio::SearchIO report object for a specific blast report
• Returns: Bio::SearchIO
• Args: valid id
• Note: alias of fetch_report()

---

🧚 Require methods from Bio::Index::Abstract 🧚

these are the ones you literally have to bring to the party — inherited requirements, no skipping

✨ _index_file ✨

• 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: (none given)
• Returns: (none given)
• Args: (none given)

✨ id_parser ✨

• 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 \&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( \&my_id_parser )
• Returns: ref to CODE if called without 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. Returns $1 from applying the regexp /^>\s*(\S+)/ to $header.
• Returns: ID string
• Args: a header line string

✨ blast_parser_type ✨

• Title: blast_parser_type
• Usage: $index->blast_parser_type() # returns
• Function: Get/Set SearchIO-based text (-m0) BLAST parser. Only values in local %VALID_PARSERS hash allowed.
• Returns: String
• Args: [optional]
• Note: This only allows simple text-based parsing options; tabular, XML, or others are not supported (see Bio::Index::BlastTable for tab output).

---

🌈 Bio::Index::Abstract methods 🌈

the whole foundational era of methods, we love her

🎀 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 setting, or none if getting the value.

🎀 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 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.

🎀 dbm_package 🎀

• 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 'DB_File' in preference to 'SDBM_File'. 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.

🎀 get_stream 🎀

• 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't 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> ) {
   /^\/\// && 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

bestie the "approprite" is spelled like that in the original, I'm not fixing her, she's iconic 💀 and seriously — that WARNING is a real one, do not skip it.

🎀 open_dbm 🎀

• 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

🎀 _version 🎀

• 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: (none given)
• Returns: (none given)
• Args: none

🎀 _filename 🎀

• Title: _filename
• Usage: $index->_filename( FILE INT )
• Function: Indexes the file
• Example: (none given)
• Returns: (none given)
• Args: (none given)

🎀 _file_handle 🎀

• 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

🎀 _file_count 🎀

• 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: (none given)
• Returns: INT
• Args: INT

🎀 add_record 🎀

• 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

🎀 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 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

🎀 unpack_record 🎀

• 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

🎀 DESTROY 🎀

• 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

---

and that's the whole page, bestie — you made it to the end and honestly? main character energy. go forth and index some blast reports, you've got this. periodt. 💖✨🦋

this page came out of perl v5.32.1, dated 2021-08-15, and it's the Bio::I...::Blast(3pm) page from the User Contributed Perl Documentation — so shoutout to that vintage and to whoever typed all this up by hand. 🎀