NAME

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

SYNOPSIS

         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);

DESCRIPTION

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

TODO

       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.

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 - Sendu Bala

       Email bix@sendu.me.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::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.

   add_lineage
        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
   get_num_taxa
        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

   get_taxon
        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).
                    OR
                  -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
                              IDs.
                    OR
                  -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.

   get_taxonids
        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

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

   each_Descendent
        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)