Provided by: libbio-perl-perl_1.7.7-1_all bug


       Bio::Species - Generic species object.


           $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

           # For storing subspecies


       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.


   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.
                  - General discussion  - About the mailing lists

       Please direct usage questions or support issues to the mailing list:

       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:


       James Gilbert email


       Sendu Bala, Chris Fields, cjfields at bioperl dot org


       The rest of the documentation details each of the object methods. Internal methods are
       usually preceded with a _

        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

        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
                  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.

        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)

        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)

        Title   : division
        Usage   : $obj->division($newval)
        Function: Genbank Division for a species
        Returns : value of division (a scalar)
        Args    : value of division (a scalar)

        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)

        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

        Title   : sub_species
        Usage   : $obj->sub_species($newval)
        Function: Get or set the scientific subspecies name.
        Returns : value of sub_species
        Args    : newvalue (optional)

        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)

        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

        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.

        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.

       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.

        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)

        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)