.\" Automatically generated by Pod::Man 4.11 (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
..
.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::Species 3pm"
.TH Bio::Species 3pm "2020-10-28" "perl v5.30.3" "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::Species \- Generic species object.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    $species = Bio::Species\->new(\-classification => [@classification]);
\&                                    # Can also pass classification
\&                                    # array to new as below
\&
\&    $species\->classification(qw( sapiens Homo Hominidae
\&                                 Catarrhini Primates Eutheria
\&                                 Mammalia Vertebrata Chordata
\&                                 Metazoa Eukaryota ));
\&
\&    $genus = $species\->genus();
\&
\&    $bi = $species\->binomial();     # $bi is now "Homo sapiens"
\&
\&    # For storing common name
\&    $species\->common_name("human");
\&
\&    # For storing subspecies
\&    $species\->sub_species("accountant");
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1NOTE:\s0 This class is planned for deprecation in favor of the simpler Bio::Taxon.
Please use that class instead.\fR
.PP
Provides a very simple object for storing phylogenetic information. The
classification is stored in an array, which is a list of nodes in a phylogenetic
tree. Access to getting and setting species and genus is provided, but not to
any of the other node types (eg: \*(L"phylum\*(R", \*(L"class\*(R", \*(L"order\*(R", \*(L"family\*(R"). There's
plenty of scope for making the model more sophisticated, if this is ever needed.
.PP
A methods are also provided for storing common names, and subspecies.
.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"
.IX Header "AUTHOR"
James Gilbert email \fBjgrg@sanger.ac.uk\fR
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Sendu Bala, bix@sendu.me.uk
Chris Fields, cjfields at bioperl dot org
.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 6
\& Title   : new
\& Usage   : my $obj = Bio::Species\->new(\-classification => \e@class)
\& Function: Build a new Species object
\& Returns : Bio::Species object
\& Args    : \-ncbi_taxid     => NCBI taxonomic ID (optional)
\&           \-classification => arrayref of classification
.Ve
.SS "classification"
.IX Subsection "classification"
.Vb 10
\& Title   : classification
\& Usage   : $self\->classification(@class_array);
\&           @classification = $self\->classification();
\& Function: Get/set the lineage of this species. The array provided must be in
\&           the order ... \-\-\-> SPECIES, GENUS \-\-\-> KINGDOM \-\-\-> etc.
\& Example : $obj\->classification(qw( \*(AqHomo sapiens\*(Aq Homo Hominidae
\&           Catarrhini Primates Eutheria Mammalia Vertebrata
\&           Chordata Metazoa Eukaryota));
\& Returns : Classification array
\& Args    : Classification array 
\&                 OR
\&           A reference to the classification array. In the latter case
\&           if there is a second argument and it evaluates to true,
\&           names will not be validated. NB: in any case, names are never
\&           validated anyway.
.Ve
.SS "ncbi_taxid"
.IX Subsection "ncbi_taxid"
.Vb 5
\& Title   : ncbi_taxid
\& Usage   : $obj\->ncbi_taxid($newval)
\& Function: Get/set the NCBI Taxon ID
\& Returns : the NCBI Taxon ID as a string
\& Args    : newvalue to set or undef to unset (optional)
.Ve
.SS "common_name"
.IX Subsection "common_name"
.Vb 7
\& Title   : common_name
\& Usage   : $self\->common_name( $common_name );
\&           $common_name = $self\->common_name();
\& Function: Get or set the common name of the species
\& Example : $self\->common_name(\*(Aqhuman\*(Aq)
\& Returns : The common name in a string
\& Args    : String, which is the common name (optional)
.Ve
.SS "division"
.IX Subsection "division"
.Vb 5
\& Title   : division
\& Usage   : $obj\->division($newval)
\& Function: Genbank Division for a species
\& Returns : value of division (a scalar)
\& Args    : value of division (a scalar)
.Ve
.SS "species"
.IX Subsection "species"
.Vb 9
\& Title   : species
\& Usage   : $self\->species( $species );
\&           $species = $self\->species();
\& Function: Get or set the species name.
\&           Note that this is  NOT genus and species
\&           \-\- use $self\->binomial() for that.
\& Example : $self\->species(\*(Aqsapiens\*(Aq);
\& Returns : species name as string (NOT genus and species)
\& Args    : species name as string (NOT genus and species)
.Ve
.SS "genus"
.IX Subsection "genus"
.Vb 7
\& Title   : genus
\& Usage   : $self\->genus( $genus );
\&           $genus = $self\->genus();
\& Function: Get or set the scientific genus name.
\& Example : $self\->genus(\*(AqHomo\*(Aq);
\& Returns : Scientific genus name as string
\& Args    : Scientific genus name as string
.Ve
.SS "sub_species"
.IX Subsection "sub_species"
.Vb 5
\& Title   : sub_species
\& Usage   : $obj\->sub_species($newval)
\& Function: Get or set the scientific subspecies name.
\& Returns : value of sub_species
\& Args    : newvalue (optional)
.Ve
.SS "variant"
.IX Subsection "variant"
.Vb 7
\& Title   : variant
\& Usage   : $obj\->variant($newval)
\& Function: Get/set variant information for this species object (strain,
\&           isolate, etc).
\& Example : 
\& Returns : value of variant (a scalar)
\& Args    : new value (a scalar or undef, optional)
.Ve
.SS "binomial"
.IX Subsection "binomial"
.Vb 8
\& Title   : binomial
\& Usage   : $binomial = $self\->binomial();
\&           $binomial = $self\->binomial(\*(AqFULL\*(Aq);
\& Function: Returns a string "Genus species", or "Genus species subspecies",
\&           if the first argument is \*(AqFULL\*(Aq (and the species has a subspecies).
\& Args    : Optionally the string \*(AqFULL\*(Aq to get the full name including
\&           the subspecies.
\& Note    : This is just munged from the taxon() name
.Ve
.SS "validate_species_name"
.IX Subsection "validate_species_name"
.Vb 10
\& Title   : validate_species_name
\& Usage   : $result = $self\->validate_species_name($string);
\& Function: Validate the species portion of the binomial
\& Args    : string
\& Notes   : The string following the "genus name" in the NCBI binomial is so
\&           variable that it\*(Aqs not clear that this is a useful function. Consider
\&           the binomials "Simian 11 rotavirus (serotype 3 / strain
\&           SA11\-Patton)", or "St. Thomas 3 rotavirus", straight from GenBank.
\&           This is particularly problematic in microbes and viruses. As such,
\&           this isn\*(Aqt actually used automatically by any Bio::Species method.
.Ve
.SS "organelle"
.IX Subsection "organelle"
.Vb 10
\& Title   : organelle
\& Usage   : $self\->organelle( $organelle );
\&           $organelle = $self\->organelle();
\& Function: Get or set the organelle name
\& Example : $self\->organelle(\*(AqChloroplast\*(Aq)
\& Returns : The organelle name in a string
\& Args    : String, which is the organelle name
\& Note    : TODO: We currently do not know where the organelle definition will
\&           eventually go.  This is stored in the source seqfeature, though,
\&           so the information isn\*(Aqt lost.
.Ve
.SS "Delegation"
.IX Subsection "Delegation"
The following methods delegate to the internal Bio::Taxon instance. This is
mainly to allow code continue using older methods, with the mind to migrate to
using Bio::Taxon and related methods when this class is deprecated.
.SS "taxon"
.IX Subsection "taxon"
.Vb 6
\& Title    : taxon
\& Usage    : $obj\->taxon
\& Function : retrieve the internal Bio::Taxon instance
\& Returns  : A Bio::Taxon. If one is not previously set,
\&            an instance is created lazily
\& Args     : Bio::Taxon (optional)
.Ve
.SS "tree"
.IX Subsection "tree"
.Vb 6
\& Title    : tree
\& Usage    : $obj\->tree
\& Function : Returns a Bio::Tree::Tree object
\& Returns  : A Bio::Tree::Tree. If one is not previously set,
\&            an instance is created lazily
\& Args     : Bio::Tree::Tree (optional)
.Ve