| Filename | /Users/ap13/perl5/lib/perl5/Bio/AnnotationCollectionI.pm |
| Statements | Executed 5 statements in 166µs |
| Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
|---|---|---|---|---|---|
| 1 | 1 | 1 | 15µs | 34µs | Bio::AnnotationCollectionI::BEGIN@132 |
| 1 | 1 | 1 | 8µs | 69µs | Bio::AnnotationCollectionI::BEGIN@137 |
| 0 | 0 | 0 | 0s | 0s | Bio::AnnotationCollectionI::add_Annotation |
| 0 | 0 | 0 | 0s | 0s | Bio::AnnotationCollectionI::get_Annotations |
| 0 | 0 | 0 | 0s | 0s | Bio::AnnotationCollectionI::get_all_annotation_keys |
| 0 | 0 | 0 | 0s | 0s | Bio::AnnotationCollectionI::get_num_of_annotations |
| 0 | 0 | 0 | 0s | 0s | Bio::AnnotationCollectionI::remove_Annotations |
| Line | State ments |
Time on line |
Calls | Time in subs |
Code |
|---|---|---|---|---|---|
| 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://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 | 2 | 44µs | 2 | 53µs | # spent 34µs (15+19) within Bio::AnnotationCollectionI::BEGIN@132 which was called:
# once (15µs+19µs) by base::import at line 132 # spent 34µs making 1 call to Bio::AnnotationCollectionI::BEGIN@132
# spent 19µs making 1 call to strict::import |
| 133 | |||||
| 134 | # Interface preamble - inherits from Bio::Root::RootI | ||||
| 135 | |||||
| 136 | |||||
| 137 | 2 | 120µs | 2 | 69µs | # spent 69µs (8+60) within Bio::AnnotationCollectionI::BEGIN@137 which was called:
# once (8µs+60µs) by base::import at line 137 # spent 69µs making 1 call to Bio::AnnotationCollectionI::BEGIN@137
# spent 60µs making 1 call to base::import, recursion: max depth 1, sum of overlapping time 60µs |
| 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 | 2µs | 1; |