Query/GenBank.pm

filter: Statementstmt 96.7% 120 / 124 Branchbran 73.8% 31 / 42 Conditioncond 66.6% 4 / 6 MC/DCmcdc 33.3% 1 / 3 Subroutinesub 100% 24 / 24 Podpod 36.3% 4 / 11 totaltotal 87.6% 184 / 210 CC 26 SCAR 12.6
CC
26
Cov
90%
new
9.5
_parse_response
4.2
_request_parameters
4.1
CRAP 3.5
« NCBIHelper.pm ↑ Summary GenBank.pm »
1 #
2 # BioPerl module for Bio::DB::Query::GenBank.pm
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Lincoln Stein <lstein@cshl.org>
7 #
8 # Copyright Lincoln Stein
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  
15 =head1 NAME
16  
17 Bio::DB::Query::GenBank - Build a GenBank Entrez Query
18  
19 =head1 SYNOPSIS
20  
21 use Bio::DB::Query::GenBank;
22 use Bio::DB::GenBank;
23  
24 my $query_string = 'Oryza[Organism] AND EST[Keyword]';
25 my $query = Bio::DB::Query::GenBank->new(-db => 'nucleotide',
26 -query => $query_string,
27 -mindate => '2001',
28 -maxdate => '2002');
29  
30 print $query->count,"\n";
31  
32 # get a Genbank database handle
33 my $gb = Bio::DB::GenBank->new();
34 my $stream = $gb->get_Stream_by_query($query);
35 while (my $seq = $stream->next_seq) {
36 # do something with the sequence object
37 }
38  
39 # initialize the list yourself
40 my $query = Bio::DB::Query::GenBank->new(-ids=>[195052,2981014,11127914]);
41  
42  
43 =head1 DESCRIPTION
44  
45 This class encapsulates NCBI Entrez queries. It can be used to store
46 a list of GI numbers, to translate an Entrez query expression into a
47 list of GI numbers, or to count the number of terms that would be
48 returned by a query. Once created, the query object can be passed to
49 a Bio::DB::GenBank object in order to retrieve the entries
50 corresponding to the query.
51  
52 =head1 FEEDBACK
53  
54 =head2 Mailing Lists
55  
56 User feedback is an integral part of the
57 evolution of this and other Bioperl modules. Send
58 your comments and suggestions preferably to one
59 of the Bioperl mailing lists. Your participation
60 is much appreciated.
61  
62 bioperl-l@bioperl.org - General discussion
63 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
64  
65 =head2 Support
66  
67 Please direct usage questions or support issues to the mailing list:
68  
69 I<bioperl-l@bioperl.org>
70  
71 rather than to the module maintainer directly. Many experienced and
72 reponsive experts will be able look at the problem and quickly
73 address it. Please include a thorough description of the problem
74 with code and data examples if at all possible.
75  
76 =head2 Reporting Bugs
77  
78 Report bugs to the Bioperl bug tracking system to help us keep track
79 the bugs and their resolution. Bug reports can be submitted via the
80 web:
81  
82 https://github.com/bioperl/bioperl-live/issues
83  
84 =head1 AUTHOR - Lincoln Stein
85  
86 Email lstein@cshl.org
87  
88 =head1 APPENDIX
89  
90 The rest of the documentation details each of the
91 object methods. Internal methods are usually
92 preceded with a _
93  
94 =cut
95  
96 # Let the code begin...
97  
98 package Bio::DB::Query::GenBank;
99 12 $Bio::DB::Query::GenBank::VERSION = '1.7.8';
100 12 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
101 12 ▶use URI::Escape 'uri_unescape';
Subroutine BEGIN: called CC=1 SCAR=0.0
102 12 ▶use Bio::DB::NCBIHelper;
Subroutine BEGIN: called CC=1 SCAR=0.0
103  
104  
105 #use constant EPOST => $Bio::DB::NCBIHelper::HOSTBASE . '/entrez/eutils/epost.fcgi';
106 #use constant ESEARCH => $Bio::DB::NCBIHelper::HOSTBASE . '/entrez/eutils/esearch.fcgi';
107 # the reference to the our variable of the $Bio::DB::NCBIHelper::HOSTBASE doesn't seem to work in
108 # the constant definition in perl 5.10.1 or 5.16.3
109 12 ▶use constant EPOST => '/entrez/eutils/epost.fcgi';
Subroutine BEGIN: called CC=1 SCAR=0.0
110 12 ▶use constant ESEARCH => '/entrez/eutils/esearch.fcgi';
Subroutine BEGIN: called CC=1 SCAR=0.0
111 12 ▶use constant DEFAULT_DB => 'protein';
Subroutine BEGIN: called CC=1 SCAR=0.0
112 12 ▶use constant MAXENTRY => 100;
Subroutine BEGIN: called CC=1 SCAR=0.0
113  
114 12 ▶use vars qw(@ATTRIBUTES);
Subroutine BEGIN: called CC=1 SCAR=0.0
115 12 our $REQUEST_DELAY = 4;
116  
117 12 ▶use base qw(Bio::DB::Query::WebQuery);
Subroutine BEGIN: called CC=1 SCAR=0.0
118  
119 12 ▶BEGIN {
Subroutine BEGIN: called CC=2 SCAR=6.9
120 12 @ATTRIBUTES = qw(db reldate mindate maxdate datetype maxids email);
121 12 for my $method (@ATTRIBUTES) {
122 84 ▶ eval <<END;
Subroutine datetype: called CC=2 SCAR=6.9
Subroutine db: called CC=2 SCAR=6.9
Subroutine email: called CC=2 SCAR=6.9
Subroutine maxdate: called CC=2 SCAR=6.9
Subroutine maxids: called CC=2 SCAR=6.9
Subroutine mindate: called CC=2 SCAR=6.9
Subroutine reldate: called CC=2 SCAR=6.9
Pod undocumented
Pod undocumented
Pod undocumented
Pod undocumented
Pod undocumented
Pod undocumented
Pod undocumented
Branch: 7 branches
BranchTrueFalseTotal
if @_ 3 4 7
if @_ 3 6 9
if @_ 0 4 4
if @_ 1 3 4
if @_ 0 4 4
if @_ 1 3 4
if @_ 0 2 2
123 sub $method {
124 my \$self = shift;
125 my \$d = \$self->{'_$method'};
126 \$self->{'_$method'} = shift if \@_;
127 \$d;
128 }
129 END
130 }
131 }
132  
133 =head2 new
134  
135 Title : new
136 Usage : $db = Bio::DB::Query::GenBank->new(@args)
137 Function: create new query object
138 Returns : new query object
139 Args : -db database (see below for allowable values)
140 -query query string
141 -mindate minimum date to retrieve from (YYYY/MM/DD)
142 -maxdate maximum date to retrieve from (YYYY/MM/DD)
143 -reldate relative date to retrieve from (days)
144 -datetype date field to use ('edat' or 'mdat')
145 -ids array ref of gids (overrides query)
146 -maxids the maximum number of IDs you wish to collect
147 (defaults to 100)
148 -email Email address; required if you want to decrease
149 delay time between queries
150 -delay Delay time (in seconds). Note NCBI policy requires 4
151 seconds between requests unless an email is provided
152  
153 This method creates a new query object. Typically you will specify a
154 -db and a -query argument, possibly modified by -mindate, -maxdate, or
155 -reldate. -mindate and -maxdate specify minimum and maximum dates for
156 entries you are interested in retrieving, expressed in the form
157 YYYY/MM/DD. -reldate is used to fetch entries that are more recent
158 than the indicated number of days.
159  
160 If you provide an array reference of IDs in -ids, the query will be
161 ignored and the list of IDs will be used when the query is passed to a
162 Bio::DB::GenBank object's get_Stream_by_query() method. A variety of
163 IDs are automatically recognized, including GI numbers, Accession
164 numbers, Accession.version numbers and locus names.
165  
166 By default, the query will collect only the first 100 IDs and will
167 generate an exception if you call the ids() method and the query
168 returned more than that number. To increase this maximum, set -maxids
169 to a number larger than the number of IDs you expect to obtain. This
170 only affects the list of IDs you obtain when you call the ids()
171 method, and does not affect in any way the number of entries you
172 receive when you generate a SeqIO stream from the query.
173  
174 -db option values:
175  
176 The most commonly used databases are:
177  
178 protein
179 nucleotide
180 nuccore
181 nucgss
182 nucest
183 unigene
184  
185 An up to date list of database names supported by NCBI eUtils is
186 always available at:
187 https://eutils.ncbi.nlm.nih.gov/entrez/eutils/einfo.fcgi?
188  
189 However, note that not all of these databases return datatypes that
190 are parsable by Bio::DB::GenBank
191  
192 =cut
193  
194 3 ▶sub new {
Subroutine new: called CC=9 SCAR=22.5
Pod documented
195 3 my $class = shift;
196 3 my $self = $class->SUPER::new(@_);
197 3 my ($query,$db,$reldate,$mindate,$maxdate,$datetype,$ids,$maxids,$email,$delay)
198 = $self->_rearrange([qw(QUERY DB RELDATE MINDATE MAXDATE DATETYPE IDS
199 MAXIDS EMAIL DELAY)],@_);
200 3 ▶ $self->db($db || DEFAULT_DB);
Condition100%2/2
$db || 'protein'
l!l
21
MC/DC100%1/1
$db || 'protein'
$db
Truth table100%2/2
A
A= $db
Aresult
11
00
201 3 ▶ $reldate && $self->reldate($reldate);
Branch: 1 branch
BranchTrueFalseTotal
$reldate and $self->reldate($reldate) 0 3 3
202 3 ▶ $mindate && $self->mindate($mindate);
Branch: 1 branch
BranchTrueFalseTotal
$mindate and $self->mindate($mindate) 1 2 3
203 3 ▶ $maxdate && $self->maxdate($maxdate);
Branch: 1 branch
BranchTrueFalseTotal
$maxdate and $self->maxdate($maxdate) 1 2 3
204 3 ▶ $maxids && $self->maxids($maxids);
Branch: 1 branch
BranchTrueFalseTotal
$maxids and $self->maxids($maxids) 0 3 3
205 3 ▶ $email && $self->email($email);
Branch: 1 branch
BranchTrueFalseTotal
$email and $self->email($email) 0 3 3
206 3 ▶ $datetype ||= 'mdat';
Condition50%1/2
$datetype ||= "mdat"
l!l
03
MC/DC0%0/1
$datetype ||= "mdat"
$datetype
Truth table50%1/2
A
A= $datetype
Aresult
11
00
207 3 ▶ $datetype && $self->datetype($datetype);
Branch: 1 branch
BranchTrueFalseTotal
$datetype and $self->datetype($datetype) 3 0 3
208 3 $self;
209 }
210  
211 =head2 cookie
212  
213 Title : cookie
214 Usage : ($cookie,$querynum) = $db->cookie
215 Function: return the NCBI query cookie
216 Returns : list of (cookie,querynum)
217 Args : none
218  
219 NOTE: this information is used by Bio::DB::GenBank in
220 conjunction with efetch.
221  
222 =cut
223  
224 4 ▶sub cookie {
Subroutine cookie: called CC=2 SCAR=6.9
Pod documented
225 4 my $self = shift;
226 4 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 2 2 4
227 2 $self->{'_cookie'} = shift;
228 2 $self->{'_querynum'} = shift;
229 }
230  
231 else {
232 2 $self->_sleep();
233 2 $self->_run_query;
234 2 @{$self}{qw(_cookie _querynum)};
235 }
236 }
237  
238 =head2 _request_parameters
239  
240 Title : _request_parameters
241 Usage : ($method,$base,@params = $db->_request_parameters
242 Function: return information needed to construct the request
243 Returns : list of method, url base and key=>value pairs
244 Args : none
245  
246 =cut
247  
248 2 ▶sub _request_parameters {
Subroutine _request_parameters: called CC=4 SCAR=14.0
249 2 my $self = shift;
250 2 my ($method,$base);
251 2 ▶ my @params = map {eval("\$self->$_") ? ($_ => eval("\$self->$_")) : () } @ATTRIBUTES;
Branch: 1 branch
BranchTrueFalseTotal
eval "\$self->$_" ? : 6 8 14
252 2 push @params,('usehistory'=>'y','tool'=>'bioperl');
253 2 $method = 'get';
254  
255 2 $base = $Bio::DB::NCBIHelper::HOSTBASE.ESEARCH; # this seems to need to be dynamic
256 2 push @params,('term' => $self->query);
257 # Providing 'retmax' limits queries to 500 sequences ?? I don't think so LS
258 2 ▶ push @params,('retmax' => $self->maxids || MAXENTRY);
Condition50%1/2
$self->maxids || 100
l!l
02
MC/DC0%0/1
$self->maxids || 100
$self->maxids
Truth table50%1/2
A
A= $self->maxids
Aresult
11
00
259 2 ▶ if ($self->email) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->email) 0 2 2
260 0 push @params,('email' => $self->email);
261 }
262  
263 # And actually, it seems that we need 'retstart' equal to 0 ?? I don't think so LS
264 # push @params, ('retstart' => 0);
265  
266 2 ($method,$base,@params);
267 }
268  
269  
270 =head2 count
271  
272 Title : count
273 Usage : $count = $db->count;
274 Function: return count of number of entries retrieved by query
275 Returns : integer
276 Args : none
277  
278 Returns the number of entries that are matched by the query.
279  
280 =cut
281  
282 6 ▶sub count {
Subroutine count: called CC=2 SCAR=6.9
Pod documented
283 6 my $self = shift;
284 6 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 2 4 6
285 2 my $d = $self->{'_count'};
286 2 $self->{'_count'} = shift;
287 2 return $d;
288 }
289 else {
290 4 $self->_sleep();
291 4 $self->_run_query;
292 4 return $self->{'_count'};
293 }
294 }
295  
296 =head2 ids
297  
298 Title : ids
299 Usage : @ids = $db->ids([@ids])
300 Function: get/set matching ids
301 Returns : array of sequence ids
302 Args : (optional) array ref with new set of ids
303  
304 =cut
305  
306 =head2 query
307  
308 Title : query
309 Usage : $query = $db->query([$query])
310 Function: get/set query string
311 Returns : string
312 Args : (optional) new query string
313  
314 =cut
315  
316 =head2 _parse_response
317  
318 Title : _parse_response
319 Usage : $db->_parse_response($content)
320 Function: parse out response
321 Returns : empty
322 Args : none
323 Throws : 'unparseable output exception'
324  
325 =cut
326  
327 2 ▶sub _parse_response {
Subroutine _parse_response: called CC=4 SCAR=14.5
328 2 my $self = shift;
329 2 my $content = shift;
330 2 ▶ if (my ($warning) = $content =~ m!<ErrorList>(.+)</ErrorList>!s) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($warning) = $content =~ m[<ErrorList>(.+)</ErrorList>]s) 0 2 2
331 0 $self->warn("Warning(s) from GenBank: $warning\n");
332 }
333 2 ▶ if (my ($error) = $content =~ /<OutputMessage>([^<]+)/) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($error) = $content =~ /<OutputMessage>([^<]+)/) 0 2 2
334 0 $self->throw("Error from Genbank: $error");
335 }
336  
337 2 my ($count) = $content =~ /<Count>(\d+)/;
338 2 my ($max) = $content =~ /<RetMax>(\d+)/;
339 2 my $truncated = $count > $max;
340 2 $self->count($count);
341 2 ▶ if (!$truncated) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $truncated) { } 2 0 2
342 2 my @ids = $content =~ /<Id>(\d+)/g;
343 2 $self->ids(\@ids);
344 } else {
345 0 $self->debug("ids truncated at $max\n");
346 }
347 2 $self->_truncated($truncated);
348 2 my ($cookie) = $content =~ m!<WebEnv>(\S+)</WebEnv>!;
349 2 my ($querykey) = $content =~ m!<QueryKey>(\d+)!;
350 2 $self->cookie(uri_unescape($cookie),$querykey);
351 }
352  
353 =head2 _generate_id_string
354  
355 Title : _generate_id_string
356 Usage : $string = $db->_generate_id_string
357 Function: joins IDs together in string (possibly implementation-dependent)
358 Returns : string of concatenated IDs
359 Args : array ref of ids (normally passed into the constructor)
360  
361 =cut
362  
363 2 ▶sub _generate_id_string {
Subroutine _generate_id_string: called CC=2 SCAR=6.9
364 2 my ($self, $ids) = @_;
365 # this attempts to separate out accs (alphanumeric) from UIDs (numeric only)
366 # recent changes to esearch has wrought this upon us.. cjf 4/19/07
367 return sprintf('%s',join('|',map {
368 2 ▶ ($_ =~ m{^\d+$}) ? $_.'[UID]' : $_.'[PACC]'
Branch: 1 branch
BranchTrueFalseTotal
$_ =~ /^\d+$/ ? : 2 4 6
369 } @$ids));
370 }
371  
372 =head2 delay_policy
373  
374 Title : delay_policy
375 Usage : $secs = $self->delay_policy
376 Function: NCBI requests a delay of 4 seconds between requests unless email is
377 provided. This method implements a 4 second delay; use 'delay()' to
378 override, though understand if no email is provided we are not
379 responsible for users being IP-blocked by NCBI
380 Returns : number of seconds to delay
381 Args : none
382  
383 =cut
384  
385 3 ▶sub delay_policy {
Subroutine delay_policy: called CC=1 SCAR=0.0
Pod documented
386 3 my $self = shift;
387 3 return $REQUEST_DELAY;
388 }
389  
390 12 1;
« NCBIHelper.pm ↑ Summary GenBank.pm »