Provided by: libbio-perl-perl_1.7.8-1_all bug

NAME

       Bio::Taxon - A node in a represented taxonomy

SYNOPSIS

         use Bio::Taxon;

         # Typically you will get a Taxon from a Bio::DB::Taxonomy object
         # but here is how you initialize one
         my $taxon = Bio::Taxon->new(-name      => $name,
                                     -id        => $id,
                                     -rank      => $rank,
                                     -division  => $div);

         # Get one from a database
         my $dbh = Bio::DB::Taxonomy->new(-source   => 'flatfile',
                                          -directory=> '/tmp',
                                          -nodesfile=> '/path/to/nodes.dmp',
                                          -namesfile=> '/path/to/names.dmp');
         my $human = $dbh->get_taxon(-name => 'Homo sapiens');
         $human = $dbh->get_taxon(-taxonid => '9606');

         print "id is ", $human->id, "\n"; # 9606
         print "rank is ", $human->rank, "\n"; # species
         print "scientific name is ", $human->scientific_name, "\n"; # Homo sapiens
         print "division is ", $human->division, "\n"; # Primates

         my $mouse = $dbh->get_taxon(-name => 'Mus musculus');

         # You can quickly make your own lineages with the list database
         my @ranks = qw(superkingdom class genus species);
         my @h_lineage = ('Eukaryota', 'Mammalia', 'Homo', 'Homo sapiens');
         my $list_dbh = Bio::DB::Taxonomy->new(-source => 'list', -names => \@h_lineage,
                                                                  -ranks => \@ranks);
         $human = $list_dbh->get_taxon(-name => 'Homo sapiens');
         my @names = $human->common_names; # @names is empty
         $human->common_names('woman');
         @names = $human->common_names; # @names contains woman

         # You can switch to another database when you need more information
         my $entrez_dbh = Bio::DB::Taxonomy->new(-source => 'entrez');
         $human->db_handle($entrez_dbh);
         @names = $human->common_names; # @names contains woman, human, man

         # Since Bio::Taxon implements Bio::Tree::NodeI, we have access to those
         # methods (and can manually create our own taxa and taxonomy without the use
         # of any database)
         my $homo = $human->ancestor;

         # Though be careful with each_Descendent - unless you add_Descendent()
         # yourself, you won't get an answer because unlike for ancestor(), Bio::Taxon
         # does not ask the database for the answer. You can ask the database yourself
         # using the same method:
         ($human) = $homo->db_handle->each_Descendent($homo);

         # We can also take advantage of Bio::Tree::Tree* methods:
         # a) some methods are available with just an empty tree object
         use Bio::Tree::Tree;
         my $tree_functions = Bio::Tree::Tree->new();
         my @lineage = $tree_functions->get_lineage_nodes($human);
         my $lineage = $tree_functions->get_lineage_string($human);
         my $lca = $tree_functions->get_lca($human, $mouse);

         # b) for other methods, create a tree using your Taxon object
         my $tree = Bio::Tree::Tree->new(-node => $human);
         my @taxa = $tree->get_nodes;
         $homo = $tree->find_node(-rank => 'genus');

         # Normally you can't get the lca of a list-database derived Taxon and an
         # entrez or flatfile-derived one because the two different databases might
         # have different roots and different numbers of ranks between the root and the
         # taxa of interest. To solve this, make a tree of the Taxon with the more
         # detailed lineage and splice out all the taxa that won't be in the lineage of
         # your other Taxon:
         my $entrez_mouse = $entrez_dbh->get_taxon(-name => 'Mus musculus');
         my $list_human = $list_dbh->get_taxon(-name => 'Homo sapiens');
         my $mouse_tree = Bio::Tree::Tree->new(-node => $entrez_mouse);
         $mouse_tree->splice(-keep_rank => \@ranks);
         $lca = $mouse_tree->get_lca($entrez_mouse, $list_human);

DESCRIPTION

       This is the next generation (for Bioperl) of representing Taxonomy information. Previously
       all information was managed by a single object called Bio::Species. This new
       implementation allows representation of the intermediate nodes not just the species nodes
       and can relate their connections.

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

