Bio/DB/EntrezGene.pm

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