Bio/Index/GenBank.pm

   1 #
   2 # $Id$
   3 #
   4 # BioPerl module for Bio::Index::Abstract
   5 #
   6 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   7 #
   8 # Cared for by Ewan Birney <birney@sanger.ac.uk>
   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::GenBank - Interface for indexing one or more GenBank
  17 files (i.e. flat file GenBank format).
  18
  19 =head1 SYNOPSIS
  20
  21     # Complete code for making an index for one or more GenBank files
  22     use strict;
  23     use Bio::Index::GenBank;
  24
  25     my $Index_File_Name = shift;
  26     my $inx = Bio::Index::GenBank->new(-filename => $Index_File_Name,
  27                                                            -write_flag => 'WRITE');
  28     $inx->make_index(@ARGV);
  29
  30     # Print out sequences present in the index in gcg format
  31     use Bio::Index::GenBank;
  32     use Bio::SeqIO;
  33     use strict;
  34
  35     my $Index_File_Name = shift;
  36     my $inx = Bio::Index::GenBank->new(-filename => $Index_File_Name);
  37     my $seqio = Bio::SeqIO->new(-format => 'gcg');
  38     foreach my $id (@ARGV) {
  39         my $seq = $inx->fetch($id); # Returns Bio::Seq object
  40         $seqio->write_seq($seq);
  41     }
  42
  43     # alternatively
  44     my ($locus, $acc);
  45     my $seq1 = $inx->get_Seq_by_id($locus);
  46     my $seq2 = $inx->get_Seq_by_acc($acc);
  47
  48 =head1 DESCRIPTION
  49
  50 By default the index that is created uses the LOCUS, ACCESSION, and
  51 VERSION identifiers as keys. Inherits functions for managing dbm
  52 files from Bio::Index::Abstract.pm, and provides the basic
  53 functionality for indexing GenBank files, and retrieving the
  54 sequence from 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($file_name);
  63
  64    # here is where the retrieval key is specified
  65    sub get_id {
  66       my $line = shift;
  67       $line =~ /clone="(\S+)"/;
  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 L<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   http://bugzilla.open-bio.org/
 100
 101 =head1 AUTHOR - Ewan Birney
 102
 103 Email - birney@ebi.ac.uk
 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::GenBank;
 115
 116 use strict;
 117
 118 use Bio::Seq;
 119
 120 use base qw(Bio::Index::AbstractSeq);
 121
 122 sub _type_stamp {
 123     return '__GenBank_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: Specialized function to index GenBank 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     my( $self,
 145         $file,                  # File name
 146         $i                      # Index-number of file being indexed
 147         ) = @_;
 148
 149     my $begin = 0;
 150
 151     my $id_parser = $self->id_parser;
 152
 153     open my $GENBANK, '<', $file or
 154         $self->throw("Can't open file for read : $file");
 155
 156     my %done_ids;
 157     while (<$GENBANK>) {
 158         if (/^LOCUS/) {
 159             $begin = tell($GENBANK) - length($_);
 160         }
 161         for my $id (&$id_parser($_)) {
 162             next if exists $done_ids{$id};
 163             $self->add_record($id, $i, $begin) if $id;
 164             $done_ids{$id} = 1;
 165         }
 166         if (m{//}) {
 167             %done_ids = ();
 168         }
 169     }
 170     close $GENBANK;
 171     return 1;
 172 }
 173
 174 =head2 id_parser
 175
 176   Title   : id_parser
 177   Usage   : $index->id_parser( CODE )
 178   Function: Stores or returns the code used by record_id to
 179             parse the ID for record from a string.
 180             Returns \&default_id_parser (see below) if not
 181             set. An entry will be added to
 182             the index for each string in the list returned.
 183   Example : $index->id_parser( \&my_id_parser )
 184   Returns : reference to CODE if called without arguments
 185   Args    : CODE
 186
 187 =cut
 188
 189 sub id_parser {
 190     my ($self,$code) = @_;
 191
 192     if ($code) {
 193         $self->{'_id_parser'} = $code;
 194     }
 195     return $self->{'_id_parser'} || \&default_id_parser;
 196 }
 197
 198 =head2 default_id_parser
 199
 200   Title   : default_id_parser
 201   Usage   : $id = default_id_parser($line)
 202   Function: The default parser for GenBank.pm
 203   Returns : Array of specified ids
 204   Args    : a line string
 205
 206 =cut
 207
 208 #'
 209
 210 sub default_id_parser {
 211     my $line = shift;
 212     my %accs;
 213     if ( $line =~ /^LOCUS\s+(\S+)/ ) {
 214         $accs{$1}++;
 215     } elsif ( $line =~ /^ACCESSION\s+(.*)/ ) {
 216         for my $acc ( split(/\s+/,$1) ) {
 217             $accs{$acc}++;
 218         }
 219     } elsif ( /^VERSION\s+(.*)/) {
 220         my $x = $1;
 221         for my $acc ( split(/\s+/,$1) ) {
 222             $acc=~ s/GI\://;
 223             $accs{$acc}++;
 224         }
 225     }
 226     keys %accs;
 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 =cut
 239
 240 sub _file_format{
 241    my ($self,@args) = @_;
 242    return 'GenBank';
 243 }
 244
 245 1;
 246
 247 __END__