2 # BioPerl module for Bio::Index::Stockholm
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Chris Fields <cjfields@uiuc.edu>
8 # Copyright Chris Fields
10 # You may distribute this module under the same terms as perl itself
12 # POD documentation - main docs before the code
21 use Bio::Index::Stockholm;
22 my ($indexfile,$file1,$file2,$query);
23 my $index = Bio::Index::Stockholm->new(-filename => $indexfile,
25 $index->make_index($file1,$file2);
27 # get raw data stream starting at alignment position
28 my $fh = $index->get_stream($query);
30 # fetch individual alignment
31 my $align = $index->fetch_aln($query); # alias for fetch_report
32 my $align = $index->fetch_report($query); # same as above
33 print "query is ", $align->display_id, "\n";
37 Indexes Stockholm format alignments such as those from Pfam and Rfam.
38 Returns raw stream data using the ID or a Bio::SimpleAlign object
41 This module also allows for ID parsing using a callback:
43 $inx->id_parser(\&get_id);
45 $inx->make_index($file_name);
47 # here is where the retrieval key is specified
50 $line =~ /^>.+gi\|(\d+)/;
54 The indexer is capable of indexing based on multiple IDs passed back from the
55 callback; this is assuming of course all IDs are unique. The default is to use
56 the alignment ID provided for Rfam/Pfam output.
58 Note: for best results 'use strict'.
62 - allow using an alternative regex for indexing (for instance, the ID instead of AC)
68 User feedback is an integral part of the evolution of this and other
69 Bioperl modules. Send your comments and suggestions preferably to
70 the Bioperl mailing list. Your participation is much appreciated.
72 bioperl-l@bioperl.org - General discussion
73 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
77 Please direct usage questions or support issues to the mailing list:
79 I<bioperl-l@bioperl.org>
81 rather than to the module maintainer directly. Many experienced and
82 reponsive experts will be able look at the problem and quickly
83 address it. Please include a thorough description of the problem
84 with code and data examples if at all possible.
88 Report bugs to the Bioperl bug tracking system to help us keep track
89 of the bugs and their resolution. Bug reports can be submitted via the
92 https://redmine.open-bio.org/projects/bioperl/
94 =head1 AUTHOR - Chris Fields
96 Email cjfields-at-bioperl-dot-org
100 The rest of the documentation details each of the object methods.
101 Internal methods are usually preceded with a _
105 # Let the code begin...
107 package Bio
::Index
::Stockholm
;
111 use base
qw(Bio::Index::Abstract Bio::Root::Root);
114 return ${Bio
::Root
::Version
::VERSION
};
119 Usage : $index = Bio::Index::Abstract->new(
120 -filename => $dbm_file,
122 -dbm_package => 'DB_File',
125 Function: Returns a new index object. If filename is
126 specified, then open_dbm() is immediately called.
127 Bio::Index::Abstract->new() will usually be called
128 directly only when opening an existing index.
129 Returns : A new index object
130 Args : -filename The name of the dbm index file.
131 -write_flag TRUE if write access to the dbm file is
133 -dbm_package The Perl dbm module to use for the
135 -verbose Print debugging output to STDERR if
142 my($class,@args) = @_;
144 my $self = $class->SUPER::new
(@args);
148 =head2 Bio::Index::Stockholm implemented methods
155 Usage : my $align = $idx->fetch_report($id);
156 Function: Returns a Bio::SimpleAlign object
157 for a specific alignment
158 Returns : Bio::SimpleAlign
165 my $fh = $self->get_stream($id);
166 my $report = Bio
::AlignIO
->new(-noclose
=> 1,
167 -format
=> 'stockholm',
169 return $report->next_aln;
175 Usage : my $align = $idx->fetch_aln($id);
176 Function: Returns a Bio::SimpleAlign object
177 for a specific alignment
178 Returns : Bio::SimpleAlign
180 Note : alias for fetch_report
184 *fetch_aln
= \
&fetch_report
;
186 =head2 Require methods from Bio::Index::Abstract
193 Usage : $index->_index_file( $file_name, $i )
194 Function: Specialist function to index report file(s).
195 Is provided with a filename and an integer
196 by make_index in its SUPER class.
206 $i # Index-number of file being indexed
211 my $id_parser = $self->id_parser;
213 open my $STOCKHOLM, '<', $file or $self->throw("Could not read file '$file': $!");
217 # In Windows, text files have '\r\n' as line separator, but when reading in
218 # text mode Perl will only show the '\n'. This means that for a line "ABC\r\n",
219 # "length $_" will report 4 although the line is 5 bytes in length.
220 # We assume that all lines have the same line separator and only read current line.
221 my $init_pos = tell($STOCKHOLM);
222 my $curr_line = <$STOCKHOLM>;
223 my $pos_diff = tell($STOCKHOLM) - $init_pos;
224 my $correction = $pos_diff - length $curr_line;
225 seek $STOCKHOLM, $init_pos, 0; # Rewind position to proceed to read the file
227 while (<$STOCKHOLM>) {
228 if ( /^#\sSTOCKHOLM/ ) {
229 $begin = tell($STOCKHOLM) - length($_) - $correction;
232 for my $id ( &$id_parser($_) ) {
233 next if exists $done_ids{$id};
234 $self->add_record($id, $i, $begin) if $id;
238 %done_ids = () if ( m{//} );
249 Usage : $index->id_parser( CODE )
250 Function: Stores or returns the code used by record_id to
251 parse the ID for record from a string.
252 Returns \&default_id_parser (see below) if not
253 set. An entry will be added to
254 the index for each string in the list returned.
255 Example : $index->id_parser( \&my_id_parser )
256 Returns : reference to CODE if called without arguments
262 my ($self,$code) = @_;
265 $self->{'_id_parser'} = $code;
267 return $self->{'_id_parser'} || \
&default_id_parser
;
270 =head2 default_id_parser
272 Title : default_id_parser
273 Usage : $id = default_id_parser($line)
274 Function: The default parser for Stockholm.pm
275 Returns : Array of specified ids
280 sub default_id_parser
{
284 if ( $line =~ /^#=GF AC\s+(\S+)/ ) {
290 =head2 Bio::Index::Abstract methods
297 Usage : $value = $self->filename();
298 $self->filename($value);
299 Function: Gets or sets the name of the dbm index file.
300 Returns : The current value of filename
301 Args : Value of filename if setting, or none if
307 Usage : $value = $self->write_flag();
308 $self->write_flag($value);
309 Function: Gets or sets the value of write_flag, which
310 is wether the dbm file should be opened with
312 Returns : The current value of write_flag (default 0)
313 Args : Value of write_flag if setting, or none if
318 Usage : $value = $self->dbm_package();
319 $self->dbm_package($value);
321 Function: Gets or sets the name of the Perl dbm module used.
322 If the value is unset, then it returns the value of
323 the package variable $USE_DBM_TYPE or if that is
324 unset, then it chooses the best available dbm type,
325 choosing 'DB_File' in preference to 'SDBM_File'.
326 Bio::Abstract::Index may work with other dbm file
329 Returns : The current value of dbm_package
330 Args : Value of dbm_package if setting, or none if
337 Usage : $stream = $index->get_stream( $id );
338 Function: Returns a file handle with the file pointer
339 at the approprite place
341 This provides for a way to get the actual
342 file contents and not an object
344 WARNING: you must parse the record deliminter
345 *yourself*. Abstract wont do this for you
348 $fh = $index->get_stream($myid);
352 will parse the entire file if you do not put in
353 a last statement in, like
356 /^\/\// && last; # end of record
360 Returns : A filehandle object
361 Args : string represents the accession number
362 Notes : This method should not be used without forethought
367 Usage : $index->open_dbm()
368 Function: Opens the dbm file associated with the index
369 object. Write access is only given if explicitly
370 asked for by calling new(-write => 1) or having set
371 the write_flag(1) on the index object. The type of
372 dbm file opened is that returned by dbm_package().
373 The name of the file to be is opened is obtained by
374 calling the filename() method.
376 Example : $index->_open_dbm()
377 Returns : 1 on success
383 Usage : $type = $index->_version()
384 Function: Returns a string which identifes the version of an
385 index module. Used to permanently identify an index
386 file as having been created by a particular version
387 of the index module. Must be provided by the sub class
395 Usage : $index->_filename( FILE INT )
396 Function: Indexes the file
404 Usage : $fh = $index->_file_handle( INT )
405 Function: Returns an open filehandle for the file
406 index INT. On opening a new filehandle it
407 caches it in the @{$index->_filehandle} array.
408 If the requested filehandle is already open,
409 it simply returns it from the array.
410 Example : $fist_file_indexed = $index->_file_handle( 0 );
411 Returns : ref to a filehandle
417 Usage : $index->_file_count( INT )
418 Function: Used by the index building sub in a sub class to
419 track the number of files indexed. Sets or gets
420 the number of files indexed when called with or
430 Usage : $index->add_record( $id, @stuff );
431 Function: Calls pack_record on @stuff, and adds the result
432 of pack_record to the index database under key $id.
433 If $id is a reference to an array, then a new entry
434 is added under a key corresponding to each element
436 Example : $index->add_record( $id, $fileNumber, $begin, $end )
437 Returns : TRUE on success or FALSE on failure
443 Usage : $packed_string = $index->pack_record( LIST )
444 Function: Packs an array of scalars into a single string
445 joined by ASCII 034 (which is unlikely to be used
446 in any of the strings), and returns it.
447 Example : $packed_string = $index->pack_record( $fileNumber, $begin, $end )
448 Returns : STRING or undef
453 Title : unpack_record
454 Usage : $index->unpack_record( STRING )
455 Function: Splits the sting provided into an array,
456 splitting on ASCII 034.
457 Example : ( $fileNumber, $begin, $end ) = $index->unpack_record( $self->db->{$id} )
458 Returns : A 3 element ARRAY
459 Args : STRING containing ASCII 034
464 Usage : Called automatically when index goes out of scope
465 Function: Closes connection to database and handles to