GenBank.pm

filter: Statementstmt 94.7% 18 / 19 Branchbran 50.0% 1 / 2 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 6 / 6 Podpod 100% 2 / 2 totaltotal 93.1% 27 / 29 CC 2 SCAR 2.8
CC
2
Cov
90%
get_params
2.1
BEGIN
1.0
BEGIN
1.0
CRAP 1.3
« Query/GenBank.pm ↑ Summary GenPept.pm »
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
BranchTrueFalseTotal
defined $Bio::DB::GenBank::PARAMSTRING{$mode} ? : 20 0 20
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__
« Query/GenBank.pm ↑ Summary GenPept.pm »