Bio/DB/EntrezGene.pm

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