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

💖 Bio::Index::Hmmer — bestie edition (part 1 of 2) 💖

ok so this is the manual for Bio::Index::Hmmer, living in the 3pm section of the perl docs (User Contributed Perl Documentation, to be exact). It indexes HMMER reports and lets you fetch them back by query. Let's get into it 🫶

---

✨ NAME ✨

Bio::Index::Hmmer — it builds indexes over HMMER reports and supports retrieval based on the query. That's the whole vibe. 👑

---

✨ SYNOPSIS ✨

okay so here's literally the complete code for indexing a set of report files:

# Complete Code for indexing a set of report files
#!/usr/bin/perl -w
use strict;
use Bio::Index::Hmmer;
my $indexfile = shift;
my $index = Bio::Index::Hmmer->new(
        -filename => $indexfile,
        -write_flag => 1
);
$index->make_index(@ARGV);

and here's the complete code for fetching a report:

# Complete code for fetching a report
use strict;
use Bio::Index::Hmmer;
my $indexfile = shift;
my $index = Bio::Index::Hmmer->new(
        -filename => $indexfile,
        -write_flag => 0
);

foreach my $id (@ARGV) {
        my $report = $index->fetch_report($id);
        print "Query: ", $report->query_name(), "\n";
        while( my $hit = $report->next_hit() ) {
                print "\tHit Name: ", $hit->name(), "\n";
                while( my $hsp = $hit->next_domain() ) {
                        print "\t\tE-Value: ", $hsp->evalue(), "\n";
                }
        }
}

like, that's it. that's the whole thing. copy, paste, slay. 💅

---

✨ DESCRIPTION ✨

so this object lets you build an index on a HMMER file (or, like, multiple files, no pressure) and then gives you quick access to the HMMER report for that accession. For best results, use strict. that's not a suggestion, bestie, that's a lifestyle. 😌

you can also set or customize the unique key used to retrieve stuff by writing your own function and calling the id_parser() method. For example:

$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 =~ /^KW\s+([A-Z]+)/i;
   $1;
}

see how that works? you hand it a coderef, it does the thing. your index, your rules. ✨

---

✨ 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. fr fr, they mean it. 🫶

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. like, not to be dramatic but there are Many experienced and reponsive experts who will be able look at the problem and quickly address it. so slide into the list's DMs instead 💌

Please include a thorough description of the problem with code and data examples if at all possible. receipts help. always. 🙈

🌸 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

ok real talk: bugs are not a vibe, but reporting them is. help them help you. 💀

---

✨ AUTHOR - Josh Lauricha ✨

Email laurichj@bioinfo.ucr.edu

---

(part 1 done, bestie — more coming, don't go anywhere 💖)

✨ APPENDIX ✨

okay bestie, this is the deep-lore part 💖 the rest of the docs breaks down literally every single object method, one by one. and heads up: the internal ones — the secret backstage ones — are usually marked with a _ up front. you'll clock them instantly 🫶

---

🎀 new

• Usage:

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

• Function: hands you back a brand-new index object. and the second you pass in filename, it immediately calls open_dbm() — no waiting, no asking, it just goes 💅
• Returns: a shiny 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 — prints debugging output to STDERR if TRUE.

---

🧬 Bio::Index::Hmmer implemented methods

fetch_report

• Title: fetch_report
• Usage: my $report = $idx->fetch_report($id);
• Function: gives you back a Bio::Search::Result::HMMERResult report object for one specific HMMER report 🔥
• Returns: Bio::Search::Result::HMMERResult
• Args: a valid id

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 for, like, specifying a different parser for different flavours of blast dbs. if you never set it, it returns \&default_id_parser (peep below 👇). and if you do supply your own id_parser subroutine, then it should expect a fasta description line. an entry gets added to the index for each string in the list it hands back.
• 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.
• Returns: an ID string
• Args: a header line string

---

🌈 Require methods from Bio::Index::Abstract

_index_file

• Title: _index_file
• Usage: $index->_index_file( $file_name, $i )
• Function: the specialist function that indexes HMMER report file(s). it gets handed a filename and an integer by make_index in its SUPER class.
• Example:
• Returns:
• Args:

---

💜 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: the value of filename if you're setting it, or nothing 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 whether the dbm file should be opened with write access.
• Returns: the current value of write_flag (default 0)
• Args: the value of write_flag if you're setting it, or nothing if you're just getting it.

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 the value is unset, then it returns the value of the package variable $USE_DBM_TYPE, or — if that's unset too — then it picks the best available dbm type, choosing 'DB_File' in preference to 'SDBM_File'. Bio::Abstract::Index may work with other dbm file types too 👀
• Returns: the current value of dbm_package
• Args: the value of dbm_package if you're setting it, or nothing if you're just getting it.

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.

this is your way to grab the actual file contents and not an object.

⚠️ 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 drop a last statement in there, like so:

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

• Returns: a filehandle object
• Args: a string representing the accession number
• Notes: this method should not be used without forethought 😭

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 by calling new(-write => 1) or by having set write_flag(1) on the index object. the type of dbm file that gets opened is whatever dbm_package() returns. 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.
• Example:
• Returns:
• Args: none

_filename

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

_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 hands it right back to you from the array. efficiency queen 👑
• Example: $fist_file_indexed = $index->_file_handle( 0 );
• Returns: a 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:
• 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 matching each element of that array. multitasking fr fr ✨
• 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 one single string joined by ASCII 034 (which is unlikely to 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 hand 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 sequence files 🫶
• Returns: NEVER 💀
• Args: NONE

---

and that's a wrap, bestie!! 🌸 this page was perl v5.30.0, dated 2019-10-29, from Bio::I...::Hmmer(3pm) — iconic, historic, we stan a documented module 💅✨