lib/Bio/Index/GenBank.pm

   1 #
   2 #
   3 # BioPerl module for Bio::Index::Abstract
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Ewan Birney <birney@sanger.ac.uk>
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Index::GenBank - Interface for indexing one or more GenBank
  16 files (i.e. flat file GenBank format).
  17
  18 =head1 SYNOPSIS
  19
  20     # Complete code for making an index for one or more GenBank files
  21     use strict;
  22     use Bio::Index::GenBank;
  23
  24     my $Index_File_Name = shift;
  25     my $inx = Bio::Index::GenBank->new(-filename => $Index_File_Name,
  26                                                            -write_flag => 'WRITE');
  27     $inx->make_index(@ARGV);
  28
  29     # Print out sequences present in the index in gcg format
  30     use Bio::Index::GenBank;
  31     use Bio::SeqIO;
  32     use strict;
  33
  34     my $Index_File_Name = shift;
  35     my $inx = Bio::Index::GenBank->new(-filename => $Index_File_Name);
  36     my $seqio = Bio::SeqIO->new(-format => 'gcg');
  37     foreach my $id (@ARGV) {
  38         my $seq = $inx->fetch($id); # Returns Bio::Seq object
  39         $seqio->write_seq($seq);
  40     }
  41
  42     # alternatively
  43     my ($locus, $acc);
  44     my $seq1 = $inx->get_Seq_by_id($locus);
  45     my $seq2 = $inx->get_Seq_by_acc($acc);
  46
  47 =head1 DESCRIPTION
  48
  49 By default the index that is created uses the LOCUS, ACCESSION, and
  50 VERSION identifiers as keys. Inherits functions for managing dbm
  51 files from Bio::Index::Abstract.pm, and provides the basic
  52 functionality for indexing GenBank files, and retrieving the
  53 sequence from them. For best results 'use strict'.
  54
  55 You can also set or customize the unique key used to retrieve by
  56 writing your own function and calling the id_parser() method.
  57 For example:
  58
  59    $inx->id_parser(\&get_id);
  60    # make the index
  61    $inx->make_index($file_name);
  62
  63    # here is where the retrieval key is specified
  64    sub get_id {
  65       my $line = shift;
  66       $line =~ /clone="(\S+)"/;
  67       $1;
  68    }
  69
  70 =head1 FEED_BACK
  71
  72 =head2 Mailing Lists
  73
  74 User feedback is an integral part of the evolution of this and other
  75 Bioperl modules. Send your comments and suggestions preferably to one
  76 of the Bioperl mailing lists.  Your participation is much appreciated.
  77
  78   bioperl-l@bioperl.org                  - General discussion
  79   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  80
  81 =head2 Support
  82
  83 Please direct usage questions or support issues to the mailing list:
  84
  85 I<bioperl-l@bioperl.org>
  86
  87 rather than to the module maintainer directly. Many experienced and
  88 reponsive experts will be able look at the problem and quickly
  89 address it. Please include a thorough description of the problem
  90 with code and data examples if at all possible.
  91
  92 =head2 Reporting Bugs
  93
  94 Report bugs to the Bioperl bug tracking system to help us keep track
  95 the bugs and their resolution.  Bug reports can be submitted via
  96 the web:
  97
  98   https://github.com/bioperl/bioperl-live/issues
  99
 100 =head1 AUTHOR - Ewan Birney
 101
 102 Email - birney@ebi.ac.uk
 103
 104 =head1 APPENDIX
 105
 106 The rest of the documentation details each of the object methods.
 107 Internal methods are usually preceded with a _
 108
 109 =cut
 110
 111 # Let's begin the code...
 112
 113 package Bio::Index::GenBank;
 114
 115 use strict;
 116
 117 use Bio::Seq;
 118
 119 use base qw(Bio::Index::AbstractSeq);
 120
 121 sub _type_stamp {
 122     return '__GenBank_FLAT__'; # What kind of index are we?
 123 }
 124
 125 sub _version {
 126     return 0.1;
 127 }
 128
 129 =head2 _index_file
 130
 131   Title   : _index_file
 132   Usage   : $index->_index_file($file_name, $i)
 133   Function: Specialized function to index GenBank format files.
 134             Is provided with a filename and an integer
 135             by make_index in its SUPER class.
 136   Example :
 137   Returns :
 138   Args    :
 139
 140 =cut
 141
 142 sub _index_file {
 143     my( $self,
 144         $file,                  # File name
 145         $i                      # Index-number of file being indexed
 146         ) = @_;
 147
 148     my $begin = 0;
 149
 150     my $id_parser = $self->id_parser;
 151
 152     open my $GENBANK, '<', $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($GENBANK);
 161     my $curr_line  = <$GENBANK>;
 162     my $pos_diff   = tell($GENBANK) - $init_pos;
 163     my $correction = $pos_diff - length $curr_line;
 164     seek $GENBANK, $init_pos, 0; # Rewind position to proceed to read the file
 165
 166     while (<$GENBANK>) {
 167         if (/^LOCUS/) {
 168             $begin = tell($GENBANK) - 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 $GENBANK;
 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 : reference 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 GenBank.pm
 212   Returns : Array of specified ids
 213   Args    : a line string
 214
 215 =cut
 216
 217 #'
 218
 219 sub default_id_parser {
 220     my $line = shift;
 221     my %accs;
 222     if ( $line =~ /^LOCUS\s+(\S+)/ ) {
 223         $accs{$1}++;
 224     } elsif ( $line =~ /^ACCESSION\s+(.*)/ ) {
 225         for my $acc ( split(/\s+/,$1) ) {
 226             $accs{$acc}++;
 227         }
 228     } elsif ( /^VERSION\s+(.*)/) {
 229         my $x = $1;
 230         for my $acc ( split(/\s+/,$1) ) {
 231             $acc=~ s/GI\://;
 232             $accs{$acc}++;
 233         }
 234     }
 235     keys %accs;
 236 }
 237
 238 =head2 _file_format
 239
 240  Title   : _file_format
 241  Usage   : Internal function for indexing system
 242  Function: Provides file format for this database
 243  Example :
 244  Returns :
 245  Args    :
 246
 247 =cut
 248
 249 sub _file_format{
 250    my ($self,@args) = @_;
 251    return 'GenBank';
 252 }
 253
 254 1;
 255
 256 __END__