Bio/DB/EMBL.pm

   1 #
   2 # $Id$
   3 #
   4 # BioPerl module for Bio::DB::EMBL
   5 #
   6 # Cared for by Heikki Lehvaslaiho <heikki-at-bioperl-dot-org>
   7 #
   8 # Copyright Jason Stajich
   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::DB::EMBL - Database object interface for EMBL entry retrieval
  17
  18 =head1 SYNOPSIS
  19
  20   use Bio::DB::EMBL;
  21
  22   $embl = Bio::DB::EMBL->new();
  23
  24   # remember that EMBL_ID does not equal GenBank_ID!
  25   $seq = $embl->get_Seq_by_id('BUM'); # EMBL ID
  26   print "cloneid is ", $seq->id, "\n";
  27
  28   # or changeing to accession number and Fasta format ...
  29   $embl->request_format('fasta');
  30   $seq = $embl->get_Seq_by_acc('J02231'); # EMBL ACC
  31   print "cloneid is ", $seq->id, "\n";
  32
  33   # especially when using versions, you better be prepared
  34   # in not getting what what want
  35   eval {
  36       $seq = $embl->get_Seq_by_version('J02231.1'); # EMBL VERSION
  37   };
  38   print "cloneid is ", $seq->id, "\n" unless $@;
  39
  40   # or ... best when downloading very large files, prevents
  41   # keeping all of the file in memory
  42
  43   # also don't want features, just sequence so let's save bandwith
  44   # and request Fasta sequence
  45   $embl = Bio::DB::EMBL->new(-retrievaltype => 'tempfile' ,
  46                             -format => 'fasta');
  47   my $seqio = $embl->get_Stream_by_id(['AC013798', 'AC021953'] );
  48   while( my $clone =  $seqio->next_seq ) {
  49         print "cloneid is ", $clone->id, "\n";
  50   }
  51
  52 =head1 DESCRIPTION
  53
  54 Allows the dynamic retrieval of sequence objects L<Bio::Seq> from the
  55 EMBL database using the dbfetch script at EBI:
  56 L<http://www.ebi.ac.uk/cgi-bin/dbfetch>.
  57
  58 In order to make changes transparent we have host type (currently only
  59 ebi) and location (defaults to ebi) separated out.  This allows later
  60 additions of more servers in different geographical locations.
  61
  62 The functionality of this module is inherited from L<Bio::DB::DBFetch>
  63 which implements L<Bio::DB::WebDBSeqI>.
  64
  65 =head1 FEEDBACK
  66
  67 =head2 Mailing Lists
  68
  69 User feedback is an integral part of the evolution of this and other
  70 Bioperl modules. Send your comments and suggestions preferably to one
  71 of the Bioperl mailing lists.  Your participation is much appreciated.
  72
  73   bioperl-l@bioperl.org                  - General discussion
  74   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  75
  76 =head2 Reporting Bugs
  77
  78 Report bugs to the Bioperl bug tracking system to help us keep track
  79 the bugs and their resolution.  Bug reports can be submitted via the
  80 web:
  81
  82   http://bugzilla.open-bio.org/
  83
  84 =head1 AUTHOR - Heikki Lehvaslaiho
  85
  86 Email Heikki Lehvaslaiho E<lt>heikki-at-bioperl-dot-orgE<gt>
  87
  88 =head1 APPENDIX
  89
  90 The rest of the documentation details each of the object
  91 methods. Internal methods are usually preceded with a _
  92
  93 =cut
  94
  95 # Let the code begin...
  96
  97 package Bio::DB::EMBL;
  98 use strict;
  99 use vars qw($MODVERSION %HOSTS %FORMATMAP  $DEFAULTFORMAT);
 100
 101 $MODVERSION = '0.2';
 102 use Bio::DB::RefSeq;
 103
 104 use base qw(Bio::DB::DBFetch);
 105
 106 BEGIN {
 107     # you can add your own here theoretically.
 108     %HOSTS = (
 109                'dbfetch' => {
 110                    baseurl => 'http://%s/cgi-bin/dbfetch?db=embl&style=raw',
 111                    hosts   => {
 112                        'ebi'  => 'www.ebi.ac.uk'
 113                        }
 114                }
 115               );
 116     %FORMATMAP = ( 'embl' => 'embl',
 117                    'fasta' => 'fasta'
 118                    );
 119     $DEFAULTFORMAT = 'embl';
 120 }
 121
 122 =head2 new
 123
 124  Title   : new
 125  Usage   : $gb = Bio::DB::GenBank->new(@options)
 126  Function: Creates a new genbank handle
 127  Returns : New genbank handle
 128  Args    : -delay   number of seconds to delay between fetches (3s)
 129
 130 NOTE:  There are other options that are used internally.
 131
 132 =cut
 133
 134 sub new {
 135     my ($class, @args ) = @_;
 136     my $self = $class->SUPER::new(@args);
 137
 138     $self->{ '_hosts' } = {};
 139     $self->{ '_formatmap' } = {};
 140
 141     $self->hosts(\%HOSTS);
 142     $self->formatmap(\%FORMATMAP);
 143     $self->{'_default_format'} = $DEFAULTFORMAT;
 144
 145     return $self;
 146 }
 147
 148
 149 =head2 Bio::DB::WebDBSeqI methods
 150
 151 Overriding WebDBSeqI method to help newbies to retrieve sequences.
 152 EMBL database is all too often passed RefSeq accessions. This
 153 redirects those calls. See L<Bio::DB::RefSeq>.
 154
 155
 156 =head2 get_Stream_by_acc
 157
 158   Title   : get_Stream_by_acc
 159   Usage   : $seq = $db->get_Seq_by_acc([$acc1, $acc2]);
 160   Function: Gets a series of Seq objects by accession numbers
 161   Returns : a Bio::SeqIO stream object
 162   Args    : $ref : a reference to an array of accession numbers for
 163                    the desired sequence entries
 164   Note    : For GenBank, this just calls the same code for get_Stream_by_id()
 165
 166 =cut
 167
 168 sub get_Stream_by_acc {
 169     my ($self, $ids ) = @_;
 170     my $newdb = $self->_check_id($ids);
 171     if ($newdb && $newdb->isa('Bio::DB::RefSeq')) {
 172         return $newdb->get_seq_stream('-uids' => $ids, '-mode' => 'single');
 173     } else {
 174         return $self->get_seq_stream('-uids' => $ids, '-mode' => 'single');
 175     }
 176 }
 177
 178
 179 =head2 _check_id
 180
 181   Title   : _check_id
 182   Usage   :
 183   Function:
 184   Returns : A Bio::DB::RefSeq reference or throws
 185   Args    : $id(s), $string
 186
 187 =cut
 188
 189 sub _check_id {
 190     my ($self, $ids) = @_;
 191
 192     # NT contigs can not be retrieved
 193     $self->throw("NT_ contigs are whole chromosome files which are not part of regular".
 194                  "database distributions. Go to ftp://ftp.ncbi.nih.gov/genomes/.")
 195         if $ids =~ /NT_/;
 196
 197     # Asking for a RefSeq from EMBL/GenBank
 198
 199     if ($ids =~ /N._/) {
 200         $self->warn("[$ids] is not a normal sequence entry but a RefSeq entry.".
 201                    " Redirecting the request.\n")
 202             if $self->verbose >= 0;
 203         return  Bio::DB::RefSeq->new(-verbose => $self->verbose);
 204     }
 205 }
 206
 207
 208 1;