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

💖 Bio::Index::Stockholm — the manual page, bestie edition 💖

okay so before we even get into it: this page lives in the User Contributed Perl Documentation and its manual name is Bio::I...ockholm(3pm) (yes the title got truncated, we don't know her full name either, it's giving mystery 💅). Anyway. Sit down, grab a strawberry, because this module is iconic and you're gonna understand it.

---

✨ NAME ✨

Bio::Index::Stockholm — the Interface for indexing Stockholm files. that's it. that's the whole vibe. 🎀

---

🌸 SYNOPSIS 🌸

here's the whole thing, copy it exactly bestie, no cap:

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

    # get raw data stream starting at alignment position
    my $fh = $index->get_stream($query);

    # fetch individual alignment
    my $align = $index->fetch_aln($query); # alias for fetch_report
    my $align = $index->fetch_report($query); # same as above
    print "query is ", $align->display_id, "\n";

so like: you build an index, you make the index over your files, then you either grab a raw data stream with get_stream or pull a whole alignment with fetch_aln / fetch_report (they're the same thing, twin sisters, fetch_aln is literally just an alias for fetch_report 🫶). then you print the display_id. slay.

---

🦋 DESCRIPTION 🦋

This module indexes Stockholm format alignments — the kind that come out of Pfam and Rfam. You get raw stream data back using the ID, or you get a Bio::SimpleAlign object back (that happens via Bio::AlignIO, if you were wondering where she got it from).

It also lets you do ID parsing with a callback, which is the part where you get to be the main character:

   $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 handed back from that callback — that's assuming, obviously, that all the IDs are unique. you know what assuming does, but here it's fine. The default behaviour is to just use the alignment ID that Rfam/Pfam output gives you.

Note: for best results 'use strict'. literally just do it. use strict is your best friend, she keeps you safe 💖

---

💀 TODO 💀

• allow using an alternative regex for indexing (for instance, the ID instead of AC)

that's the list. one item. she's short but she's honest. 🙈

---

💌 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 — like, genuinely, they want to hear from you. 👑

  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. why? because there are many experienced and reponsive experts (yes, that's the original spelling, we're keeping it, character for character, periodt) 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. code and data examples. always. that's the assignment. 📝

🐛 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

that's a GitHub link bestie, go click it if something's broken. 🔥

---

👑 AUTHOR - Chris Fields 👑

Email cjfields-at-bioperl-dot-org

shoutout Chris, you ate that. 🌈

---

part 1 done, more coming, don't go anywhere 💜

🎀 APPENDIX 🎀

okay so this is the deep-dive part — every single object method gets its whole explanation here, bestie. just a heads up: internal methods are usually preceded with a _, so if you see an underscore just know it's giving backstage-pass energy 💅

---

🌟 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, slay. if filename is specified then open_dbm() gets called immediately — no waiting, no chill. Bio::Index::Abstract->new() is usually only called straight-up when you're opening an index that already exists.
• Returns: a new index object ✨
• Args:
  • -filename — the name of the dbm index file.
  • -write_flag — TRUE if you actually need write access to the dbm file.
  • -dbm_package — the Perl dbm module to use for the index.
  • -verbose — prints debugging output to STDERR if TRUE.

---

💖 Bio::Index::Stockholm implemented methods 💖

fetch_report

• Title: fetch_report
• Usage: my $align = $idx->fetch_report($id);
• Function: returns a Bio::SimpleAlign object for a specific alignment 🧬
• Returns: Bio::SimpleAlign
• Args: valid id

fetch_aln

• Title: fetch_aln
• Usage: my $align = $idx->fetch_aln($id);
• Function: returns a Bio::SimpleAlign object for a specific alignment
• Returns: Bio::SimpleAlign
• Args: valid id
• Note: it's literally an alias for fetch_report — same vibe, different name, iykyk

---

🌈 Require methods from Bio::Index::Abstract 🌈

_index_file

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

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. if nothing's been set it returns \&default_id_parser (peep below 👀). an entry gets added to the index for each string in the list it returns.
• Example: $index->id_parser( \&my_id_parser )
• Returns: a reference to CODE if you call it with no arguments
• Args: CODE

default_id_parser

• Title: default_id_parser
• Usage: $id = default_id_parser($line)
• Function: the default parser for Stockholm.pm
• Returns: array of specified ids
• Args: a 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 none if you're just 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 you're setting it, or none if you're just 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 that's being used. if the value is unset, it returns the value of the package variable $USE_DBM_TYPE, or if that is unset too, 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, fyi.
• Returns: the current value of dbm_package
• Args: value of dbm_package if you're setting it, or none if you're just getting the value.

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 get the actual file contents and not an object, bestie.

🚨 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 💀

open_dbm

• Usage: $index->open_dbm()
• Function: opens the dbm file that's 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 opened is whatever dbm_package() returns. the name of the file that gets 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. 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

_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. if the filehandle you asked for is already open, it just hands it back to you straight from 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:
• 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 the key $id. if $id is a reference to an array, then a new entry gets added under a key corresponding to each element of the array. multifunctional, we love to see it 💅
• 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, so it's a solid pick), 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 give 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. bye bestie 🫶
• Returns: NEVER
• Args: NONE

---

and that's the whole page, no crumbs left 💖 this was pulled from the perl v5.30.0 docs dated 2020-03-03 — go forth and index something iconic, you've got this 👑