lib/Bio/Index/Swissprot.pm

   1 #
   2 # BioPerl module for Bio::Index::Swissprot
   3 #
   4 # You may distribute this module under the same terms as perl itself
   5
   6 # POD documentation - main docs before the code
   7
   8 =head1 NAME
   9
  10 Bio::Index::Swissprot - Interface for indexing one or more
  11 Swissprot files.
  12
  13 =head1 SYNOPSIS
  14
  15   # Make an index for one or more Swissprot files:
  16
  17     use Bio::Index::Swissprot;
  18     use strict;
  19
  20     my $index_file_name = shift;
  21     my $inx = Bio::Index::Swissprot->new(
  22         -filename => $index_file_name,
  23         -write_flag => 1);
  24     $inx->make_index(@ARGV);
  25
  26   # Print out several sequences present in the index in Genbank
  27   # format:
  28
  29     use Bio::Index::Swissprot;
  30     use Bio::SeqIO;
  31     use strict;
  32
  33     my $out = Bio::SeqIO->new( -format => 'genbank',
  34                                -fh => \*STDOUT );
  35     my $index_file_name = shift;
  36     my $inx = Bio::Index::Swissprot->new(-filename => $index_file_name);
  37
  38     foreach my $id (@ARGV) {
  39         my $seq = $inx->fetch($id); # Returns a Bio::Seq object
  40         $out->write_seq($seq);
  41     }
  42
  43     # alternatively
  44     my ($id, $acc);
  45     my $seq1 = $inx->get_Seq_by_id($id);
  46     my $seq2 = $inx->get_Seq_by_acc($acc);
  47
  48 =head1 DESCRIPTION
  49
  50 By default the index that is created uses the AC and ID identifiers
  51 as keys. This module inherits functions for managing dbm files from
  52 Bio::Index::Abstract.pm, and provides the basic functionality
  53 for indexing Swissprot files and retrieving Sequence objects from
  54 them. For best results 'use strict'.
  55
  56 You can also set or customize the unique key used to retrieve by
  57 writing your own function and calling the id_parser() method.
  58 For example:
  59
  60    $inx->id_parser(\&get_id);
  61    # make the index
  62    $inx->make_index($index_file_name);
  63
  64    # here is where the retrieval key is specified
  65    sub get_id {
  66       my $line = shift;
  67       $line =~ /^KW\s+([A-Z]+)/i;
  68       $1;
  69    }
  70
  71 =head1 FEED_BACK
  72
  73 =head2 Mailing Lists
  74
  75 User feedback is an integral part of the evolution of this and other
  76 Bioperl modules. Send your comments and suggestions preferably to one
  77 of the Bioperl mailing lists.  Your participation is much appreciated.
  78
  79   bioperl-l@bioperl.org                  - General discussion
  80   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  81
  82 =head2 Support
  83
  84 Please direct usage questions or support issues to the mailing list:
  85
  86 I<bioperl-l@bioperl.org>
  87
  88 rather than to the module maintainer directly. Many experienced and
  89 reponsive experts will be able look at the problem and quickly
  90 address it. Please include a thorough description of the problem
  91 with code and data examples if at all possible.
  92
  93 =head2 Reporting Bugs
  94
  95 Report bugs to the Bioperl bug tracking system to help us keep track
  96 the bugs and their resolution.  Bug reports can be submitted via
  97 the web:
  98
  99   https://github.com/bioperl/bioperl-live/issues
 100
 101 =head1 AUTHOR - Ewan Birney
 102
 103 Also lorenz@ist.org, bosborne at alum.mit.edu
 104
 105 =head1 APPENDIX
 106
 107 The rest of the documentation details each of the object methods.
 108 Internal methods are usually preceded with a _
 109
 110 =cut
 111
 112 # Let's begin the code...
 113
 114 package Bio::Index::Swissprot;
 115
 116 use strict;
 117
 118 use Bio::Seq;
 119
 120 use base qw(Bio::Index::AbstractSeq);
 121
 122 sub _type_stamp {
 123         return '__Swissprot_FLAT__'; # What kind of index are we?
 124 }
 125
 126 sub _version {
 127         return 0.1;
 128 }
 129
 130 =head2 _index_file
 131
 132   Title   : _index_file
 133   Usage   : $index->_index_file( $file_name, $i )
 134   Function: Specialist function to index Swissprot format files.
 135             Is provided with a filename and an integer
 136             by make_index in its SUPER class.
 137   Example :
 138   Returns :
 139   Args    :
 140
 141 =cut
 142
 143 sub _index_file {
 144         # $file is file name, $i is number of file being indexed
 145         my( $self, $file, $i ) = @_;
 146
 147         # Offset from start of file
 148         my $begin = 0;
 149
 150         my $id_parser = $self->id_parser;
 151
 152         open my $SWISSPROT, '<', $file or $self->throw("Could not read file '$file': $!");
 153
 154         my %done_ids;
 155
 156         # In Windows, text files have '\r\n' as line separator, but when reading in
 157         # text mode Perl will only show the '\n'. This means that for a line "ABC\r\n",
 158         # "length $_" will report 4 although the line is 5 bytes in length.
 159         # We assume that all lines have the same line separator and only read current line.
 160         my $init_pos   = tell($SWISSPROT);
 161         my $curr_line  = <$SWISSPROT>;
 162         my $pos_diff   = tell($SWISSPROT) - $init_pos;
 163         my $correction = $pos_diff - length $curr_line;
 164         seek $SWISSPROT, $init_pos, 0; # Rewind position to proceed to read the file
 165
 166         while (<$SWISSPROT>) {
 167                 if (/^ID\s+\S+/) {
 168                         $begin = tell($SWISSPROT) - length( $_ ) - $correction;
 169                 }
 170                 for my $id (&$id_parser($_)) {
 171                         next if exists $done_ids{$id};
 172                         $self->add_record($id, $i, $begin) if $id;
 173                         $done_ids{$id} = 1;
 174                 }
 175         if (m{//}) {
 176             %done_ids = ();
 177         }
 178         }
 179         close $SWISSPROT;
 180         return 1;
 181 }
 182
 183 =head2 id_parser
 184
 185   Title   : id_parser
 186   Usage   : $index->id_parser( CODE )
 187   Function: Stores or returns the code used by record_id to
 188             parse the ID for record from a string.
 189             Returns \&default_id_parser (see below) if not
 190             set. An entry will be added to
 191             the index for each string in the list returned.
 192   Example : $index->id_parser( \&my_id_parser )
 193   Returns : ref to CODE if called without arguments
 194   Args    : CODE
 195
 196 =cut
 197
 198 sub id_parser {
 199         my( $self, $code ) = @_;
 200
 201         if ($code) {
 202                 $self->{'_id_parser'} = $code;
 203         }
 204         return $self->{'_id_parser'} || \&default_id_parser;
 205 }
 206
 207 =head2 default_id_parser
 208
 209   Title   : default_id_parser
 210   Usage   : $id = default_id_parser( $line )
 211   Function: The default parser for Swissprot.pm
 212             Returns $1 from applying the regexp /^ID\s*(\S+)/
 213             or /^AC\s+([A-Z0-9]+)/ to the current line.
 214   Returns : ID string
 215   Args    : a line string
 216
 217 =cut
 218
 219 sub default_id_parser {
 220         my $line = shift;
 221         if ($line =~ /^ID\s*(\S+)/) {
 222                 return $1;
 223         }
 224         elsif ($line =~ /^AC\s+([A-Z0-9]+)/) {
 225                 return $1;
 226         }
 227 }
 228
 229 =head2 _file_format
 230
 231  Title   : _file_format
 232  Usage   : Internal function for indexing system
 233  Function: Provides file format for this database
 234  Example :
 235  Returns :
 236  Args    :
 237
 238
 239 =cut
 240
 241 sub _file_format {
 242    return 'swiss';
 243 }
 244
 245 1;
 246
 247 __END__