Bio Species
SummaryIncluded librariesPackage variablesSynopsisDescriptionGeneral documentationMethods
Toolbar
WebCvs
Summary
Bio::Species - Generic species object.
Package variables
No package variables defined.
Included modules
Bio::DB::Taxonomy
Bio::Taxon
Bio::Tree::Tree
Inherit
Bio::Root::Root Bio::Tree::NodeI
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.
Methods
newDescriptionCode
classificationDescriptionCode
speciesDescriptionCode
genusDescriptionCode
sub_speciesDescriptionCode
variantDescriptionCode
binomialDescriptionCode
validate_species_nameDescriptionCode
validate_name
No description
Code
organelleDescriptionCode
node_name
No description
Code
scientific_name
No description
Code
id
No description
Code
object_id
No description
Code
ncbi_taxidDescriptionCode
rank
No description
Code
divisionDescriptionCode
common_names
No description
Code
common_nameDescriptionCode
genetic_code
No description
Code
mitochondrial_genetic_code
No description
Code
create_date
No description
Code
pub_date
No description
Code
update_date
No description
Code
db_handle
No description
Code
parent_id
No description
Code
parent_taxon_id
No description
Code
version
No description
Code
authority
No description
Code
namespace
No description
Code
ancestor
No description
Code
get_Parent_Node
No description
Code
each_Descendent
No description
Code
get_Children_Nodes
No description
Code
remove_Descendant
No description
Code
name
No description
Code
taxonDescriptionCode
treeDescriptionCode
DESTROY
No description
Code
Methods description
newcode    nextTop
 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
classificationcodeprevnextTop
 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.
speciescodeprevnextTop
 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)
genuscodeprevnextTop
 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_speciescodeprevnextTop
 Title   : sub_species
Usage : $obj->sub_species($newval)
Function: Get or set the scientific subspecies name.
Returns : value of sub_species
Args : newvalue (optional)
variantcodeprevnextTop
 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)
binomialcodeprevnextTop
 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_namecodeprevnextTop
 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.
organellecodeprevnextTop
 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.
ncbi_taxidcodeprevnextTop
 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)
divisioncodeprevnextTop
 Title   : division
Usage : $obj->division($newval)
Function: Genbank Division for a species
Returns : value of division (a scalar)
Args : value of division (a scalar)
common_namecodeprevnextTop
 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)
taxoncodeprevnextTop
 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)
treecodeprevnextTop
 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)