AUTHOR - Sendu Bala

       Email bix@sendu.me.uk

CONTRIBUTORS

       Jason Stajich,    jason-at-bioperl-dot-org (original Bio::Taxonomy::Node) Juguang Xiao,
       juguang@tll.org.sg Gabriel Valiente, valiente@lsi.upc.edu

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::Node->new();
        Function: Builds a new Bio::Taxonomy::Node object
        Returns : an instance of Bio::Taxonomy::Node
        Args    : -dbh               => a reference to a Bio::DB::Taxonomy object
                                        [no default]
                  -name              => a string representing the taxon name
                                        (scientific name)
                  -id                => human readable id - typically NCBI taxid
                  -ncbi_taxid        => same as -id, but explicitly say that it is an
                                        NCBI taxid
                  -rank              => node rank (one of 'species', 'genus', etc)
                  -common_names      => array ref of all common names
                  -division          => 'Primates', 'Rodents', etc
                  -genetic_code      => genetic code table number
                  -mito_genetic_code => mitochondrial genetic code table number
                  -create_date       => date created in database
                  -update_date       => date last updated in database
                  -pub_date          => date published in database

Bio::IdentifiableI interface

       Also see Bio::IdentifiableI

   version
        Title   : version
        Usage   : $taxon->version($newval)
        Returns : value of version (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   authority
        Title   : authority
        Usage   : $taxon->authority($newval)
        Returns : value of authority (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   namespace
        Title   : namespace
        Usage   : $taxon->namespace($newval)
        Returns : value of namespace (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

Bio::Taxonomy::Node implementation

   db_handle
        Title   : db_handle
        Usage   : $taxon->db_handle($newval)
        Function: Get/Set Bio::DB::Taxonomy Handle
        Returns : value of db_handle (a scalar) (Bio::DB::Taxonomy object)
        Args    : on set, new value (a scalar, optional) Bio::DB::Taxonomy object

       Also see Bio::DB::Taxonomy

   rank
        Title   : rank
        Usage   : $taxon->rank($newval)
        Function: Get/set rank of this Taxon, 'species', 'genus', 'order', etc...
        Returns : value of rank (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   id
        Title   : id
        Usage   : $taxon->id($newval)
        Function: Get/Set id (NCBI Taxonomy ID in most cases); object_id() and
                  ncbi_taxid() are synonyms of this method.
        Returns : id (a scalar)
        Args    : none to get, OR scalar to set

   ncbi_taxid
        Title   : ncbi_taxid
        Usage   : $taxon->ncbi_taxid($newval)
        Function: Get/Set the NCBI Taxonomy ID; This actually sets the id() but only
                  returns an id when ncbi_taxid has been explictely set with this
                  method.
        Returns : id (a scalar)
        Args    : none to get, OR scalar to set

   parent_id
        Title   : parent_id
        Usage   : $taxon->parent_id()
        Function: Get parent ID, (NCBI Taxonomy ID in most cases);
                  parent_taxon_id() is a synonym of this method.
        Returns : value of parent_id (a scalar)
        Args    : none

   trusted_parent_id
        Title   : trusted_parent_id
        Usage   : $taxon->trusted_parent_id()
        Function: If the parent_id is explicitly set, trust it
        Returns : simple boolean value (whether or not it has been set)
        Args    : none
        Notes   : Previously, the parent_id method was to be deprecated in favor of
                  using ancestor(). However this removes one key optimization point,
                  namely when an implementation has direct access to the taxon's
                  parent ID when retrieving the information for the taxon ID.  This
                  method is in place so implementations can choose to (1) check whether
                  the parent_id is set and (2) trust that the implementation (whether
                  it is self or another implementation) set the parent_id correctly.

   genetic_code
        Title   : genetic_code
        Usage   : $taxon->genetic_code($newval)
        Function: Get/set genetic code table
        Returns : value of genetic_code (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   mitochondrial_genetic_code
        Title   : mitochondrial_genetic_code
        Usage   : $taxon->mitochondrial_genetic_code($newval)
        Function: Get/set mitochondrial genetic code table
        Returns : value of mitochondrial_genetic_code (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   create_date
        Title   : create_date
        Usage   : $taxon->create_date($newval)
        Function: Get/Set Date this node was created (in the database)
        Returns : value of create_date (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   update_date
        Title   : update_date
        Usage   : $taxon->update_date($newval)
        Function: Get/Set Date this node was updated (in the database)
        Returns : value of update_date (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   pub_date
        Title   : pub_date
        Usage   : $taxon->pub_date($newval)
        Function: Get/Set Date this node was published (in the database)
        Returns : value of pub_date (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   ancestor
        Title   : ancestor
        Usage   : my $ancestor_taxon = $taxon->ancestor()
        Function: Retrieve the ancestor taxon. Normally the database is asked what the
                  ancestor is.

                  If you manually set the ancestor (or you make a Bio::Tree::Tree with
                  this object as an argument to new()), the database (if any) will not
                  be used for the purposes of this method.

                  To restore normal database behaviour, call ancestor(undef) (which
                  would remove this object from the tree), or request this taxon again
                  as a new Taxon object from the database.

        Returns : Bio::Taxon
        Args    : none

   get_Parent_Node
        Title   : get_Parent_Node
        Function: Synonym of ancestor()
        Status  : deprecated

   each_Descendent
        Title   : each_Descendent
        Usage   : my @taxa = $taxon->each_Descendent();
        Function: Get all the descendents for this Taxon (but not their descendents,
                  ie. not a recursive fetchall). get_Children_Nodes() is a synonym of
                  this method.

                  Note that this method never asks the database for the descendents;
                  it will only return objects you have manually set with
                  add_Descendent(), or where this was done for you by making a
                  Bio::Tree::Tree with this object as an argument to new().

                  To get the database descendents use
                  $taxon->db_handle->each_Descendent($taxon).

        Returns : Array of Bio::Taxon objects
        Args    : optionally, when you have set your own descendents, the string
                  "height", "creation", "alpha", "revalpha", or coderef to be used to
                  sort the order of children nodes.

   get_Children_Nodes
        Title   : get_Children_Nodes
        Function: Synonym of each_Descendent()
        Status  : deprecated

   name
         Title:    name
         Usage:    $taxon->name('scientific', 'Homo sapiens');
                   $taxon->name('common', 'human', 'man');
                   my @names = @{$taxon->name('common')};
         Function: Get/set the names. node_name(), scientific_name() and common_names()
                   are shorthands to name('scientific'), name('scientific') and
                   name('common') respectively.
         Returns:  names (a array reference)
         Args:     Arg1 => the name_class. You can assign any text, but the words
                       'scientific' and 'common' have the special meaning, as
                       scientific name and common name, respectively. 'scientific' and
                       'division' are treated specially, allowing only the first value
                       in the Arg2 list to be set.
                   Arg2 ... => list of names

   node_name
        Title   : node_name
        Usage   : $taxon->node_name($newval)
        Function: Get/set the name of this taxon (node), typically the scientific name
                  of the taxon, eg. 'Primate' or 'Homo'; scientific_name() is a synonym
                  of this method.
        Returns : value of node_name (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   common_names
        Title   : common_names
        Usage   : $taxon->common_names($newval)
        Function: Get/add the other names of this taxon, typically the genbank common
                  name and others, eg. 'Human' and 'man'. common_name() is a synonym
                  of this method.
        Returns : array of names in list context, one of those names in scalar context
        Args    : on add, new list of names (scalars, optional)

   division
        Title   : division
        Usage   : $taxon->division($newval)
        Function: Get/set the division this taxon belongs to, eg. 'Primates' or
                  'Bacteria'.
        Returns : value of division (a scalar)
        Args    : on set, new value (a scalar or undef, optional)

   remove_Descendent
        Title   : remove_Descendent
        Usage   : $node->remove_Descedent($node_foo);
        Function: Removes a specific node from being a Descendent of this node
        Returns : nothing
        Args    : An array of Bio::Node::NodeI objects which have been previously
                  passed to the add_Descendent call of this object.