.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Bio::Taxonomy 3pm"
.TH Bio::Taxonomy 3pm "2018-10-27" "perl v5.26.2" "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::Taxonomy \- representing Taxonomy.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  # 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 => {
\&          \*(Aqscientific\*(Aq => [\*(Aqsapiens\*(Aq],
\&          \*(Aqcommon_name\*(Aq => [\*(Aqhuman\*(Aq]
\&      },
\&      \-rank => \*(Aqspecies\*(Aq  # Required tag
\&  );
\&  my $node_genus_Homo = Bio::Taxonomy::Node\->new(
\&      \-object_id => 9605,
\&      \-names => { \*(Aqscientific\*(Aq => [\*(AqHomo\*(Aq] },
\&      \-rank => \*(Aqgenus\*(Aq
\&  );
\&  my $node_class_Mammalia = Bio::Taxonomy::Node\->new(
\&      \-object_id => 40674,
\&      \-names => {
\&          \*(Aqscientific\*(Aq => [\*(AqMammalia\*(Aq],
\&          \*(Aqcommon\*(Aq => [\*(Aqmammals\*(Aq]
\&      },
\&      \-rank => \*(Aqclass\*(Aq
\&  );
\&  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;
\&
\&  # \*(Aqcommon_names\*(Aq refers to the lowest\-rank node\*(Aqs common names, in
\&  # array.
\&  my @common_names = $taxonomy\->common_names;
\&
\&  # \*(Aqget_node\*(Aq, will return undef if the rank is no defined in
\&  # taxonomy object.  It will throw error if the rank string is not
\&  # defined, say \*(Aqspecies lah\*(Aq.
\&  my $node = $taxonomy\->get_node(\*(Aqclass\*(Aq);
\&  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
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Bio::Taxonomy object represents any rank-level in taxonomy system,
rather than Bio::Species which is able to represent only
species-level.
.PP
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.
.SS "Creation by instantiation"
.IX Subsection "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.
.SS "Creation by Factory fetching"
.IX Subsection "Creation by Factory fetching"
\&\s-1NCBI\s0 Taxonomy system is well accepted as the standard. The Taxonomy
Factories in bioperl access this system, through \s-1HTTP\s0 to \s-1NCBI\s0 Entrez,
dump file, and advanced biosql database.
.PP
Bio::Taxonomy::FactoryI defines all methods that all implementations
must obey.
.PP
\&\f(CW$factory\fR\->fetch is a general method to fetch Taxonomy by either
\&\s-1NCBI\s0 taxid or any types of names.
.PP
\&\f(CW$factory\fR\->fetch_parent($taxonomy), returns a Taxonomy that is
one-step higher rank of the taxonomy specified as argument.
.PP
\&\f(CW$factory\fR\->fetch_children($taxonomy), reports an array of Taxonomy
those are one-step lower rank of the taxonomy specified as the
argument.
.SS "Usage of Taxonomy object"
.IX Subsection "Usage of Taxonomy object"
##
.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 "CONTACT"
.IX Header "CONTACT"
Juguang Xiao, juguang@tll.org.sg
.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 7
\& 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
.Ve
.SS "method"
.IX Subsection "method"
.Vb 5
\& Title   : method
\& Usage   : $obj = taxonomy\->method($method);
\& Function: set or return the method used to decide classification
\& Returns : $obj
\& Args    : $obj
.Ve
.SS "classify"
.IX Subsection "classify"
.Vb 5
\& 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
.Ve
.SS "level_of_rank"
.IX Subsection "level_of_rank"
.Vb 5
\& Title   : level_of_rank
\& Usage   : $obj = taxonomy\->level_of_rank($obj);
\& Function: returns the level of a rank name
\& Returns : $obj
\& Args    : $obj
.Ve
.SS "rank_of_number"
.IX Subsection "rank_of_number"
.Vb 5
\& Title   : rank_of_number
\& Usage   : $obj = taxonomy\->rank_of_number($obj);
\& Function: returns the rank name of a rank level
\& Returns : $obj
\& Args    : $obj
.Ve
.SS "ranks"
.IX Subsection "ranks"
.Vb 5
\& Title   : ranks
\& Usage   : @obj = taxonomy\->ranks(@obj);
\& Function: set or return all ranks
\& Returns : @obj
\& Args    : @obj
.Ve
.SS "add_node"
.IX Subsection "add_node"
.Vb 5
\&  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)
.Ve
.SS "binomial"
.IX Subsection "binomial"
.Vb 6
\&  Title   : binomial
\&  Usage   : my $val = $obj\->binomial;
\&  Function: returns the binomial name if this taxonomy reaches species level
\&  Returns : the binomial name
\&            OR undef if taxonmy does not reach species level
\&  Args    : [No arguments]
.Ve
.SS "get_node"
.IX Subsection "get_node"
.Vb 5
\&  Title   : get_node
\&  Usage   : $node = $taxonomy\->get_node(\*(Aqspecies\*(Aq);
\&  Function: get a Bio::Taxonomy::Node object according to rank name
\&  Returns : a Bio::Taxonomy::Node object or undef if null
\&  Args    : a valid rank name
.Ve
.SS "classification"
.IX Subsection "classification"
.Vb 5
\&  Title   : classification
\&  Usage   : @names = $taxonomy\->classification;
\&  Function: get the classification names of one taxonomy
\&  Returns : array of names
\&  Args    : [No arguments]
.Ve