NAME

       Bio::Annotation::Collection - Default Perl implementation of AnnotationCollectionI

SYNOPSIS

          # get an AnnotationCollectionI somehow, eg

          $ac = $seq->annotation();

          foreach $key ( $ac->get_all_annotation_keys() ) {
              @values = $ac->get_Annotations($key);
              foreach $value ( @values ) {
                 # value is an Bio::AnnotationI, and defines a "as_text" method
                 print "Annotation ",$key," stringified value ",$value->as_text,"\n";

                 # also defined hash_tree method, which allows data orientated
                 # access into this object
                 $hash = $value->hash_tree();
              }
          }

DESCRIPTION

       Bioperl implementation for Bio::AnnotationCollectionI

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 one of the Bioperl mailing lists. 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 the bugs and their
       resolution.  Bug reports can be submitted via the web:

         https://redmine.open-bio.org/projects/bioperl/

AUTHOR - Ewan Birney

       Email birney@ebi.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   : $coll = Bio::Annotation::Collection->new()
        Function: Makes a new Annotation::Collection object.
        Returns : Bio::Annotation::Collection
        Args    : none

Bio::AnnotationCollectionI implementing methods

   get_all_annotation_keys
        Title   : get_all_annotation_keys
        Usage   : $ac->get_all_annotation_keys()
        Function: gives back a list of annotation keys, which are simple text strings
        Returns : list of strings
        Args    : none

   get_Annotations
        Title   : get_Annotations
        Usage   : my @annotations = $collection->get_Annotations('key')
        Function: Retrieves all the Bio::AnnotationI objects for one or more
                  specific key(s).

                  If no key is given, returns all annotation objects.

                  The returned objects will have their tagname() attribute set to
                  the key under which they were attached, unless the tagname was
                  already set.

        Returns : list of Bio::AnnotationI - empty if no objects stored for a key
        Args    : keys (list of strings) for annotations (optional)

   get_nested_Annotations
        Title   : get_nested_Annotations
        Usage   : my @annotations = $collection->get_nested_Annotations(
                                       '-key' => \@keys,
                                       '-recursive => 1);
        Function: Retrieves all the Bio::AnnotationI objects for one or more
                  specific key(s). If -recursive is set to true, traverses the nested
                  annotation collections recursively and returns all annotations
                  matching the key(s).

                  If no key is given, returns all annotation objects.

                  The returned objects will have their tagname() attribute set to
                  the key under which they were attached, unless the tagname was
                  already set.

        Returns : list of Bio::AnnotationI - empty if no objects stored for a key
        Args    : -keys      => arrayref of keys to search for (optional)
                  -recursive => boolean, whether or not to recursively traverse the
                   nested annotations and return annotations with matching keys.

   get_all_Annotations
        Title   : get_all_Annotations
        Usage   :
        Function: Similar to get_Annotations, but traverses and flattens nested
                  annotation collections. This means that collections in the
                  tree will be replaced by their components.

                  Keys will not be passed on to nested collections. I.e., if the
                  tag name of a nested collection matches the key, it will be
                  flattened in its entirety.

                  Hence, for un-nested annotation collections this will be identical
                  to get_Annotations.
        Example :
        Returns : an array of L<Bio::AnnotationI> compliant objects
        Args    : keys (list of strings) for annotations (optional)

   get_num_of_annotations
        Title   : get_num_of_annotations
        Usage   : my $count = $collection->get_num_of_annotations()
        Function: Returns the count of all annotations stored in this collection
        Returns : integer
        Args    : none

Implementation specific functions - mainly for adding

   add_Annotation
        Title   : add_Annotation
        Usage   : $self->add_Annotation('reference',$object);
                  $self->add_Annotation($object,'Bio::MyInterface::DiseaseI');
                  $self->add_Annotation($object);
                  $self->add_Annotation('disease',$object,'Bio::MyInterface::DiseaseI');
        Function: Adds an annotation for a specific key.

                  If the key is omitted, the object to be added must provide a value
                  via its tagname().

                  If the archetype is provided, this and future objects added under
                  that tag have to comply with the archetype and will be rejected
                  otherwise.

        Returns : none
        Args    : annotation key ('disease', 'dblink', ...)
                  object to store (must be Bio::AnnotationI compliant)
                  [optional] object archetype to map future storage of object
                             of these types to

   remove_Annotations
        Title   : remove_Annotations
        Usage   :
        Function: Remove the annotations for the specified key from this collection.
        Example :
        Returns : an array Bio::AnnotationI compliant objects which were stored
                  under the given key(s)
        Args    : the key(s) (tag name(s), one or more strings) for which to
                  remove annotations (optional; if none given, flushes all
                  annotations)

   flatten_Annotations
        Title   : flatten_Annotations
        Usage   :
        Function: Flattens part or all of the annotations in this collection.

                  This is a convenience method for getting the flattened
                  annotation for the given keys, removing the annotation for
                  those keys, and adding back the flattened array.

                  This should not change anything for un-nested collections.
        Example :
        Returns : an array Bio::AnnotationI compliant objects which were stored
                  under the given key(s)
        Args    : list of keys (strings) the annotation for which to flatten,
                  defaults to all keys if not given

Bio::AnnotationI methods implementations

          This is to allow nested annotation: you can use a collection as an
          annotation object for an annotation collection.

   as_text
        Title   : as_text
        Usage   :
        Function: See L<Bio::AnnotationI>
        Example :
        Returns : a string
        Args    : none

   display_text
        Title   : display_text
        Usage   : my $str = $ann->display_text();
        Function: returns a string. Unlike as_text(), this method returns a string
                  formatted as would be expected for te specific implementation.

                  One can pass a callback as an argument which allows custom text
                  generation; the callback is passed the current instance and any text
                  returned
        Example :
        Returns : a string
        Args    : [optional] callback

   hash_tree
        Title   : hash_tree
        Usage   :
        Function: See L<Bio::AnnotationI>
        Example :
        Returns : a hash reference
        Args    : none

   tagname
        Title   : tagname
        Usage   : $obj->tagname($newval)
        Function: Get/set the tagname for this annotation value.

                  Setting this is optional. If set, it obviates the need to
                  provide a tag to Bio::AnnotationCollectionI when adding
                  this object. When obtaining an AnnotationI object from the
                  collection, the collection will set the value to the tag
                  under which it was stored unless the object has a tag
                  stored already.

        Example :
        Returns : value of tagname (a scalar)
        Args    : new value (a scalar, optional)

Backward compatible functions

       Functions put in for backward compatibility with old Bio::Annotation.pm stuff

   description
        Title   : description
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   add_gene_name
        Title   : add_gene_name
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   each_gene_name
        Title   : each_gene_name
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   add_Reference
        Title   : add_Reference
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   each_Reference
        Title   : each_Reference
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   add_Comment
        Title   : add_Comment
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   each_Comment
        Title   : each_Comment
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   add_DBLink
        Title   : add_DBLink
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

   each_DBLink
        Title   : each_DBLink
        Usage   :
        Function:
        Example :
        Returns :
        Args    :

Implementation management functions

   _typemap
        Title   : _typemap
        Usage   : $obj->_typemap($newval)
        Function:
        Example :
        Returns : value of _typemap
        Args    : newvalue (optional)