Provided by: libbio-perl-perl_1.7.2-2_all 
NAME
Bio::Species - Generic species object.
SYNOPSIS
$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");
DESCRIPTION
NOTE: This class is planned for deprecation in favor of the simpler Bio::Taxon. Please
use that class instead.
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:
"phylum", "class", "order", "family"). There's plenty of scope for making the model more
sophisticated, if this is ever needed.
A methods are also provided for storing common names, and subspecies.
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
James Gilbert email jgrg@sanger.ac.uk
CONTRIBUTORS
Sendu Bala, bix@sendu.me.uk Chris Fields, cjfields at bioperl dot org
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::Species->new(-classification => \@class)
Function: Build a new Species object
Returns : Bio::Species object
Args : -ncbi_taxid => NCBI taxonomic ID (optional)
-classification => arrayref of classification
classification
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( 'Homo sapiens' 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.
ncbi_taxid
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)
common_name
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('human')
Returns : The common name in a string
Args : String, which is the common name (optional)
division
Title : division
Usage : $obj->division($newval)
Function: Genbank Division for a species
Returns : value of division (a scalar)
Args : value of division (a scalar)
species
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('sapiens');
Returns : species name as string (NOT genus and species)
Args : species name as string (NOT genus and species)
genus
Title : genus
Usage : $self->genus( $genus );
$genus = $self->genus();
Function: Get or set the scientific genus name.
Example : $self->genus('Homo');
Returns : Scientific genus name as string
Args : Scientific genus name as string
sub_species
Title : sub_species
Usage : $obj->sub_species($newval)
Function: Get or set the scientific subspecies name.
Returns : value of sub_species
Args : newvalue (optional)
variant
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)
binomial
Title : binomial
Usage : $binomial = $self->binomial();
$binomial = $self->binomial('FULL');
Function: Returns a string "Genus species", or "Genus species subspecies",
if the first argument is 'FULL' (and the species has a subspecies).
Args : Optionally the string 'FULL' to get the full name including
the subspecies.
Note : This is just munged from the taxon() name
validate_species_name
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's 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't actually used automatically by any Bio::Species method.
organelle
Title : organelle
Usage : $self->organelle( $organelle );
$organelle = $self->organelle();
Function: Get or set the organelle name
Example : $self->organelle('Chloroplast')
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't lost.
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.
taxon
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)
tree
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)