Bio/DB/GenPept.pm

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