Methods code
newdescriptionprevnextTop
sub new {
    my($class, @args) = @_;
    
    my $self = $class->SUPER::new(@args);
    
    # Bio::Species is now just a proxy object that just observes the NodeI
# interface methods but delegates them to the proper classes (Bio::Taxon and
# Bio::Tree::Tree). This will be surplanted by the much simpler
# Bio::Taxon/Bio::DB::Taxonomy modules in the future.
# Using a proxy allows proper GC w/o using weaken(). This just wraps the
# older instances, which have no reciprocal refs (thus no circular refs).
# This can then run proper cleanup
$self->taxon(Bio::Taxon->new(@args)); my ($org, $sp, $var, $classification) = $self->_rearrange([qw(ORGANELLE SUB_SPECIES VARIANT CLASSIFICATION)], @args); if (defined $classification && ref($classification) eq "ARRAY" && @{$classification}) { $self->classification(@$classification); } else { $self->tree(Bio::Tree::Tree->new()); } defined $org && $self->organelle($org); defined $sp && $self->sub_species($sp); defined $var && $self->variant($var); return $self;
}
classificationdescriptionprevnextTop
sub classification {
    my ($self, @vals) = @_;

    my $taxon = $self->taxon;

    if (@vals) {
        if (ref($vals[0]) eq 'ARRAY') {
            @vals = @{$vals[0]};
        }
        
        $vals[1] ||= '';
        # make sure the lineage contains us as first or second element
# (lineage may have subspecies, species, genus ...)
my $name = $taxon->node_name; my ($genus, $species) = (quotemeta($vals[1]), quotemeta($vals[0])); if ($name && ($name !~ m{$species}i && $name !~ m{$genus}i) && $name !~ m{$vals[1] $vals[0]}i) { if ($name =~ /^$vals[1] $vals[0]\s*(.+)/) { # just assume the problem is someone tried to make a Bio::Species starting at subspecies
#*** no idea if this is appropriate! just a possible fix related to bug 2092
$self->sub_species($1); $name = $taxon->node_name("$vals[1] $vals[0]"); } else { $self->warn("The supplied lineage does not start near '$name' (I was supplied '".join(" | ", @vals)."')"); } } # create a lineage for ourselves
my $db = Bio::DB::Taxonomy->new(-source => 'list', -names => [reverse @vals]); unless ($taxon->scientific_name) { # assume we're supposed to be the leaf of the supplied lineage
$self->taxon->scientific_name($vals[0]); } unless ($taxon->rank) { # and that we are rank species
$taxon->rank('species'); } $taxon->db_handle($db); $self->tree(Bio::Tree::Tree->new(-node => $taxon)); } @vals = (); foreach my $node ($self->tree->get_lineage_nodes($taxon), $taxon) { unshift(@vals, $node->scientific_name || next); } return @vals;
}
speciesdescriptionprevnextTop
sub species {
    my ($self, $species) = @_;
    
	if ($species) {
		$self->{_species} = $species;
	}

	unless (defined $self->{_species}) {
		# work it out from our nodes
my $species_taxon = $self->tree->find_node(-rank => 'species'); unless ($species_taxon) { # just assume we are rank species
$species_taxon = $self->taxon; } $species = $species_taxon->scientific_name; #
# munge it like the Bio::SeqIO modules used to do
# (more or less copy/pasted from old Bio::SeqIO::genbank, hence comments
# referring to 'ORGANISM' etc.)
#
my $root = $self->tree->get_root_node; unless ($root) { $self->tree(Bio::Tree::Tree->new(-node => $species_taxon)); $root = $self->tree->get_root_node; } my @spflds = split(' ', $species); if (@spflds > 1 && $root->node_name ne 'Viruses') { $species = undef; # does the next term start with uppercase?
# yes: valid genus; no then unconventional
# e.g. leaf litter basidiomycete sp. Collb2-39
my $genus; if ($spflds[0] =~ m/^[A-Z]/) {
$genus = shift(@spflds);
} else { undef $genus; } my $sub_species; if (@spflds) { while (my $fld = shift @spflds) { $species .= "$fld "; # does it have subspecies or varieties?
last if ($fld =~ m/(sp\.|var\.)/);
} chop $species; # last space
$sub_species = join ' ',@spflds if(@spflds); } else { $species = 'sp.'; } # does ORGANISM start with any words which make its genus undefined?
# these are in @unkn_genus
# this in case species starts with uppercase so isn't caught above.
# alter common name if required
my $unconv = 0; # is it unconventional species name?
my @unkn_genus = ('unknown','unclassified','uncultured','unidentified'); foreach (@unkn_genus) { if ($genus && $genus =~ m/$_/i) {
$species = $genus . " " . $species;
undef $genus; $unconv = 1; last; } elsif ($species =~ m/$_/i) {
$unconv = 1;
last; } } if (!$unconv && !$sub_species && $species =~ s/^(\w+)\s(\w+)$/$1/) { # need to extract subspecies from conventional ORGANISM format.
# Will the 'word' in a two element species name
# e.g. $species = 'thummi thummi' => $species='thummi' &
# $sub_species='thummi'
$sub_species = $2; } $self->genus($genus) if $genus; $self->sub_species($sub_species) if $sub_species; } $self->{_species} = $species; } return $self->{_species};
}
genusdescriptionprevnextTop
sub genus {
    my ($self, $genus) = @_;

    # TODO: instead of caching the raw name, cache the actual node instance.
if ($genus) { $self->{_genus} = $genus; } unless (defined $self->{_genus}) { my $genus_taxon = $self->tree->find_node(-rank => 'genus'); unless ($genus_taxon) { # just assume our ancestor is rank genus
$genus_taxon = $self->taxon->ancestor; } $self->{_genus} = $genus_taxon->scientific_name if $genus_taxon; } return $self->{_genus};
}
sub_speciesdescriptionprevnextTop
sub sub_species {
    my ($self, $sub) = @_;
    
    # TODO: instead of caching the raw name, cache the actual node instance.
if (!defined $self->{'_sub_species'}) { my $ss_taxon = $self->tree->find_node(-rank => 'subspecies'); if ($ss_taxon) { if ($sub) { $ss_taxon->scientific_name($sub); # *** weakening ref to our root node in species() to solve a
# memory leak means that we have a subspecies taxon to set
# during the first call to species(), but it has vanished by
# the time a user subsequently calls sub_species() to get the
# value. So we 'cheat' and just store the subspecies name in
# our self hash, instead of the tree. Is this a problem for
# a Species object? Can't decide --sendu
# This can now be changed to deal with this information on the
# fly. For now, the caching remains, but maybe we should just
# let these things deal with mutable data as needed? -- cjfields
$self->{'_sub_species'} = $sub; } return $ss_taxon->scientific_name; } else { # should we create a node here to be added to the tree?
} } # fall back to direct storage on self
$self->{'_sub_species'} = $sub if $sub; return $self->{'_sub_species'};
}
variantdescriptionprevnextTop
sub variant {
    my ($self, $var) = @_;
    
    # TODO: instead of caching the raw name, cache the actual node instance.
if (!defined $self->{'_variant'}) { my $var_taxon = $self->tree->find_node(-rank => 'variant'); if ($var_taxon) { if ($var) { $var_taxon->scientific_name($var); } return $var_taxon->scientific_name; } else { # should we create a node here to be added to the tree?
} } # fall back to direct storage on self
$self->{'_variant'} = $var if $var; return $self->{'_variant'};
}
binomialdescriptionprevnextTop
sub binomial {
    my ($self, $full) = @_;
    my $rank = $self->taxon->rank || 'no rank';
    
    my ($species, $genus) = ($self->species, $self->genus);
    unless (defined $species) {
        $species = 'sp.';
        $self->warn("requested binomial but classification was not set");
    }
    $genus = '' unless( defined $genus);
    
    $species =~ s/$genus\s+//;
    
    my $bi = "$genus $species";
    if (defined($full) && $full =~ /full/i) { 
        my $ssp = $self->sub_species;
        if ($ssp) {
            $ssp =~ s/$bi\s+//;
            $ssp =~ s/$species\s+//;
            $bi .= " $ssp";
        }
    }
    return $bi;
}
validate_species_namedescriptionprevnextTop
sub validate_species_name {
    my( $self, $string ) = @_;

    return 1 if $string eq "sp.";
    return 1 if $string =~ /strain/;
    return 1 if $string =~ /^[a-z][\w\s-]+$/i;
    $self->throw("Invalid species name '$string'");
}
validate_namedescriptionprevnextTop
sub validate_name {
    return 1;
}
organelledescriptionprevnextTop
sub organelle {
    my($self) = shift;
    return $self->{'_organelle'} = shift if @_;
    return $self->{'_organelle'};
}
node_namedescriptionprevnextTop
sub node_name {
shift->taxon->node_name(@_)
}
scientific_namedescriptionprevnextTop
sub scientific_name {
shift->taxon->node_name(@_)
}
iddescriptionprevnextTop
sub id {
shift->taxon->id(@_)
}
object_iddescriptionprevnextTop
sub object_id {
shift->taxon->id(@_)
}
ncbi_taxiddescriptionprevnextTop
sub ncbi_taxid {
shift->taxon->ncbi_taxid(@_)
}
rankdescriptionprevnextTop
sub rank {
shift->taxon->rank(@_)
}
divisiondescriptionprevnextTop
sub division {
shift->taxon->division(@_)
}
common_namesdescriptionprevnextTop
sub common_names {
shift->taxon->common_names(@_)
}
common_namedescriptionprevnextTop
sub common_name {
shift->taxon->common_names(@_)
}
genetic_codedescriptionprevnextTop
sub genetic_code {
shift->taxon->genetic_code(@_)
}
mitochondrial_genetic_codedescriptionprevnextTop
sub mitochondrial_genetic_code {
shift->taxon->mitochondrial_genetic_code(@_)
}
create_datedescriptionprevnextTop
sub create_date {
 shift->taxon->create_date(@_)
}
pub_datedescriptionprevnextTop
sub pub_date {
 shift->taxon->pub_date(@_)
}
update_datedescriptionprevnextTop
sub update_date {
 shift->taxon->update_date(@_)
}
db_handledescriptionprevnextTop
sub db_handle {
 shift->taxon->db_handle(@_)
}
parent_iddescriptionprevnextTop
sub parent_id {
 shift->taxon->parent_id(@_)
}
parent_taxon_iddescriptionprevnextTop
sub parent_taxon_id {
 shift->taxon->parent_id(@_)
}
versiondescriptionprevnextTop
sub version {
 shift->taxon->version(@_)
}
authoritydescriptionprevnextTop
sub authority {
 shift->taxon->authority(@_)
}
namespacedescriptionprevnextTop
sub namespace {
 shift->taxon->namespace(@_)
}
ancestordescriptionprevnextTop
sub ancestor {
 shift->taxon->ancestor(@_)
}
get_Parent_NodedescriptionprevnextTop
sub get_Parent_Node {
 shift->taxon->get_Parent_Node(@_)
}
each_DescendentdescriptionprevnextTop
sub each_Descendent {
 shift->taxon->each_Descendent(@_)
}
get_Children_NodesdescriptionprevnextTop
sub get_Children_Nodes {
 shift->taxon->get_Children_Nodes(@_)
}
remove_DescendantdescriptionprevnextTop
sub remove_Descendant {
 shift->taxon->remove_Descendant(@_)
}
namedescriptionprevnextTop
sub name {
 shift->taxon->name(@_)
}
taxondescriptionprevnextTop
sub taxon {
    my ($self, $taxon) = @_;
    if (!$self->{taxon} || $taxon) {
        $taxon ||= Bio::Taxon->new();
        $self->{taxon} = $taxon;
    }
    $self->{taxon};
}
treedescriptionprevnextTop
sub tree {
    my ($self, $tree) = @_;
    if (!$self->{tree} || $tree) {
        $tree ||= Bio::Tree::Tree->new();
        delete $tree->{_root_cleanup_methods};
        $self->{tree} = $tree;
    }
    $self->{tree};
}
DESTROYdescriptionprevnextTop
sub DESTROY {
    my $self = shift;
    $self->tree->cleanup_tree;
    delete $self->{tree};
    $self->taxon->node_cleanup;
}

1;
}
General documentation
FEEDBACKTop
Mailing ListsTop
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 Top
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 BugsTop
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://redmine.open-bio.org/projects/bioperl/
AUTHORTop
James Gilbert email jgrg@sanger.ac.uk
CONTRIBUTORSTop
Sendu Bala, bix@sendu.me.uk
Chris Fields, cjfields at bioperl dot org
APPENDIXTop
The rest of the documentation details each of the object
methods. Internal methods are usually preceded with a _
DelegationTop
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.