| 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 formatted 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://github.com/bioperl/bioperl-live/issues | ||
| 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 | 316 | $Bio::AnnotationCollectionI::VERSION = '1.7.8'; | |
| 133 | 316 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 134 | |||
| 135 | # Interface preamble - inherits from Bio::Root::RootI | ||
| 136 | |||
| 137 | |||
| 138 | 316 | ▶ | use base qw(Bio::Root::RootI); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 139 | |||
| 140 | =head1 ACCESSOR METHODS | ||
| 141 | |||
| 142 | Use these for Bio::AnnotationI object access. | ||
| 143 | |||
| 144 | =cut | ||
| 145 | |||
| 146 | =head2 get_all_annotation_keys() | ||
| 147 | |||
| 148 | Usage : $ac->get_all_annotation_keys() | ||
| 149 | Function: gives back a list of annotation keys, which are simple text strings | ||
| 150 | Returns : list of strings | ||
| 151 | Args : none | ||
| 152 | |||
| 153 | =cut | ||
| 154 | |||
| 155 | 0 | ▶ | sub get_all_annotation_keys{ |
|
Subroutine
get_all_annotation_keys: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 156 | 0 | shift->throw_not_implemented(); | |
| 157 | } | ||
| 158 | |||
| 159 | |||
| 160 | =head2 get_Annotations() | ||
| 161 | |||
| 162 | Usage : my @annotations = $collection->get_Annotations('key') | ||
| 163 | Function: Retrieves all the Bio::AnnotationI objects for a specific key | ||
| 164 | Returns : list of Bio::AnnotationI - empty if no objects stored for a key | ||
| 165 | Args : string which is key for annotations | ||
| 166 | |||
| 167 | =cut | ||
| 168 | |||
| 169 | 0 | ▶ | sub get_Annotations{ |
|
Subroutine
get_Annotations: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 170 | 0 | shift->throw_not_implemented(); | |
| 171 | } | ||
| 172 | |||
| 173 | =head2 add_Annotation() | ||
| 174 | |||
| 175 | Usage : $self->add_Annotation('reference',$object); | ||
| 176 | $self->add_Annotation($object,'Bio::MyInterface::DiseaseI'); | ||
| 177 | $self->add_Annotation($object); | ||
| 178 | $self->add_Annotation('disease',$object,'Bio::MyInterface::DiseaseI'); | ||
| 179 | Function: Adds an annotation for a specific key. | ||
| 180 | |||
| 181 | If the key is omitted, the object to be added must provide a value | ||
| 182 | via its tagname(). | ||
| 183 | |||
| 184 | If the archetype is provided, this and future objects added under | ||
| 185 | that tag have to comply with the archetype and will be rejected | ||
| 186 | otherwise. | ||
| 187 | |||
| 188 | Returns : none | ||
| 189 | Args : annotation key ('disease', 'dblink', ...) | ||
| 190 | object to store (must be Bio::AnnotationI compliant) | ||
| 191 | [optional] object archetype to map future storage of object | ||
| 192 | of these types to | ||
| 193 | |||
| 194 | =cut | ||
| 195 | |||
| 196 | 0 | ▶ | sub add_Annotation { |
|
Subroutine
add_Annotation: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 197 | 0 | shift->throw_not_implemented(); | |
| 198 | } | ||
| 199 | |||
| 200 | =head2 remove_Annotations() | ||
| 201 | |||
| 202 | Usage : | ||
| 203 | Function: Remove the annotations for the specified key from this collection. | ||
| 204 | Returns : an list of Bio::AnnotationI compliant objects which were stored | ||
| 205 | under the given key(s) | ||
| 206 | Args : the key(s) (tag name(s), one or more strings) for which to | ||
| 207 | remove annotations (optional; if none given, flushes all | ||
| 208 | annotations) | ||
| 209 | |||
| 210 | =cut | ||
| 211 | |||
| 212 | 0 | ▶ | sub remove_Annotations{ |
|
Subroutine
remove_Annotations: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 213 | 0 | shift->throw_not_implemented(); | |
| 214 | } | ||
| 215 | |||
| 216 | =head2 get_num_of_annotations() | ||
| 217 | |||
| 218 | Usage : my $count = $collection->get_num_of_annotations() | ||
| 219 | Function: Returns the count of all annotations stored in this collection | ||
| 220 | Returns : integer | ||
| 221 | Args : none | ||
| 222 | |||
| 223 | =cut | ||
| 224 | |||
| 225 | 0 | ▶ | sub get_num_of_annotations{ |
|
Subroutine
get_num_of_annotations: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 226 | 0 | shift->throw_not_implemented(); | |
| 227 | } | ||
| 228 | |||
| 229 | 316 | 1; | |