Bio/DB/GenPept.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::DB::GenPept
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Aaron Mackey <amackey@virginia.edu>
   8 #
   9 # Copyright Aaron Mackey
  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 # completely reworked by Jason Stajich to use Bio::DB::WebDBSeqI 2000-12-12
  16
  17 =head1 NAME
  18
  19 Bio::DB::GenPept - Database object interface to GenPept
  20
  21 =head1 SYNOPSIS
  22
  23     $gb = Bio::DB::GenPept->new();
  24
  25     $seq = $gb->get_Seq_by_id('195055'); # Unique ID
  26
  27     # or ...
  28
  29     $seq = $gb->get_Seq_by_acc('DEECTH'); # Accession Number
  30
  31     my $seqio = $gb->get_Stream_by_id(['195055', 'DEECTH']);
  32     while( my $seq = $seqio->next_seq ) {
  33             print "seq is is ", $seq->display_id, "\n";
  34     }
  35
  36 =head1 DESCRIPTION
  37
  38 Allows the dynamic retrieval of Sequence objects (Bio::Seq) from the GenPept
  39 database at NCBI, via an Entrez query.
  40
  41 WARNING: Please do NOT spam the Entrez web server with multiple requests.
  42 NCBI offers Batch Entrez for this purpose.  Batch Entrez support will likely
  43 be supported in a future version of DB::GenPept.
  44
  45 Currently the only return format supported by NCBI Entrez for GenPept
  46 database is GenPept format, so any format specification passed to
  47 GenPept will be ignored still be forced to GenPept format (which is
  48 just GenBank format).
  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 L<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   http://bugzilla.open-bio.org/
  81
  82 =head1 AUTHOR - Aaron Mackey, Jason Stajich
  83
  84 Email amackey@virginia.edu
  85 Email jason@bioperl.org
  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::GenPept;
  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 = 'gp';
 104     %PARAMSTRING = (
 105                      'batch' => { 'db'     => 'protein',
 106                                   'usehistory' => 'n',
 107                                   'tool'   => 'bioperl'},
 108                          # no query?
 109                      'gi' => { 'db'     => 'protein',
 110                                'usehistory' => 'n',
 111                                'tool'   => 'bioperl',
 112                                'retmode' => 'text'},
 113                      'version' => { 'db'     => 'protein',
 114                                     'usehistory' => 'n',
 115                                     'tool'   => 'bioperl',
 116                                     'retmode' => 'text'},
 117                      'single' => { 'db'     => 'protein',
 118                                    'usehistory' => 'n',
 119                                    'tool'   => 'bioperl',
 120                                    'retmode' => 'text'},
 121                          'webenv' => {
 122                                   'query_key'  => 'querykey',
 123                                   'WebEnv'  => 'cookie',
 124                                   'db'     => 'protein',
 125                                   'usehistory' => 'n',
 126                                   'tool'   => 'bioperl',
 127                                   'retmode' => 'text'},
 128                      );
 129 }
 130
 131 # the new way to make modules a little more lightweight
 132 sub new {
 133   my($class, @args) = @_;
 134   my $self = $class->SUPER::new(@args);
 135   $self->request_format($self->default_format);
 136   return $self;
 137 }
 138
 139 =head2 get_params
 140
 141  Title   : get_params
 142  Usage   : my %params = $self->get_params($mode)
 143  Function: Returns key,value pairs to be passed to NCBI database
 144            for either 'batch' or 'single' sequence retrieval method
 145  Returns : a key,value pair hash
 146  Args    : 'single' or 'batch' mode for retrieval
 147
 148 =cut
 149
 150 sub get_params {
 151     my ($self, $mode) = @_;
 152     return defined $PARAMSTRING{$mode} ? %{$PARAMSTRING{$mode}} : %{$PARAMSTRING{$DEFAULTMODE}};
 153 }
 154
 155 =head2 default_format
 156
 157  Title   : default_format
 158  Usage   : my $format = $self->default_format
 159  Function: Returns default sequence format for this module
 160  Returns : string
 161  Args    : none
 162
 163 =cut
 164
 165 sub default_format {
 166     return $DEFAULTFORMAT;
 167 }
 168
 169 # from Bio::DB::WebDBSeqI from Bio::DB::RandomAccessI
 170
 171 =head1 Routines from Bio::DB::WebDBSeqI and Bio::DB::RandomAccessI
 172
 173 =head2 get_Seq_by_id
 174
 175  Title   : get_Seq_by_id
 176  Usage   : $seq = $db->get_Seq_by_id('ROA1_HUMAN')
 177  Function: Gets a Bio::Seq object by its name
 178  Returns : a Bio::Seq object
 179  Args    : the id (as a string) of a sequence
 180  Throws  : "id does not exist" exception
 181
 182 =head2 get_Seq_by_acc
 183
 184   Title   : get_Seq_by_acc
 185   Usage   : $seq = $db->get_Seq_by_acc('AAC73346');
 186   Function: Gets a Seq objects by accession number
 187   Returns : Bio::Seq object
 188   Args    : accession number to retrive by
 189
 190 =head1 Routines implemented by Bio::DB::NCBIHelper
 191
 192 =head2 get_request
 193
 194  Title   : get_request
 195  Usage   : my $url = $self->get_request
 196  Function: HTTP::Request
 197  Returns :
 198  Args    : %qualifiers = a hash of qualifiers (ids, format, etc)
 199
 200 =head2 get_Stream_by_id
 201
 202   Title   : get_Stream_by_id
 203   Usage   : $stream = $db->get_Stream_by_id( [$uid1, $uid2] );
 204   Function: Gets a series of Seq objects by unique identifiers
 205   Returns : a Bio::SeqIO stream object
 206   Args    : $ref : a reference to an array of unique identifiers for
 207                    the desired sequence entries
 208
 209 =head2 get_Stream_by_acc (2)
 210
 211   Title   : get_Stream_by_acc
 212   Usage   : $seq = $db->get_Stream_by_acc($acc);
 213   Function: Gets a series of Seq objects by accession numbers
 214   Returns : a Bio::SeqIO stream object
 215   Args    : $ref : a reference to an array of accession numbers for
 216                    the desired sequence entries
 217   Note    : For GenBank, this just calls the same code for get_Stream_by_id()
 218
 219 =head2 request_format
 220
 221  Title   : request_format
 222  Usage   : my $format = $self->request_format;
 223            $self->request_format($format);
 224  Function: Get/Set sequence format retrieval
 225  Returns : string representing format
 226  Args    : $format = sequence format
 227
 228 =cut
 229
 230 # override to force format to be GenPept regardless
 231 sub request_format {
 232     my ($self) = @_;
 233     return $self->SUPER::request_format($self->default_format());
 234 }
 235
 236 1;
 237 __END__
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253