branch-1-6/Bio/DB/EntrezGene.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::EntrezGene
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Brian Osborne bosborne at alum.mit.edu
   8 #
   9 # Copyright Brian Osborne
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::DB::EntrezGene - Database object interface to Entrez Gene
  18
  19 =head1 SYNOPSIS
  20
  21     use Bio::DB::EntrezGene;
  22
  23     my $db = Bio::DB::EntrezGene->new;
  24
  25     my $seq = $db->get_Seq_by_id(2); # Gene id
  26
  27     # or ...
  28
  29     my $seqio = $db->get_Stream_by_id([2, 4693, 3064]); # Gene ids
  30     while ( my $seq = $seqio->next_seq ) {
  31             print "id is ", $seq->display_id, "\n";
  32     }
  33
  34 =head1 DESCRIPTION
  35
  36 Allows the dynamic retrieval of Sequence objects from the
  37 Entrez Gene database at NCBI, via an Entrez query using Gene ids.
  38
  39 This module requires the CPAN Bio::ASN1 module.
  40
  41 WARNING: Please do NOT spam the Entrez web server with multiple requests.
  42 NCBI offers Batch Entrez for this purpose.
  43
  44 =head1 NOTES
  45
  46 The Entrez eutils API does not allow Entrez Gene queries by name as
  47 of this writing, therefore there are only get_Seq_by_id and
  48 get_Stream_by_id methods in this module, and these expect Gene ids.
  49 There are no get_Seq_by_acc or get_Stream_by_acc methods.
  50
  51 =head1 FEEDBACK
  52
  53 =head2 Mailing Lists
  54
  55 User feedback is an integral part of the
  56 evolution of this and other Bioperl modules. Send
  57 your comments and suggestions preferably to one
  58 of the Bioperl mailing lists. Your participation
  59 is much appreciated.
  60
  61   bioperl-l@bioperl.org                  - General discussion
  62   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  63
  64 =head2 Support
  65
  66 Please direct usage questions or support issues to the mailing list:
  67
  68 I<bioperl-l@bioperl.org>
  69
  70 rather than to the module maintainer directly. Many experienced and
  71 reponsive experts will be able look at the problem and quickly
  72 address it. Please include a thorough description of the problem
  73 with code and data examples if at all possible.
  74
  75 =head2 Reporting Bugs
  76
  77 Report bugs to the Bioperl bug tracking system to help us keep track
  78 the bugs and their resolution.  Bug reports can be submitted via the
  79 web:
  80
  81   http://bugzilla.open-bio.org/
  82
  83 =head1 AUTHOR - Brian Osborne
  84
  85 Email bosborne at alum.mit.edu
  86
  87 =head1 APPENDIX
  88
  89 The rest of the documentation details each of the object
  90 methods. Internal methods are usually preceded with a _
  91
  92 =cut
  93
  94 # Let the code begin...
  95
  96 package Bio::DB::EntrezGene;
  97 use strict;
  98 use vars qw($DEFAULTFORMAT $DEFAULTMODE %PARAMSTRING);
  99
 100 use base qw(Bio::DB::NCBIHelper);
 101 BEGIN {
 102     $DEFAULTMODE   = 'single';
 103     $DEFAULTFORMAT = 'asn.1';
 104     %PARAMSTRING = ('batch'  => {'db'     => 'gene',
 105                                                                                          'usehistory' => 'y',
 106                                                                                          'tool'   => 'bioperl',
 107                                                                                          'retmode' => 'asn.1'},
 108                                                    'gi'     => {'db'     => 'gene',
 109                                                                                          'usehistory' => 'y',
 110                                                                                          'tool'   => 'bioperl',
 111                                                                                          'retmode' => 'asn.1'},
 112                                                   'version' => {'db'     => 'gene',
 113                                                                                          'usehistory' => 'y',
 114                                                                                          'tool'   => 'bioperl',
 115                                                                                          'retmode' => 'asn.1'},
 116                                                   'single'  => {'db'     => 'gene',
 117                                                                                          'usehistory' => 'y',
 118                                                                                          'tool'   => 'bioperl',
 119                                                                                          'retmode' => 'asn.1'} );
 120 }
 121
 122 # the new way to make modules a little more lightweight
 123 sub new {
 124   my($class, @args) = @_;
 125   my $self = $class->SUPER::new(@args);
 126   # Seems that Bio::SeqIO::entrezgene requires this:
 127   $self->{_retrieval_type} = "tempfile";
 128   $self->request_format($self->default_format);
 129   return $self;
 130 }
 131
 132 =head2 get_params
 133
 134  Title   : get_params
 135  Usage   : my %params = $self->get_params($mode)
 136  Function: Returns key,value pairs to be passed to NCBI database
 137            for either 'batch' or 'single' sequence retrieval method
 138  Returns : A key,value pair hash
 139  Args    : 'single' or 'batch' mode for retrieval
 140
 141 =cut
 142
 143 sub get_params {
 144     my ($self, $mode) = @_;
 145     return defined $PARAMSTRING{$mode} ? %{$PARAMSTRING{$mode}} :
 146                 %{$PARAMSTRING{$DEFAULTMODE}};
 147 }
 148
 149 =head2 default_format
 150
 151  Title   : default_format
 152  Usage   : my $format = $self->default_format
 153  Function: Returns default sequence format for this module
 154  Returns : string
 155  Args    : none
 156
 157 =cut
 158
 159 sub default_format {
 160         return $DEFAULTFORMAT;
 161 }
 162
 163 # from Bio::DB::WebDBSeqI from Bio::DB::RandomAccessI
 164
 165 =head1 Routines from Bio::DB::WebDBSeqI and Bio::DB::RandomAccessI
 166
 167 =head2 get_Seq_by_id
 168
 169  Title   : get_Seq_by_id
 170  Usage   : $seq = $db->get_Seq_by_id(2)
 171  Function: Gets a Bio::Seq object by its name
 172  Returns : A Bio::Seq object
 173  Args    : Gene id
 174  Throws  : "id does not exist" exception
 175
 176 =head1 Routines implemented by Bio::DB::NCBIHelper
 177
 178 =head2 get_request
 179
 180  Title   : get_request
 181  Usage   : my $url = $self->get_request
 182  Function: HTTP::Request
 183  Returns :
 184  Args    : %qualifiers = a hash of qualifiers (ids, format, etc)
 185
 186 =head2 get_Stream_by_id
 187
 188   Title   : get_Stream_by_id
 189   Usage   : $stream = $db->get_Stream_by_id( [$gid1, $gid2] );
 190   Function: Gets a series of Seq objects using Gene ids
 191   Returns : A Bio::SeqIO stream object
 192   Args    : A reference to an array of Gene ids
 193
 194 =head2 request_format
 195
 196  Title   : request_format
 197  Usage   : my $format = $self->request_format;
 198            $self->request_format($format);
 199  Function: Get or set sequence format retrieval
 200  Returns : String representing format
 201  Args    : $format = sequence format
 202
 203 =cut
 204
 205 # override to force format
 206 sub request_format {
 207     my ($self) = @_;
 208     return $self->SUPER::request_format($self->default_format());
 209 }
 210
 211 1;
 212
 213 __END__