Bio/AnnotationCollectionI.pm

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