.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Taxon 3pm"
.TH Bio::Taxon 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Taxon \- A node in a represented taxonomy
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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   => \*(Aqflatfile\*(Aq,
\&                                   \-directory=> \*(Aq/tmp\*(Aq,
\&                                   \-nodesfile=> \*(Aq/path/to/nodes.dmp\*(Aq,
\&                                   \-namesfile=> \*(Aq/path/to/names.dmp\*(Aq);
\&  my $human = $dbh\->get_taxon(\-name => \*(AqHomo sapiens\*(Aq);
\&  $human = $dbh\->get_taxon(\-taxonid => \*(Aq9606\*(Aq);
\&
\&  print "id is ", $human\->id, "\en"; # 9606
\&  print "rank is ", $human\->rank, "\en"; # species
\&  print "scientific name is ", $human\->scientific_name, "\en"; # Homo sapiens
\&  print "division is ", $human\->division, "\en"; # Primates
\&
\&  my $mouse = $dbh\->get_taxon(\-name => \*(AqMus musculus\*(Aq);
\&
\&  # You can quickly make your own lineages with the list database
\&  my @ranks = qw(superkingdom class genus species);
\&  my @h_lineage = (\*(AqEukaryota\*(Aq, \*(AqMammalia\*(Aq, \*(AqHomo\*(Aq, \*(AqHomo sapiens\*(Aq);
\&  my $list_dbh = Bio::DB::Taxonomy\->new(\-source => \*(Aqlist\*(Aq, \-names => \e@h_lineage,
\&                                                           \-ranks => \e@ranks);
\&  $human = $list_dbh\->get_taxon(\-name => \*(AqHomo sapiens\*(Aq);
\&  my @names = $human\->common_names; # @names is empty
\&  $human\->common_names(\*(Aqwoman\*(Aq);
\&  @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 => \*(Aqentrez\*(Aq);
\&  $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\*(Aqt 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 => \*(Aqgenus\*(Aq);
\&
\&  # Normally you can\*(Aqt 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\*(Aqt be in the lineage of
\&  # your other Taxon:
\&  my $entrez_mouse = $entrez_dbh\->get_taxon(\-name => \*(AqMus musculus\*(Aq);
\&  my $list_human = $list_dbh\->get_taxon(\-name => \*(AqHomo sapiens\*(Aq);
\&  my $mouse_tree = Bio::Tree::Tree\->new(\-node => $entrez_mouse);
\&  $mouse_tree\->splice(\-keep_rank => \e@ranks);
\&  $lca = $mouse_tree\->get_lca($entrez_mouse, $list_human);
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR \- Sendu Bala"
.IX Header "AUTHOR - Sendu Bala"
Email bix@sendu.me.uk
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Jason Stajich,    jason-at-bioperl-dot-org (original Bio::Taxonomy::Node)
Juguang Xiao,     juguang@tll.org.sg
Gabriel Valiente, valiente@lsi.upc.edu
.SH "APPENDIX"
.IX Header "APPENDIX"
The rest of the documentation details each of the object methods.
Internal methods are usually preceded with a _
.SS "new"
.IX Subsection "new"
.Vb 10
\& 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 \*(Aqspecies\*(Aq, \*(Aqgenus\*(Aq, etc)
\&           \-common_names      => array ref of all common names
\&           \-division          => \*(AqPrimates\*(Aq, \*(AqRodents\*(Aq, 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
.Ve
.SH "Bio::IdentifiableI interface"
.IX Header "Bio::IdentifiableI interface"
Also see Bio::IdentifiableI
.SS "version"
.IX Subsection "version"
.Vb 4
\& Title   : version
\& Usage   : $taxon\->version($newval)
\& Returns : value of version (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "authority"
.IX Subsection "authority"
.Vb 4
\& Title   : authority
\& Usage   : $taxon\->authority($newval)
\& Returns : value of authority (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "namespace"
.IX Subsection "namespace"
.Vb 4
\& Title   : namespace
\& Usage   : $taxon\->namespace($newval)
\& Returns : value of namespace (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SH "Bio::Taxonomy::Node implementation"
.IX Header "Bio::Taxonomy::Node implementation"
.SS "db_handle"
.IX Subsection "db_handle"
.Vb 5
\& 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
.Ve
.PP
Also see Bio::DB::Taxonomy
.SS "rank"
.IX Subsection "rank"
.Vb 5
\& Title   : rank
\& Usage   : $taxon\->rank($newval)
\& Function: Get/set rank of this Taxon, \*(Aqspecies\*(Aq, \*(Aqgenus\*(Aq, \*(Aqorder\*(Aq, etc...
\& Returns : value of rank (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "id"
.IX Subsection "id"
.Vb 6
\& 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
.Ve
.SS "ncbi_taxid"
.IX Subsection "ncbi_taxid"
.Vb 7
\& 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
.Ve
.SS "parent_id"
.IX Subsection "parent_id"
.Vb 6
\& 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
.Ve
.SS "trusted_parent_id"
.IX Subsection "trusted_parent_id"
.Vb 12
\& 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\*(Aqs
\&           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.
.Ve
.SS "genetic_code"
.IX Subsection "genetic_code"
.Vb 5
\& 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)
.Ve
.SS "mitochondrial_genetic_code"
.IX Subsection "mitochondrial_genetic_code"
.Vb 5
\& 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)
.Ve
.SS "create_date"
.IX Subsection "create_date"
.Vb 5
\& 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)
.Ve
.SS "update_date"
.IX Subsection "update_date"
.Vb 5
\& 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)
.Ve
.SS "pub_date"
.IX Subsection "pub_date"
.Vb 5
\& 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)
.Ve
.SS "ancestor"
.IX Subsection "ancestor"
.Vb 4
\& 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
.Ve
.SS "get_Parent_Node"
.IX Subsection "get_Parent_Node"
.Vb 3
\& Title   : get_Parent_Node
\& Function: Synonym of ancestor()
\& Status  : deprecated
.Ve
.SS "each_Descendent"
.IX Subsection "each_Descendent"
.Vb 5
\& 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.
.Ve
.SS "get_Children_Nodes"
.IX Subsection "get_Children_Nodes"
.Vb 3
\& Title   : get_Children_Nodes
\& Function: Synonym of each_Descendent()
\& Status  : deprecated
.Ve
.SS "name"
.IX Subsection "name"
.Vb 10
\&  Title:    name
\&  Usage:    $taxon\->name(\*(Aqscientific\*(Aq, \*(AqHomo sapiens\*(Aq);
\&            $taxon\->name(\*(Aqcommon\*(Aq, \*(Aqhuman\*(Aq, \*(Aqman\*(Aq);
\&            my @names = @{$taxon\->name(\*(Aqcommon\*(Aq)};
\&  Function: Get/set the names. node_name(), scientific_name() and common_names()
\&            are shorthands to name(\*(Aqscientific\*(Aq), name(\*(Aqscientific\*(Aq) and
\&            name(\*(Aqcommon\*(Aq) respectively.
\&  Returns:  names (a array reference)
\&  Args:     Arg1 => the name_class. You can assign any text, but the words
\&                \*(Aqscientific\*(Aq and \*(Aqcommon\*(Aq have the special meaning, as
\&                scientific name and common name, respectively. \*(Aqscientific\*(Aq and
\&                \*(Aqdivision\*(Aq are treated specially, allowing only the first value
\&                in the Arg2 list to be set.
\&            Arg2 ... => list of names
.Ve
.SS "node_name"
.IX Subsection "node_name"
.Vb 7
\& 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. \*(AqPrimate\*(Aq or \*(AqHomo\*(Aq; 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)
.Ve
.SS "common_names"
.IX Subsection "common_names"
.Vb 7
\& 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. \*(AqHuman\*(Aq and \*(Aqman\*(Aq. 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)
.Ve
.SS "division"
.IX Subsection "division"
.Vb 6
\& Title   : division
\& Usage   : $taxon\->division($newval)
\& Function: Get/set the division this taxon belongs to, eg. \*(AqPrimates\*(Aq or
\&           \*(AqBacteria\*(Aq.
\& Returns : value of division (a scalar)
\& Args    : on set, new value (a scalar or undef, optional)
.Ve
.SS "remove_Descendent"
.IX Subsection "remove_Descendent"
.Vb 6
\& 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.
.Ve