Provided by: libbio-perl-perl_1.7.2-2_all bug


       Bio::DB::Taxonomy::list - An implementation of Bio::DB::Taxonomy that accepts lists of
       words to build a database


         use Bio::DB::Taxonomy;

         my $db = Bio::DB::Taxonomy->new( -source => 'list' );

         my @ranks = ('superkingdom', 'class', 'genus', 'species');
         my @names = ('Eukaryota', 'Mammalia', 'Homo', 'Homo sapiens');
         $db->add_lineage(-names => \@names, -ranks => \@ranks);

         @names = ('Eukaryota', 'Mammalia', 'Mus', 'Mus musculus');
         $db->add_lineage(-names => \@names, -ranks => \@ranks);


       This is an implementation which uses supplied lists of words to create a database from
       which you can extract Bio::Taxon objects.


       It is possible this module could do something like store the data it builds up to disc.
       Would that be useful?  At any rate, this is why the module is called 'list' and not
       'in_memory' or similar.


   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:

AUTHOR - Sendu Bala



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

        Title   : new
        Usage   : my $obj = Bio::DB::Taxonomy::list->new();
        Function: Builds a new Bio::DB::Taxonomy::list object
        Returns : an instance of Bio::DB::Taxonomy::list
        Args    : optional, as per the add_lineage() method.

        Title   : add_lineage
        Usage   : my @names = ('Eukaryota', 'Mammalia', 'Homo', 'Homo sapiens');
                  my @ranks = ('superkingdom', 'class', 'genus', 'species');
                  $db->add_lineage( -names => \@names, -ranks => \@ranks );
        Function: Add a lineage to the database, where the lineage is described by
                  a list of scientific names in the order root->leaf. The rank of each
                  name can optionally be described by supplying an additional list
                  of rank names in the same order (eg. superkingdom->species).
        Returns : 1 for success
        Args    : -names => [] : array ref of scientific names, REQUIRED
                  -ranks => [] : array ref of rank names, same order as above, OPTIONAL

   Bio::DB::Taxonomy Interface implementation
        Title   : get_num_taxa
        Usage   : my $num = $db->get_num_taxa();
        Function: Get the number of taxa stored in the database.
        Returns : A number
        Args    : None

        Title   : get_taxon
        Usage   : my $taxon = $db->get_taxon(-taxonid => $taxonid)
        Function: Get a Bio::Taxon object from the database.
        Returns : Bio::Taxon object
        Args    : A single value which is the ID of the taxon to retrieve
                    OR named args, as follows:
                  -taxonid => Taxonomy ID (NB: these are not NCBI taxonomy ids but
                              'list' pre-fixed ids unique to the list database).
                  -name    => String (to query by a taxonomy name). A given taxon name
                              can match different taxonomy objects. When that is the
                              case, a warning is displayed and the first matching taxon
                              is reported. See get_taxonids() to get all matching taxon
                  -names   => Array ref of lineage names, like in add_lineage(). To
                              overcome the limitations of -name, you can use -names to
                              provide the full lineage of the taxon you want and get a
                              unique, unambiguous taxon object.

        Title   : get_taxonids
        Usage   : my @taxonids = $db->get_taxonids('Homo sapiens');
        Function: Searches for a taxonid (generated by the list module) based on a
                  query string. Note that multiple taxonids can match to the same
                  supplied name.
        Returns : array of integer ids in list context, one of these in scalar context
        Args    : string representing taxon's name

        Title   : ancestor
        Usage   : my $ancestor_taxon = $db->ancestor($taxon)
        Function: Retrieve the full ancestor taxon of a supplied Taxon from the
        Returns : Bio::Taxon
        Args    : Bio::Taxon (that was retrieved from this database)

        Title   : each_Descendent
        Usage   : my @taxa = $db->each_Descendent($taxon);
        Function: Get all the descendents of the supplied Taxon (but not their
                  descendents, ie. not a recursive fetchall).
        Returns : Array of Bio::Taxon objects
        Args    : Bio::Taxon (that was retrieved from this database)