Bio/AnnotationCollectionI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::AnnotationCollectionI
   4 #
   5 # Cared for by Ewan Birney <birney@ebi.ac.uk>
   6 #
   7 # Copyright Ewan Birney
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::AnnotationCollectionI - Interface for annotation collections
  16
  17 =head1 SYNOPSIS
  18
  19    # get an AnnotationCollectionI somehow, eg
  20
  21    $ac = $seq->annotation();
  22
  23    foreach $key ( $ac->get_all_annotation_keys() ) {
  24        @values = $ac->get_Annotations($key);
  25        foreach $value ( @values ) {
  26           # value is an Bio::AnnotationI, and defines a "as_text" method
  27           print "Annotation ",$key," stringified value ",$value->as_text,"\n";
  28
  29           # also defined hash_tree method, which allows data orientated
  30           # access into this object
  31           $hash = $value->hash_tree();
  32        }
  33    }
  34
  35 =head1 DESCRIPTION
  36
  37 Annotation Collections are a way of storing a series of "interesting
  38 facts" about something. We call an "interesting fact" in Bioperl an
  39 Annotation (this differs from a Sequence Feature, which is called
  40 a Sequence Feature and may or may not have an Annotation Collection).
  41
  42 A benefit of this approach is that all sorts of simple, interesting
  43 observations can be collected, the possibility is endless.
  44
  45 The Bioperl approach is that the "interesting facts" are represented by
  46 Bio::AnnotationI objects. The interface Bio::AnnotationI guarantees
  47 two methods
  48
  49    $obj->as_text(); # string formated to display to users
  50
  51 and
  52
  53    $obj->hash_tree(); # hash with defined rules for data-orientated discovery
  54
  55 The hash_tree method is designed to play well with XML output and
  56 other "nested-tag-of-data-values", think BoulderIO and/or Ace stuff. For more
  57 information see L<Bio::AnnotationI>.
  58
  59 Annotations are stored in AnnotationCollections, each Annotation under a
  60 different "tag". The tags allow simple discovery of the available annotations,
  61 and in some cases (like the tag "gene_name") indicate how to interpret the
  62 data underneath the tag. The tag is only one tag deep and each tag can have an
  63 array of values.
  64
  65 In addition, AnnotationCollections are guaranteed to maintain consistent
  66 types of objects under each tag - at least that each object complies to one
  67 interface. The "standard" AnnotationCollection insists the following rules
  68 are set up:
  69
  70   Tag            Object
  71   ---            ------
  72   comment        Bio::Annotation::Comment
  73   dblink         Bio::Annotation::DBLink
  74   description    Bio::Annotation::SimpleValue
  75   gene_name      Bio::Annotation::SimpleValue
  76   ontology_term  Bio::Annotation::OntologyTerm
  77   reference      Bio::Annotation::Reference
  78
  79 These tags are the implict tags that the SeqIO system needs to round-trip
  80 GenBank/EMBL/Swissprot.
  81
  82 However, you as a user and us collectively as a community can grow the
  83 "standard" tag mapping over time and specifically for a particular
  84 area.
  85
  86
  87 =head1 FEEDBACK
  88
  89 =head2 Mailing Lists
  90
  91 User feedback is an integral part of the evolution of this and other
  92 Bioperl modules. Send your comments and suggestions preferably to one
  93 of the Bioperl mailing lists.  Your participation is much appreciated.
  94
  95   bioperl-l@bioperl.org
  96
  97 =head2 Reporting Bugs
  98
  99 Report bugs to the Bioperl bug tracking system to help us keep track
 100 the bugs and their resolution.  Bug reports can be submitted via the
 101 web:
 102
 103   http://bugzilla.open-bio.org/
 104
 105 =head1 AUTHOR - Ewan Birney
 106
 107 Email birney@ebi.ac.uk
 108
 109 =head1 APPENDIX
 110
 111 The rest of the documentation details each of the object methods. Internal methods
 112 are usually preceded with a _
 113
 114 =cut
 115
 116
 117 # Let the code begin...
 118
 119 package Bio::AnnotationCollectionI;
 120 use strict;
 121
 122 # Interface preamble - inherits from Bio::Root::RootI
 123
 124
 125 use base qw(Bio::Root::RootI);
 126
 127 =head1 ACCESSOR METHODS
 128
 129 Use these for Bio::AnnotationI object access.
 130
 131 =cut
 132
 133 =head2 get_all_annotation_keys()
 134
 135  Usage   : $ac->get_all_annotation_keys()
 136  Function: gives back a list of annotation keys, which are simple text strings
 137  Returns : list of strings
 138  Args    : none
 139
 140 =cut
 141
 142 sub get_all_annotation_keys{
 143     shift->throw_not_implemented();
 144 }
 145
 146
 147 =head2 get_Annotations()
 148
 149  Usage   : my @annotations = $collection->get_Annotations('key')
 150  Function: Retrieves all the Bio::AnnotationI objects for a specific key
 151  Returns : list of Bio::AnnotationI - empty if no objects stored for a key
 152  Args    : string which is key for annotations
 153
 154 =cut
 155
 156 sub get_Annotations{
 157     shift->throw_not_implemented();
 158 }
 159
 160 =head2 add_Annotation()
 161
 162  Usage   : $self->add_Annotation('reference',$object);
 163            $self->add_Annotation($object,'Bio::MyInterface::DiseaseI');
 164            $self->add_Annotation($object);
 165            $self->add_Annotation('disease',$object,'Bio::MyInterface::DiseaseI');
 166  Function: Adds an annotation for a specific key.
 167
 168            If the key is omitted, the object to be added must provide a value
 169            via its tagname().
 170
 171            If the archetype is provided, this and future objects added under
 172            that tag have to comply with the archetype and will be rejected
 173            otherwise.
 174
 175  Returns : none
 176  Args    : annotation key ('disease', 'dblink', ...)
 177            object to store (must be Bio::AnnotationI compliant)
 178            [optional] object archetype to map future storage of object
 179            of these types to
 180
 181 =cut
 182
 183 sub add_Annotation {
 184   shift->throw_not_implemented();
 185 }
 186
 187 =head2 remove_Annotations()
 188
 189  Usage   :
 190  Function: Remove the annotations for the specified key from this collection.
 191  Returns : an list of Bio::AnnotationI compliant objects which were stored
 192            under the given key(s)
 193  Args    : the key(s) (tag name(s), one or more strings) for which to
 194            remove annotations (optional; if none given, flushes all
 195            annotations)
 196
 197 =cut
 198
 199 sub remove_Annotations{
 200   shift->throw_not_implemented();
 201 }
 202
 203 =head2 get_num_of_annotations()
 204
 205  Usage   : my $count = $collection->get_num_of_annotations()
 206  Function: Returns the count of all annotations stored in this collection
 207  Returns : integer
 208  Args    : none
 209
 210 =cut
 211
 212 sub get_num_of_annotations{
 213     shift->throw_not_implemented();
 214 }
 215
 216 1;