NAME

       Bio::Taxonomy - representing Taxonomy.

SYNOPSIS

         # NB: This module is deprecated. Use Bio::Taxon in combination with
         # Bio::Tree::Tree methods instead.

         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

DESCRIPTION

       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
       ##

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules. Send
       your comments and suggestions preferably to the Bioperl mailing list.  Your participation
       is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track of the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

CONTACT

       Juguang Xiao, juguang@tll.org.sg

APPENDIX

       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

   new
        Title   : new
        Usage   : my $obj = Bio::Taxonomy->new();
        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]