Bio/DB/Taxonomy.pm

filter: Statementstmt 74.7% 68 / 91 Branchbran 67.8% 19 / 28 Conditioncond 66.6% 16 / 24 MC/DCmcdc 38.4% 5 / 13 Subroutinesub 60.0% 9 / 15 Podpod 100% 8 / 8 totaltotal 69.8% 125 / 179 CC 28 SCAR 27.2
CC
28
Cov
72%
get_tree
42.0
_handle_internal_id
19.2
new
4.1
CRAP 15.2
« Bio/AlignIO/xmfa.pm ↑ Summary Bio/SeqIO.pm »
1 #
2 # BioPerl module for Bio::DB::Taxonomy
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Jason Stajich <jason-at-bioperl.org>
7 #
8 # Copyright Jason Stajich
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 =head1 NAME
15  
16 Bio::DB::Taxonomy - Access to a taxonomy database
17  
18 =head1 SYNOPSIS
19  
20 use Bio::DB::Taxonomy;
21 my $db = Bio::DB::Taxonomy->new(-source => 'entrez');
22 # use NCBI Entrez over HTTP
23 my $taxonid = $db->get_taxonid('Homo sapiens');
24  
25 # get a taxon
26 my $taxon = $db->get_taxon(-taxonid => $taxonid);
27  
28 =head1 DESCRIPTION
29  
30 This is a front end module for access to a taxonomy database.
31  
32 =head1 FEEDBACK
33  
34 =head2 Mailing Lists
35  
36 User feedback is an integral part of the evolution of this and other
37 Bioperl modules. Send your comments and suggestions preferably to
38 the Bioperl mailing list. Your participation is much appreciated.
39  
40 bioperl-l@bioperl.org - General discussion
41 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
42  
43 =head2 Support
44  
45 Please direct usage questions or support issues to the mailing list:
46  
47 I<bioperl-l@bioperl.org>
48  
49 rather than to the module maintainer directly. Many experienced and
50 reponsive experts will be able look at the problem and quickly
51 address it. Please include a thorough description of the problem
52 with code and data examples if at all possible.
53  
54 =head2 Reporting Bugs
55  
56 Report bugs to the Bioperl bug tracking system to help us keep track
57 of the bugs and their resolution. Bug reports can be submitted via
58 the web:
59  
60 https://github.com/bioperl/bioperl-live/issues
61  
62 =head1 AUTHOR - Jason Stajich
63  
64 Email jason-at-bioperl.org
65  
66 =head1 CONTRIBUTORS
67  
68 Sendu Bala: bix@sendu.me.uk
69  
70 =head1 APPENDIX
71  
72 The rest of the documentation details each of the object methods.
73 Internal methods are usually preceded with a _
74  
75 =cut
76  
77 # Let the code begin...
78  
79 package Bio::DB::Taxonomy;
80 48 $Bio::DB::Taxonomy::VERSION = '1.7.8';
81 48 ▶use vars qw($DefaultSource $TAXON_IIDS);
Subroutine BEGIN: called CC=1 SCAR=0.0
82 48 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
83 48 ▶use Bio::Tree::Tree;
Subroutine BEGIN: called CC=1 SCAR=0.0
84  
85 48 ▶use base qw(Bio::Root::Root);
Subroutine BEGIN: called CC=1 SCAR=0.0
86  
87 48 $DefaultSource = 'entrez';
88 48 $TAXON_IIDS = {};
89  
90  
91 =head2 new
92  
93 Title : new
94 Usage : my $obj = Bio::DB::Taxonomy->new(-source => 'entrez');
95 Function: Builds a new Bio::DB::Taxonomy object.
96 Returns : an instance of Bio::DB::Taxonomy
97 Args : -source => which database source 'entrez' (NCBI taxonomy online),
98 'flatfile' (local NCBI taxonomy), 'greengenes' (local
99 GreenGenes taxonomy), 'silva' (local Silva taxonomy), or
100 'list' (Do-It-Yourself taxonomy)
101  
102 =cut
103  
104 428 ▶sub new {
Subroutine new: called CC=4 SCAR=14.0
Pod documented
105 428 my($class,@args) = @_;
106  
107 428 ▶ if( $class =~ /Bio::DB::Taxonomy::(\S+)/ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($class =~ /Bio::DB::Taxonomy::(\S+)/) { } 215 213 428
108 215 my ($self) = $class->SUPER::new(@args);
109 215 $self->_initialize(@args);
110 215 return $self;
111 } else {
112 213 my %param = @args;
113 213 @param{ map { lc $_ } keys %param } = values %param; # lowercase keys
114 213 ▶ my $source = $param{'-source'} || $DefaultSource;
Condition33%1/3
$param{'-source'} || $Bio::DB::Taxonomy::DefaultSource
l!l&&r!l&&!r
21300
MC/DC0%0/2
$param{'-source'} || $Bio::DB::Taxonomy::DefaultSource
$param{'-source'} $Bio::DB::Taxonomy::DefaultSource
Truth table33%1/3
A || B
A= $param{'-source'}B= $Bio::DB::Taxonomy::DefaultSource
ABresult
1X1
011
000
115  
116 213 $source = "\L$source"; # normalize capitalization to lower case
117  
118 # normalize capitalization
119 213 ▶ return unless( $class->_load_tax_module($source) );
Branch: 1 branch
BranchTrueFalseTotal
unless $class->_load_tax_module($source) 0 213 213
120 213 return "Bio::DB::Taxonomy::$source"->new(@args);
121 }
122 }
123  
124  
125 # empty for now
126 215 ▶sub _initialize { }
Subroutine _initialize: called CC=1 SCAR=0.0
127  
128  
129 =head2 get_num_taxa
130  
131 Title : get_num_taxa
132 Usage : my $num = $db->get_num_taxa();
133 Function: Get the number of taxa stored in the database.
134 Returns : A number
135 Args : None
136  
137 =cut
138  
139 0 ▶sub get_num_taxa {
Subroutine get_num_taxa: not called CC=1 SCAR=6.9
Pod documented
140 0 shift->throw_not_implemented();
141 }
142  
143  
144 =head2 get_taxon
145  
146 Title : get_taxon
147 Usage : my $taxon = $db->get_taxon(-taxonid => $taxonid);
148 Function: Get a Bio::Taxon object from the database.
149 Returns : Bio::Taxon object
150 Args : just a single value which is the database id, OR named args:
151 -taxonid => taxonomy id (to query by taxonid)
152 OR
153 -name => string (to query by a taxonomy name: common name,
154 scientific name, etc)
155  
156 =cut
157  
158 0 ▶sub get_taxon {
Subroutine get_taxon: not called CC=1 SCAR=6.9
Pod documented
159 0 shift->throw_not_implemented();
160 }
161  
162 48 *get_Taxonomy_Node = \&get_taxon;
163  
164  
165 =head2 get_taxonids
166  
167 Title : get_taxonids
168 Usage : my @taxonids = $db->get_taxonids('Homo sapiens');
169 Function: Searches for a taxonid (typically ncbi_taxon_id) based on a query
170 string. Note that multiple taxonids can match to the same supplied
171 name.
172 Returns : array of integer ids in list context, one of these in scalar context
173 Args : string representing the taxon's name
174  
175 =cut
176  
177 0 ▶sub get_taxonids {
Subroutine get_taxonids: not called CC=1 SCAR=6.9
Pod documented
178 0 shift->throw_not_implemented();
179 }
180  
181 48 *get_taxonid = \&get_taxonids;
182 48 *get_taxaid = \&get_taxonids;
183  
184  
185 =head2 get_tree
186  
187 Title : get_tree
188 Usage : my $tree = $db->get_tree(@species_names);
189 Function: Generate a tree comprised of the full lineages of all the supplied
190 species names. The nodes for the requested species are given
191 name('supplied') values corresponding to the supplied name, such that
192 they can be identified if the real species name in the database
193 (stored under node_name()) is different. The nodes are also given an
194 arbitrary branch length of 1.
195 Returns : Bio::Tree::Tree
196 Args : A list of species names (strings) to include in the tree.
197  
198 =cut
199  
200 0 ▶sub get_tree {
Subroutine get_tree: not called CC=6 SCAR=37.4
Pod documented
201 0 my ($self, @species_names) = @_;
202
203 # the full lineages of the species are merged into a single tree
204 0 my $tree;
205 0 for my $name (@species_names) {
206 0 my @ids = $self->get_taxonids($name);
207 0 ▶ if (not scalar @ids) {
Branch: 1 branch
BranchTrueFalseTotal
unless (scalar @ids) 0 0 0
208 0 $self->throw("Could not find species $name in the taxonomy");
209 }
210 0 for my $id (@ids) {
211 0 my $node = $self->get_taxon(-taxonid => $id);
212 0 $node->name('supplied', $name);
213 0 ▶ if ($tree) {
Branch: 1 branch
BranchTrueFalseTotal
if ($tree) { } 0 0 0
214 0 $tree->merge_lineage($node);
215 } else {
216 0 $tree = Bio::Tree::Tree->new(-verbose => $self->verbose, -node => $node);
217 }
218 }
219 }
220  
221 # add arbitrary branch length
222 0 for my $node ($tree->get_nodes) {
223 0 $node->branch_length(1);
224 }
225
226 0 return $tree;
227 }
228  
229  
230 =head2 ancestor
231  
232 Title : ancestor
233 Usage : my $ancestor_taxon = $db->ancestor($taxon);
234 Function: Retrieve the full ancestor taxon of a supplied Taxon from the
235 database.
236 Returns : Bio::Taxon
237 Args : Bio::Taxon (that was retrieved from this database)
238  
239 =cut
240  
241 0 ▶sub ancestor {
Subroutine ancestor: not called CC=1 SCAR=6.9
Pod documented
242 0 shift->throw_not_implemented();
243 }
244  
245  
246 =head2 each_Descendent
247  
248 Title : each_Descendent
249 Usage : my @taxa = $db->each_Descendent($taxon);
250 Function: Get all the descendents of the supplied Taxon (but not their
251 descendents, ie. not a recursive fetchall).
252 Returns : Array of Bio::Taxon objects
253 Args : Bio::Taxon (that was retrieved from this database)
254  
255 =cut
256  
257 0 ▶sub each_Descendent {
Subroutine each_Descendent: not called CC=1 SCAR=6.9
Pod documented
258 0 shift->throw_not_implemented();
259 }
260  
261  
262 =head2 get_all_Descendents
263  
264 Title : get_all_Descendents
265 Usage : my @taxa = $db->get_all_Descendents($taxon);
266 Function: Like each_Descendent(), but do a recursive fetchall
267 Returns : Array of Bio::Taxon objects
268 Args : Bio::Taxon (that was retrieved from this database)
269  
270 =cut
271  
272 14 ▶sub get_all_Descendents {
Subroutine get_all_Descendents: called CC=2 SCAR=6.9
Pod documented
273 14 my ($self, $taxon) = @_;
274 14 my @taxa;
275 14 foreach my $desc_taxon ($self->each_Descendent($taxon)) {
276 12 push @taxa, ($desc_taxon, $self->get_all_Descendents($desc_taxon));
277 }
278 14 return @taxa;
279 }
280  
281  
282 =head2 _load_tax_module
283  
284 Title : _load_tax_module
285 Usage : *INTERNAL Bio::DB::Taxonomy stuff*
286 Function: Loads up (like use) a module at run time on demand
287  
288 =cut
289  
290 213 ▶sub _load_tax_module {
Subroutine _load_tax_module: called CC=2 SCAR=7.3
291 213 my ($self, $source) = @_;
292 213 my $module = "Bio::DB::Taxonomy::" . $source;
293 213 my $ok;
294  
295 213 eval { $ok = $self->_load_module($module) };
296 213 ▶ if ( $@ ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 213 213
297 0 print STDERR $@;
298 0 print STDERR <<END;
299 $self: $source cannot be found
300 Exception $@
301 For more information about the Bio::DB::Taxonomy system please see
302 the Bio::DB::Taxonomy docs. This includes ways of checking for
303 formats at compile time, not run time.
304 END
305 ;
306 }
307 213 return $ok;
308 }
309  
310  
311 =head2 _handle_internal_id
312  
313 Title : _handle_internal_id
314 Usage : *INTERNAL Bio::DB::Taxonomy stuff*
315 Function: Add an internal ID to a taxon object, ensuring that the taxon gets
316 the same internal ID, regardless of which database it is retrieved
317 from.
318 Returns : The assigned internal ID
319 Args : * A Bio::Taxon
320 * An optional boolean to decide whether or not to try and do the job
321 using scientific name & rank in addition to taxon ID. This is
322 useful if your IDs are not comparable to that of other databases,
323 e.g. if they are arbitrary, as in the case of Bio::DB::Taxonomy::list.
324 CAVEAT: will handle ambiguous names within a database fine, but not
325 across multiple databases.
326  
327 =cut
328  
329 6233 ▶sub _handle_internal_id {
Subroutine _handle_internal_id: called CC=18 SCAR=29.5
330 6233 my ($self, $taxon, $try_name) = @_;
331 6233 ▶ $self->throw("Must supply a Bio::Taxon") unless ref($taxon) && $taxon->isa('Bio::Taxon');
Branch: 1 branch
BranchTrueFalseTotal
unless ref $taxon and $taxon->isa("Bio::Taxon") 0 6233 6233
Condition33%1/3
ref $taxon and $taxon->isa("Bio::Taxon")
!ll&&!rl&&r
006233
MC/DC0%0/2
ref $taxon and $taxon->isa("Bio::Taxon")
ref $taxon $taxon->isa("Bio::Taxon")
Truth table33%1/3
A and B
A= ref $taxonB= $taxon->isa("Bio::Taxon")
ABresult
0X0
100
111
332  
333 6233 ▶ my $taxid = $taxon->id || return;
Condition50%1/2
$taxon->id || (return)
l!l
62330
MC/DC0%0/1
$taxon->id || (return)
$taxon->id
Truth table50%1/2
A
A= $taxon->id
Aresult
11
00
334 6233 ▶ my $name = $taxon->scientific_name || '';
Condition100%2/2
$taxon->scientific_name || ''
l!l
622310
MC/DC100%1/1
$taxon->scientific_name || ''
$taxon->scientific_name
Truth table100%2/2
A
A= $taxon->scientific_name
Aresult
11
00
335 6233 ▶ my $rank = $taxon->rank || 'no rank';
Condition100%2/2
$taxon->rank || 'no rank'
l!l
536180
MC/DC100%1/1
$taxon->rank || 'no rank'
$taxon->rank
Truth table100%2/2
A
A= $taxon->rank
Aresult
11
00
336 6233 ▶ my $dbh = $try_name ? $taxon->db_handle : 'any';
Branch: 1 branch
BranchTrueFalseTotal
$try_name ? : 6233 0 6233
337  
338 6233 my $iid = $TAXON_IIDS->{taxids}->{$dbh}->{$taxid};
339 6233 ▶ if ( (not defined $iid) && $try_name && $name && exists $TAXON_IIDS->{names}->{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $iid and $try_name and $name and exists $Bio::DB::Taxonomy::TAXON_IIDS->{"names"}{$name}) 1468 4765 6233
Condition88%8/9
not defined $iid and $try_name and $name and exists $Bio::DB::Taxonomy::TAXON_IIDS->{"names"}{$name}
!ll&&!rl&&r
40986671468
not defined $iid and $try_name and $name
!ll&&!rl&&r
409442135
not defined $iid and $try_name
!ll&&!rl&&r
409402139
MC/DC75%3/4
not defined $iid and $try_name and $name and exists $Bio::DB::Taxonomy::TAXON_IIDS->{"names"}{$name}
not defined $iid $try_name $name exists $Bio::DB::Taxonomy::TAXON_IIDS->{"names"}{$name}
Truth table80%4/5
not(A) and B and C and D
A= not defined $iidB= $try_nameC= $nameD= exists $Bio::DB::Taxonomy::TAXON_IIDS->{"names"}{$name}
ABCDresult
0XXX0
10XX0
110X0
11100
11111
340 # Search for a suitable IID based on species name and ranks
341 1468 my %test_ranks = map {$_ => undef} ($rank, 'no rank');
342 1468 ▶ SEARCH: while (my ($test_rank, undef) = each %test_ranks) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($test_rank, undef) = each %test_ranks) 1468 495 1963
343 # Search at the specified rank first, then with 'no rank'
344 1468 ▶ while ( my ($test_iid, $test_info) = each %{$TAXON_IIDS->{names}->{$name}->{$rank}} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$$Bio::DB::Taxonomy::TAXON_IIDS{"names"}{$name}{$rank};}) 1476 495 1971
345 1476 ▶ while (my ($test_db, $test_taxid) = each %$test_info) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %$test_info) 973 503 1476
346 973 ▶ if ( ($test_db eq $dbh) && not($test_taxid eq $taxid) ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($test_db eq $dbh and not $test_taxid eq $taxid) 0 973 973
Condition33%1/3
$test_db eq $dbh and not $test_taxid eq $taxid
!ll&&!rl&&r
97300
MC/DC0%0/2
$test_db eq $dbh and not $test_taxid eq $taxid
$test_db eq $dbh not $test_taxid eq $taxid
Truth table33%1/3
A and not(B)
A= $test_db eq $dbhB= not $test_taxid eq $taxid
ABresult
0X0
100
111
347 # Taxa are different (same database, different taxid)
348 0 next;
349 }
350 # IID is acceptable since taxa are from different databases,
351 # or from the same database but have the same taxid
352 973 $iid = $test_iid;
353 973 $TAXON_IIDS->{taxids}->{$dbh}->{$taxid} = $iid;
354 973 last SEARCH;
355 }
356 }
357 }
358 }
359  
360 6233 ▶ if (defined $iid) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $iid) { } 5067 1166 6233
361 # Assign Bio::DB::Taxonomy IID with risky Bio::Tree::Node internal method
362 5067 $taxon->_creation_id($iid);
363 } else {
364 # Register new IID in Bio::DB::Taxonomy
365 1166 $iid = $taxon->internal_id;
366 1166 $TAXON_IIDS->{taxids}->{$dbh}->{$taxid} = $iid;
367 1166 ▶ if ($name) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name) 1162 4 1166
368 1162 $TAXON_IIDS->{names}->{$name}->{$rank}->{$iid}->{$taxon->db_handle} = $taxid
369 }
370 }
371  
372 6233 return $iid;
373  
374 }
375  
376  
377 48 1;
« Bio/AlignIO/xmfa.pm ↑ Summary Bio/SeqIO.pm »