Bio/Index/Stockholm.pm

   1 #
   2 # BioPerl module for Bio::Index::Stockholm
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Chris Fields <cjfields@uiuc.edu>
   7 #
   8 # Copyright Chris Fields
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Index::Stockholm
  17
  18 =head1 SYNOPSIS
  19
  20     use strict;
  21     use Bio::Index::Stockholm;
  22     my ($indexfile,$file1,$file2,$query);
  23     my $index = Bio::Index::Stockholm->new(-filename => $indexfile,
  24                                                           -write_flag => 1);
  25     $index->make_index($file1,$file2);
  26
  27     # get raw data stream starting at alignment position
  28     my $fh = $index->get_stream($query);
  29
  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";
  34
  35 =head1 DESCRIPTION
  36
  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
  39 (via Bio::AlignIO).
  40
  41 This module also allows for ID parsing using a callback:
  42
  43    $inx->id_parser(\&get_id);
  44    # make the index
  45    $inx->make_index($file_name);
  46
  47    # here is where the retrieval key is specified
  48    sub get_id {
  49       my $line = shift;
  50       $line =~ /^>.+gi\|(\d+)/;
  51       $1;
  52    }
  53
  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.
  57
  58 Note: for best results 'use strict'.
  59
  60 =head1 TODO
  61
  62 - allow using an alternative regex for indexing (for instance, the ID instead of AC)
  63
  64 =head1 FEEDBACK
  65
  66 =head2 Mailing Lists
  67
  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.
  71
  72   bioperl-l@bioperl.org                  - General discussion
  73   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  74
  75 =head2 Support
  76
  77 Please direct usage questions or support issues to the mailing list:
  78
  79 I<bioperl-l@bioperl.org>
  80
  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.
  85
  86 =head2 Reporting Bugs
  87
  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
  90 web:
  91
  92   https://github.com/bioperl/bioperl-live/issues
  93
  94 =head1 AUTHOR - Chris Fields
  95
  96 Email cjfields-at-bioperl-dot-org
  97
  98 =head1 APPENDIX
  99
 100 The rest of the documentation details each of the object methods.
 101 Internal methods are usually preceded with a _
 102
 103 =cut
 104
 105 # Let the code begin...
 106
 107 package Bio::Index::Stockholm;
 108 use strict;
 109 use Bio::AlignIO;
 110
 111 use base qw(Bio::Index::Abstract Bio::Root::Root);
 112
 113 sub _version {
 114         return ${Bio::Root::Version::VERSION};
 115 }
 116
 117 =head2 new
 118
 119   Usage   : $index = Bio::Index::Abstract->new(
 120                 -filename    => $dbm_file,
 121                 -write_flag  => 0,
 122                 -dbm_package => 'DB_File',
 123                 -verbose     => 0);
 124
 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
 132                          needed.
 133             -dbm_package The Perl dbm module to use for the
 134                          index.
 135             -verbose     Print debugging output to STDERR if
 136                          TRUE.
 137
 138 =cut
 139
 140 sub new {
 141
 142   my($class,@args) = @_;
 143
 144   my $self = $class->SUPER::new(@args);
 145
 146 }
 147
 148 =head2 Bio::Index::Stockholm implemented methods
 149
 150 =cut
 151
 152 =head2 fetch_report
 153
 154  Title   : fetch_report
 155  Usage   : my $align = $idx->fetch_report($id);
 156  Function: Returns a Bio::SimpleAlign object
 157            for a specific alignment
 158  Returns : Bio::SimpleAlign
 159  Args    : valid id
 160
 161 =cut
 162
 163 sub fetch_report{
 164         my ($self,$id) = @_;
 165         my $fh = $self->get_stream($id);
 166         my $report = Bio::AlignIO->new(-noclose => 1,
 167                                                                         -format => 'stockholm',
 168                                                             -fh => $fh);
 169         return $report->next_aln;
 170 }
 171
 172 =head2 fetch_aln
 173
 174  Title   : fetch_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
 179  Args    : valid id
 180  Note    : alias for fetch_report
 181
 182 =cut
 183
 184 *fetch_aln = \&fetch_report;
 185
 186 =head2 Require methods from Bio::Index::Abstract
 187
 188 =cut
 189
 190 =head2 _index_file
 191
 192   Title   : _index_file
 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.
 197   Example :
 198   Returns :
 199   Args    :
 200
 201 =cut
 202
 203 sub _index_file {
 204   my( $self,
 205       $file,  # File name
 206       $i      # Index-number of file being indexed
 207   ) = @_;
 208
 209   my $begin = 0;
 210
 211   my $id_parser = $self->id_parser;
 212
 213   open my $STOCKHOLM, '<', $file or $self->throw("Could not read file '$file': $!");
 214
 215   my %done_ids;
 216
 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
 226
 227   while (<$STOCKHOLM>) {
 228       if ( /^#\sSTOCKHOLM/ ) {
 229         $begin = tell($STOCKHOLM) - length($_) - $correction;
 230       }
 231
 232       for my $id ( &$id_parser($_) ) {
 233         next if exists $done_ids{$id};
 234         $self->add_record($id, $i, $begin) if $id;
 235         $done_ids{$id} = 1;
 236       }
 237
 238       %done_ids = () if ( m{//} );
 239   }
 240   close $STOCKHOLM;
 241
 242   1;
 243 }
 244
 245
 246 =head2 id_parser
 247
 248   Title   : id_parser
 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
 257   Args    : CODE
 258
 259 =cut
 260
 261 sub id_parser {
 262   my ($self,$code) = @_;
 263
 264   if ($code) {
 265     $self->{'_id_parser'} = $code;
 266   }
 267   return $self->{'_id_parser'} || \&default_id_parser;
 268 }
 269
 270 =head2 default_id_parser
 271
 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
 276   Args    : a line string
 277
 278 =cut
 279
 280 sub default_id_parser {
 281   my $line = shift;
 282   my %accs;
 283
 284   if ( $line =~ /^#=GF AC\s+(\S+)/ ) {
 285     $accs{$1}++;
 286   }
 287   keys %accs;
 288 }
 289
 290 =head2 Bio::Index::Abstract methods
 291
 292 =cut
 293
 294 =head2 filename
 295
 296  Title   : filename
 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
 302            getting the value.
 303
 304 =head2 write_flag
 305
 306  Title   : write_flag
 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
 311            write access.
 312  Returns : The current value of write_flag (default 0)
 313  Args    : Value of write_flag if setting, or none if
 314            getting the value.
 315
 316 =head2 dbm_package
 317
 318  Usage   : $value = $self->dbm_package();
 319            $self->dbm_package($value);
 320
 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
 327            types.
 328
 329  Returns : The current value of dbm_package
 330  Args    : Value of dbm_package if setting, or none if
 331            getting the value.
 332
 333
 334 =head2 get_stream
 335
 336  Title   : get_stream
 337  Usage   : $stream = $index->get_stream( $id );
 338  Function: Returns a file handle with the file pointer
 339            at the approprite place
 340
 341            This provides for a way to get the actual
 342            file contents and not an object
 343
 344            WARNING: you must parse the record deliminter
 345            *yourself*. Abstract wont do this for you
 346            So this code
 347
 348            $fh = $index->get_stream($myid);
 349            while( <$fh> ) {
 350               # do something
 351            }
 352            will parse the entire file if you do not put in
 353            a last statement in, like
 354
 355            while( <$fh> ) {
 356               /^\/\// && last; # end of record
 357               # do something
 358            }
 359
 360  Returns : A filehandle object
 361  Args    : string represents the accession number
 362  Notes   : This method should not be used without forethought
 363
 364
 365 =head2 open_dbm
 366
 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.
 375
 376   Example : $index->_open_dbm()
 377   Returns : 1 on success
 378
 379
 380 =head2 _version
 381
 382   Title   : _version
 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
 388   Example :
 389   Returns :
 390   Args    : none
 391
 392 =head2 _filename
 393
 394   Title   : _filename
 395   Usage   : $index->_filename( FILE INT )
 396   Function: Indexes the file
 397   Example :
 398   Returns :
 399   Args    :
 400
 401 =head2 _file_handle
 402
 403   Title   : _file_handle
 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
 412   Args    : INT
 413
 414 =head2 _file_count
 415
 416   Title   : _file_count
 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
 421             without an argument.
 422   Example :
 423   Returns : INT
 424   Args    : INT
 425
 426
 427 =head2 add_record
 428
 429   Title   : add_record
 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
 435             of the array.
 436   Example : $index->add_record( $id, $fileNumber, $begin, $end )
 437   Returns : TRUE on success or FALSE on failure
 438   Args    : ID LIST
 439
 440 =head2 pack_record
 441
 442   Title   : pack_record
 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
 449   Args    : LIST
 450
 451 =head2 unpack_record
 452
 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
 460
 461 =head2 DESTROY
 462
 463  Title   : DESTROY
 464  Usage   : Called automatically when index goes out of scope
 465  Function: Closes connection to database and handles to
 466            sequence files
 467  Returns : NEVER
 468  Args    : NONE
 469
 470
 471 =cut
 472
 473 1;