Bio::Taxonomy - representing Taxonomy. use Bio::Taxonomy; # CREATION: You can either create an instance by assigning it, # or fetch it through factory. # Create the nodes first. See Bio::Taxonomy::Node for details. my $node_species_sapiens = Bio::Taxonomy::Node->new( -object_id => 9606, # or -ncbi_taxid. Requird tag -names => { 'scientific' => ['sapiens'], 'common_name' => ['human'] }, -rank => 'species' # Required tag ); my $node_genus_Homo = Bio::Taxonomy::Node->new( -object_id => 9605, -names => { 'scientific' => ['Homo'] }, -rank => 'genus' ); my $node_class_Mammalia = Bio::Taxonomy::Node->new( -object_id => 40674, -names => { 'scientific' => ['Mammalia'], 'common' => ['mammals'] }, -rank => 'class' ); my $taxonomy = Bio::Taxonomy->new; $taxonomy->add_node($node_class_Mammalia); $taxonomy->add_node($node_species_sapiens); $taxonomy->add_node($node_genus_Homo); # OR you can fetch it through a factory implementing # Bio::Taxonomy::FactoryI my $factory; my $taxonomy = $factory->fetch_by_ncbi_taxid(40674); # USAGE # In this case, binomial returns a defined value. my $binomial = $taxonomy->binomial; # 'common_names' refers to the lowest-rank node's common names, in # array. my @common_names = $taxonomy->common_names; # 'get_node', will return undef if the rank is no defined in # taxonomy object. It will throw error if the rank string is not # defined, say 'species lah'. my $node = $taxonomy->get_node('class'); my @nodes = $taxonomy->get_all_nodes; # Also, you can search for parent and children nodes, if taxonomy # comes with factory. my $parent_taxonomy = $taxonomy->get_parent Bio::Taxonomy object represents any rank-level in taxonomy system, rather than Bio::Species which is able to represent only species-level. There are two ways to create Taxonomy object, e.g. 1) instantiate an object and assign all nodes on your own code; and 2) fetch an object by factory.

Creation by instantiation
The abstraction of Taxonomy is actually a hash in data structure term. The keys of the hash are the rank names, such as 'genus' and 'species', and the values are the instances of Bio::Taxonomy::Node.

Creation by Factory fetching
NCBI Taxonomy system is well accepted as the standard. The Taxonomy Factories in bioperl access this system, through HTTP to NCBI Entrez, dump file, and advanced biosql database. Bio::Taxonomy::FactoryI defines all methods that all implementations must obey. $factory->fetch is a general method to fetch Taxonomy by either NCBI taxid or any types of names. $factory->fetch_parent($taxonomy), returns a Taxonomy that is one-step higher rank of the taxonomy specified as argument. $factory->fetch_children($taxonomy), reports an array of Taxonomy those are one-step lower rank of the taxonomy specified as the argument.

Usage of Taxonomy object
## Juguang Xiao, juguang@tll.org.sg The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _

new
Title : new Usage : my $obj = new Bio::Taxonomy(); Function: Builds a new Bio::Taxonomy object Returns : Bio::Taxonomy Args : -method -> method used to decide classification (none|trust|lookup) -ranks -> what ranks are there

method
Title : method Usage : $obj = taxonomy->method($method); Function: set or return the method used to decide classification Returns : $obj Args : $obj

classify
Title : classify Usage : @obj[][0-1] = taxonomy->classify($species); Function: return a ranked classification Returns : @obj of taxa and ranks as word pairs separated by "@" Args : Bio::Species object

level_of_rank
Title : level_of_rank Usage : $obj = taxonomy->level_of_rank($obj); Function: returns the level of a rank name Returns : $obj Args : $obj

rank_of_number
Title : rank_of_number Usage : $obj = taxonomy->rank_of_number($obj); Function: returns the rank name of a rank level Returns : $obj Args : $obj

ranks
Title : ranks Usage : @obj = taxonomy->ranks(@obj); Function: set or return all ranks Returns : @obj Args : @obj

add_node
Title: add_node Usage: $obj->add_node($node[, $node2, ...]); Function: add one or more Bio::Taxonomy::Node objects Returns: None Args: any number of Bio::Taxonomy::Node(s)

binomial
Title : binomial Usage : my $val = $obj->binomial; Function: returns the binomial name if this taxonomy reachs species level Returns : the binomial name OR undef if taxonmy does not reach species level Args : [No arguments]

get_node
Title : get_node Usage : $node = $taxonomy->get_node('species'); Function: get a Bio::Taxonomy::Node object according to rank name Returns : a Bio::Taxonomy::Node object or undef if null Args : a vaild rank name

classification
Title : classification Usage : @names = $taxonomy->classification; Function: get the classification names of one taxonomy Returns : array of names Args : [No arguments]