/ 
bioperl-1.4
/ Bio::Species

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

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.

CONTACT

James Gilbert email jgrg@sanger.ac.uk

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: Fills or returns the classification list in
          the object.  The array provided must be in
          the order SPECIES, GENUS ---> KINGDOM.
          Checks are made that species is in lower case,
Example : $obj->classification(qw( 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.

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)

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)

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

species

Title   : species
Usage   : $self->species( $species );
          $species = $self->species();
Function: Get or set the scientific species name.  The species
          name must be in lower case.
Example : $self->species( 'sapiens' );
Returns : Scientific species name as string
Args    : Scientific species name as string

genus

Title   : genus
Usage   : $self->genus( $genus );
          $genus = $self->genus();
Function: Get or set the scientific genus name.  The genus
          must be in title case.
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:
Returns : value of sub_species
Args    : newvalue (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.

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)

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)