| 1 | # | ||||||||||
| 2 | # BioPerl module for Bio::DB::GenBank | ||||||||||
| 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 | # Added LWP support - Jason Stajich 2000-11-6 | ||||||||||
| 15 | # completely reworked by Jason Stajich 2000-12-8 | ||||||||||
| 16 | # to use WebDBSeqI | ||||||||||
| 17 | |||||||||||
| 18 | # Added batch entrez back when determined that new entrez cgi will | ||||||||||
| 19 | # essentially work (there is a limit to the number of characters in a | ||||||||||
| 20 | # GET request so I am not sure how we can get around this). The NCBI | ||||||||||
| 21 | # Batch Entrez form has changed some and it does not support retrieval | ||||||||||
| 22 | # of text only data. Still should investigate POST-ing (tried and | ||||||||||
| 23 | # failed) a message to the entrez cgi to get around the GET | ||||||||||
| 24 | # limitations. | ||||||||||
| 25 | |||||||||||
| 26 | =head1 NAME | ||||||||||
| 27 | |||||||||||
| 28 | Bio::DB::GenBank - Database object interface to GenBank | ||||||||||
| 29 | |||||||||||
| 30 | =head1 SYNOPSIS | ||||||||||
| 31 | |||||||||||
| 32 | use Bio::DB::GenBank; | ||||||||||
| 33 | $gb = Bio::DB::GenBank->new(); | ||||||||||
| 34 | |||||||||||
| 35 | $seq = $gb->get_Seq_by_id('J00522'); # Unique ID, *not always the LOCUS ID* | ||||||||||
| 36 | |||||||||||
| 37 | # or ... | ||||||||||
| 38 | |||||||||||
| 39 | $seq = $gb->get_Seq_by_acc('J00522'); # Accession Number | ||||||||||
| 40 | $seq = $gb->get_Seq_by_version('J00522.1'); # Accession.version | ||||||||||
| 41 | $seq = $gb->get_Seq_by_gi('405830'); # GI Number | ||||||||||
| 42 | |||||||||||
| 43 | # get a stream via a query string | ||||||||||
| 44 | my $query = Bio::DB::Query::GenBank->new | ||||||||||
| 45 | (-query =>'Oryza sativa[Organism] AND EST', | ||||||||||
| 46 | -reldate => '30', | ||||||||||
| 47 | -db => 'nucleotide'); | ||||||||||
| 48 | my $seqio = $gb->get_Stream_by_query($query); | ||||||||||
| 49 | |||||||||||
| 50 | while( my $seq = $seqio->next_seq ) { | ||||||||||
| 51 | print "seq length is ", $seq->length,"\n"; | ||||||||||
| 52 | } | ||||||||||
| 53 | |||||||||||
| 54 | # or ... best when downloading very large files, prevents | ||||||||||
| 55 | # keeping all of the file in memory | ||||||||||
| 56 | |||||||||||
| 57 | # also don't want features, just sequence so let's save bandwidth | ||||||||||
| 58 | # and request Fasta sequence | ||||||||||
| 59 | $gb = Bio::DB::GenBank->new(-retrievaltype => 'tempfile' , | ||||||||||
| 60 | -format => 'Fasta'); | ||||||||||
| 61 | my $seqio = $gb->get_Stream_by_acc(['AC013798', 'AC021953'] ); | ||||||||||
| 62 | while( my $clone = $seqio->next_seq ) { | ||||||||||
| 63 | print "cloneid is ", $clone->display_id, " ", | ||||||||||
| 64 | $clone->accession_number, "\n"; | ||||||||||
| 65 | } | ||||||||||
| 66 | # note that get_Stream_by_version is not implemented | ||||||||||
| 67 | |||||||||||
| 68 | # don't want the entire sequence or more options | ||||||||||
| 69 | my $gb = Bio::DB::GenBank->new(-format => 'Fasta', | ||||||||||
| 70 | -seq_start => 100, | ||||||||||
| 71 | -seq_stop => 200, | ||||||||||
| 72 | -strand => 1, | ||||||||||
| 73 | -complexity => 4); | ||||||||||
| 74 | my $seqi = $gb->get_Stream_by_query($query); | ||||||||||
| 75 | |||||||||||
| 76 | |||||||||||
| 77 | =head1 DESCRIPTION | ||||||||||
| 78 | |||||||||||
| 79 | Allows the dynamic retrieval of L<Bio::Seq> sequence objects from the | ||||||||||
| 80 | GenBank database at NCBI, via an Entrez query. | ||||||||||
| 81 | |||||||||||
| 82 | WARNING: Please do B<NOT> spam the Entrez web server with multiple | ||||||||||
| 83 | requests. NCBI offers Batch Entrez for this purpose. | ||||||||||
| 84 | |||||||||||
| 85 | Note that when querying for GenBank accessions starting with 'NT_' you | ||||||||||
| 86 | will need to call $gb-E<gt>request_format('fasta') beforehand, because | ||||||||||
| 87 | in GenBank format (the default) the sequence part will be left out | ||||||||||
| 88 | (the reason is that NT contigs are rather annotation with references | ||||||||||
| 89 | to clones). | ||||||||||
| 90 | |||||||||||
| 91 | Some work has been done to automatically detect and retrieve whole NT_ | ||||||||||
| 92 | clones when the data is in that format (NCBI RefSeq clones). The | ||||||||||
| 93 | former behavior prior to bioperl 1.6 was to retrieve these from EBI, | ||||||||||
| 94 | but now these are retrieved directly from NCBI. The older behavior can | ||||||||||
| 95 | be regained by setting the 'redirect_refseq' flag to a value | ||||||||||
| 96 | evaluating to TRUE. | ||||||||||
| 97 | |||||||||||
| 98 | =head2 Running | ||||||||||
| 99 | |||||||||||
| 100 | Alternate methods are described at | ||||||||||
| 101 | L<https://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.EFetch> | ||||||||||
| 102 | |||||||||||
| 103 | NOTE: strand should be 1 for plus or 2 for minus. | ||||||||||
| 104 | |||||||||||
| 105 | Complexity: gi is often a part of a biological blob, containing other | ||||||||||
| 106 | gis | ||||||||||
| 107 | |||||||||||
| 108 | complexity regulates the display: | ||||||||||
| 109 | 0 - get the whole blob | ||||||||||
| 110 | 1 - get the bioseq for gi of interest (default in Entrez) | ||||||||||
| 111 | 2 - get the minimal bioseq-set containing the gi of interest | ||||||||||
| 112 | 3 - get the minimal nuc-prot containing the gi of interest | ||||||||||
| 113 | 4 - get the minimal pub-set containing the gi of interest | ||||||||||
| 114 | |||||||||||
| 115 | 'seq_start' and 'seq_stop' will not work when setting complexity to | ||||||||||
| 116 | any value other than 1. 'strand' works for any setting other than a | ||||||||||
| 117 | complexity of 0 (whole glob); when you try this with a GenBank return | ||||||||||
| 118 | format nothing happens, whereas using FASTA works but causes display | ||||||||||
| 119 | problems with the other sequences in the glob. As Tao Tao says from | ||||||||||
| 120 | NCBI, "Better left it out or set it to 1." | ||||||||||
| 121 | |||||||||||
| 122 | =head1 FEEDBACK | ||||||||||
| 123 | |||||||||||
| 124 | =head2 Mailing Lists | ||||||||||
| 125 | |||||||||||
| 126 | User feedback is an integral part of the evolution of this and other | ||||||||||
| 127 | Bioperl modules. Send your comments and suggestions preferably to one | ||||||||||
| 128 | of the Bioperl mailing lists. Your participation is much appreciated. | ||||||||||
| 129 | |||||||||||
| 130 | bioperl-l@bioperl.org - General discussion | ||||||||||
| 131 | http://bioperl.org/wiki/Mailing_lists - About the mailing lists | ||||||||||
| 132 | |||||||||||
| 133 | =head2 Support | ||||||||||
| 134 | |||||||||||
| 135 | Please direct usage questions or support issues to the mailing list: | ||||||||||
| 136 | |||||||||||
| 137 | I<bioperl-l@bioperl.org> | ||||||||||
| 138 | |||||||||||
| 139 | rather than to the module maintainer directly. Many experienced and | ||||||||||
| 140 | reponsive experts will be able look at the problem and quickly | ||||||||||
| 141 | address it. Please include a thorough description of the problem | ||||||||||
| 142 | with code and data examples if at all possible. | ||||||||||
| 143 | |||||||||||
| 144 | =head2 Reporting Bugs | ||||||||||
| 145 | |||||||||||
| 146 | Report bugs to the Bioperl bug tracking system to help us keep track | ||||||||||
| 147 | the bugs and their resolution. Bug reports can be submitted via the | ||||||||||
| 148 | web: | ||||||||||
| 149 | |||||||||||
| 150 | https://github.com/bioperl/bioperl-live/issues | ||||||||||
| 151 | |||||||||||
| 152 | =head1 AUTHOR - Aaron Mackey, Jason Stajich | ||||||||||
| 153 | |||||||||||
| 154 | Email amackey@virginia.edu | ||||||||||
| 155 | Email jason@bioperl.org | ||||||||||
| 156 | |||||||||||
| 157 | =head1 APPENDIX | ||||||||||
| 158 | |||||||||||
| 159 | The rest of the documentation details each of the | ||||||||||
| 160 | object methods. Internal methods are usually | ||||||||||
| 161 | preceded with a _ | ||||||||||
| 162 | |||||||||||
| 163 | =cut | ||||||||||
| 164 | |||||||||||
| 165 | # Let the code begin... | ||||||||||
| 166 | |||||||||||
| 167 | package Bio::DB::GenBank; | ||||||||||
| 168 | 4 | $Bio::DB::GenBank::VERSION = '1.7.8'; | |||||||||
| 169 | 4 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 170 | 4 | ▶ | use vars qw(%PARAMSTRING $DEFAULTFORMAT $DEFAULTMODE); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 171 | |||||||||||
| 172 | 4 | ▶ | use base qw(Bio::DB::NCBIHelper); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 173 | 4 | ▶ | BEGIN { | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 174 | 4 | $DEFAULTMODE = 'single'; | |||||||||
| 175 | 4 | $DEFAULTFORMAT = 'gbwithparts'; | |||||||||
| 176 | 4 | %PARAMSTRING = ( | |||||||||
| 177 | 'batch' => { 'db' => 'nucleotide', | ||||||||||
| 178 | 'usehistory' => 'n', | ||||||||||
| 179 | 'tool' => 'bioperl'}, | ||||||||||
| 180 | 'query' => { 'usehistory' => 'y', | ||||||||||
| 181 | 'tool' => 'bioperl', | ||||||||||
| 182 | 'retmode' => 'text'}, | ||||||||||
| 183 | 'gi' => { 'db' => 'nucleotide', | ||||||||||
| 184 | 'usehistory' => 'n', | ||||||||||
| 185 | 'tool' => 'bioperl', | ||||||||||
| 186 | 'retmode' => 'text'}, | ||||||||||
| 187 | 'version' => { 'db' => 'nucleotide', | ||||||||||
| 188 | 'usehistory' => 'n', | ||||||||||
| 189 | 'tool' => 'bioperl', | ||||||||||
| 190 | 'retmode' => 'text'}, | ||||||||||
| 191 | 'single' => { 'db' => 'nucleotide', | ||||||||||
| 192 | 'usehistory' => 'n', | ||||||||||
| 193 | 'tool' => 'bioperl', | ||||||||||
| 194 | 'retmode' => 'text'}, | ||||||||||
| 195 | 'webenv' => { | ||||||||||
| 196 | 'query_key' => 'querykey', | ||||||||||
| 197 | 'WebEnv' => 'cookie', | ||||||||||
| 198 | 'db' => 'nucleotide', | ||||||||||
| 199 | 'usehistory' => 'n', | ||||||||||
| 200 | 'tool' => 'bioperl', | ||||||||||
| 201 | 'retmode' => 'text'}, | ||||||||||
| 202 | ); | ||||||||||
| 203 | } | ||||||||||
| 204 | |||||||||||
| 205 | # new is in NCBIHelper | ||||||||||
| 206 | |||||||||||
| 207 | # helper method to get db specific options | ||||||||||
| 208 | |||||||||||
| 209 | =head2 new | ||||||||||
| 210 | |||||||||||
| 211 | Title : new | ||||||||||
| 212 | Usage : $gb = Bio::DB::GenBank->new(@options) | ||||||||||
| 213 | Function: Creates a new genbank handle | ||||||||||
| 214 | Returns : a new Bio::DB::Genbank object | ||||||||||
| 215 | Args : -delay number of seconds to delay between fetches (3s) | ||||||||||
| 216 | |||||||||||
| 217 | NOTE: There are other options that are used internally. By NCBI policy, this | ||||||||||
| 218 | module introduces a 3s delay between fetches. If you are fetching multiple genbank | ||||||||||
| 219 | ids, it is a good idea to use get | ||||||||||
| 220 | |||||||||||
| 221 | =cut | ||||||||||
| 222 | |||||||||||
| 223 | =head2 get_params | ||||||||||
| 224 | |||||||||||
| 225 | Title : get_params | ||||||||||
| 226 | Usage : my %params = $self->get_params($mode) | ||||||||||
| 227 | Function: Returns key,value pairs to be passed to NCBI database | ||||||||||
| 228 | for either 'batch' or 'single' sequence retrieval method | ||||||||||
| 229 | Returns : a key,value pair hash | ||||||||||
| 230 | Args : 'single' or 'batch' mode for retrieval | ||||||||||
| 231 | |||||||||||
| 232 | =cut | ||||||||||
| 233 | |||||||||||
| 234 | 20 | ▶ | sub get_params { | ||||||||
|
Subroutine
get_params: called CC=2 SCAR=7.6
Pod
documented
| |||||||||||
| 235 | 20 | my ($self, $mode) = @_; | |||||||||
| 236 | return defined $PARAMSTRING{$mode} ? | ||||||||||
| 237 | 0 | ▶ | %{$PARAMSTRING{$mode}} : %{$PARAMSTRING{$DEFAULTMODE}}; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 238 | } | ||||||||||
| 239 | |||||||||||
| 240 | # from Bio::DB::WebDBSeqI from Bio::DB::RandomAccessI | ||||||||||
| 241 | |||||||||||
| 242 | =head1 Routines Bio::DB::WebDBSeqI from Bio::DB::RandomAccessI | ||||||||||
| 243 | |||||||||||
| 244 | =head2 get_Seq_by_id | ||||||||||
| 245 | |||||||||||
| 246 | Title : get_Seq_by_id | ||||||||||
| 247 | Usage : $seq = $db->get_Seq_by_id('ROA1_HUMAN') | ||||||||||
| 248 | Function: Gets a Bio::Seq object by its name | ||||||||||
| 249 | Returns : a Bio::Seq object | ||||||||||
| 250 | Args : the id (as a string) of a sequence | ||||||||||
| 251 | Throws : "id does not exist" exception | ||||||||||
| 252 | |||||||||||
| 253 | =head2 get_Seq_by_acc | ||||||||||
| 254 | |||||||||||
| 255 | Title : get_Seq_by_acc | ||||||||||
| 256 | Usage : $seq = $db->get_Seq_by_acc($acc); | ||||||||||
| 257 | Function: Gets a Seq object by accession numbers | ||||||||||
| 258 | Returns : a Bio::Seq object | ||||||||||
| 259 | Args : the accession number as a string | ||||||||||
| 260 | Note : For GenBank, this just calls the same code for get_Seq_by_id(). | ||||||||||
| 261 | Caveat: this normally works, but in rare cases simply passing the | ||||||||||
| 262 | accession can lead to odd results, possibly due to unsynchronized | ||||||||||
| 263 | NCBI ID servers. Using get_Seq_by_version() is slightly better, but | ||||||||||
| 264 | using the unique identifier (GI) and get_Seq_by_id is the most | ||||||||||
| 265 | consistent | ||||||||||
| 266 | Throws : "id does not exist" exception | ||||||||||
| 267 | |||||||||||
| 268 | =head2 get_Seq_by_gi | ||||||||||
| 269 | |||||||||||
| 270 | Title : get_Seq_by_gi | ||||||||||
| 271 | Usage : $seq = $db->get_Seq_by_gi('405830'); | ||||||||||
| 272 | Function: Gets a Bio::Seq object by gi number | ||||||||||
| 273 | Returns : A Bio::Seq object | ||||||||||
| 274 | Args : gi number (as a string) | ||||||||||
| 275 | Throws : "gi does not exist" exception | ||||||||||
| 276 | |||||||||||
| 277 | =head2 get_Seq_by_version | ||||||||||
| 278 | |||||||||||
| 279 | Title : get_Seq_by_version | ||||||||||
| 280 | Usage : $seq = $db->get_Seq_by_version('X77802.1'); | ||||||||||
| 281 | Function: Gets a Bio::Seq object by sequence version | ||||||||||
| 282 | Returns : A Bio::Seq object | ||||||||||
| 283 | Args : accession.version (as a string) | ||||||||||
| 284 | Note : Caveat: this normally works, but using the unique identifier (GI) and | ||||||||||
| 285 | get_Seq_by_id is the most consistent | ||||||||||
| 286 | Throws : "acc.version does not exist" exception | ||||||||||
| 287 | |||||||||||
| 288 | =head1 Routines implemented by Bio::DB::NCBIHelper | ||||||||||
| 289 | |||||||||||
| 290 | =head2 get_Stream_by_query | ||||||||||
| 291 | |||||||||||
| 292 | Title : get_Stream_by_query | ||||||||||
| 293 | Usage : $seq = $db->get_Stream_by_query($query); | ||||||||||
| 294 | Function: Retrieves Seq objects from Entrez 'en masse', rather than one | ||||||||||
| 295 | at a time. For large numbers of sequences, this is far superior | ||||||||||
| 296 | than get_Stream_by_[id/acc](). | ||||||||||
| 297 | Example : | ||||||||||
| 298 | Returns : a Bio::SeqIO stream object | ||||||||||
| 299 | Args : $query : An Entrez query string or a | ||||||||||
| 300 | Bio::DB::Query::GenBank object. It is suggested that you | ||||||||||
| 301 | create a Bio::DB::Query::GenBank object and get the entry | ||||||||||
| 302 | count before you fetch a potentially large stream. | ||||||||||
| 303 | |||||||||||
| 304 | =cut | ||||||||||
| 305 | |||||||||||
| 306 | =head2 get_Stream_by_id | ||||||||||
| 307 | |||||||||||
| 308 | Title : get_Stream_by_id | ||||||||||
| 309 | Usage : $stream = $db->get_Stream_by_id( [$uid1, $uid2] ); | ||||||||||
| 310 | Function: Gets a series of Seq objects by unique identifiers | ||||||||||
| 311 | Returns : a Bio::SeqIO stream object | ||||||||||
| 312 | Args : $ref : a reference to an array of unique identifiers for | ||||||||||
| 313 | the desired sequence entries | ||||||||||
| 314 | |||||||||||
| 315 | =head2 get_Stream_by_acc | ||||||||||
| 316 | |||||||||||
| 317 | Title : get_Stream_by_acc | ||||||||||
| 318 | Usage : $seq = $db->get_Stream_by_acc([$acc1, $acc2]); | ||||||||||
| 319 | Function: Gets a series of Seq objects by accession numbers | ||||||||||
| 320 | Returns : a Bio::SeqIO stream object | ||||||||||
| 321 | Args : $ref : a reference to an array of accession numbers for | ||||||||||
| 322 | the desired sequence entries | ||||||||||
| 323 | Note : For GenBank, this just calls the same code for get_Stream_by_id() | ||||||||||
| 324 | |||||||||||
| 325 | =cut | ||||||||||
| 326 | |||||||||||
| 327 | =head2 get_Stream_by_gi | ||||||||||
| 328 | |||||||||||
| 329 | Title : get_Stream_by_gi | ||||||||||
| 330 | Usage : $seq = $db->get_Seq_by_gi([$gi1, $gi2]); | ||||||||||
| 331 | Function: Gets a series of Seq objects by gi numbers | ||||||||||
| 332 | Returns : a Bio::SeqIO stream object | ||||||||||
| 333 | Args : $ref : a reference to an array of gi numbers for | ||||||||||
| 334 | the desired sequence entries | ||||||||||
| 335 | Note : For GenBank, this just calls the same code for get_Stream_by_id() | ||||||||||
| 336 | |||||||||||
| 337 | =head2 get_Stream_by_batch | ||||||||||
| 338 | |||||||||||
| 339 | Title : get_Stream_by_batch | ||||||||||
| 340 | Usage : $seq = $db->get_Stream_by_batch($ref); | ||||||||||
| 341 | Function: Retrieves Seq objects from Entrez 'en masse', rather than one | ||||||||||
| 342 | at a time. | ||||||||||
| 343 | Example : | ||||||||||
| 344 | Returns : a Bio::SeqIO stream object | ||||||||||
| 345 | Args : $ref : either an array reference, a filename, or a filehandle | ||||||||||
| 346 | from which to get the list of unique ids/accession numbers. | ||||||||||
| 347 | |||||||||||
| 348 | NOTE: This method is redundant and deprecated. Use get_Stream_by_id() | ||||||||||
| 349 | instead. | ||||||||||
| 350 | |||||||||||
| 351 | =head2 get_request | ||||||||||
| 352 | |||||||||||
| 353 | Title : get_request | ||||||||||
| 354 | Usage : my $url = $self->get_request | ||||||||||
| 355 | Function: HTTP::Request | ||||||||||
| 356 | Returns : | ||||||||||
| 357 | Args : %qualifiers = a hash of qualifiers (ids, format, etc) | ||||||||||
| 358 | |||||||||||
| 359 | =cut | ||||||||||
| 360 | |||||||||||
| 361 | =head2 default_format | ||||||||||
| 362 | |||||||||||
| 363 | Title : default_format | ||||||||||
| 364 | Usage : my $format = $self->default_format | ||||||||||
| 365 | Function: Returns default sequence format for this module | ||||||||||
| 366 | Returns : string | ||||||||||
| 367 | Args : none | ||||||||||
| 368 | |||||||||||
| 369 | =cut | ||||||||||
| 370 | |||||||||||
| 371 | 6 | ▶ | sub default_format { | ||||||||
|
Subroutine
default_format: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||
| 372 | 6 | return $DEFAULTFORMAT; | |||||||||
| 373 | } | ||||||||||
| 374 | |||||||||||
| 375 | 4 | 1; | |||||||||
| 376 | __END__ | ||||||||||