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 | BEGIN@132 | Bio::AnnotationCollectionI::
1 | 1 | 1 | 8µs | 69µs | BEGIN@137 | Bio::AnnotationCollectionI::
0 | 0 | 0 | 0s | 0s | add_Annotation | Bio::AnnotationCollectionI::
0 | 0 | 0 | 0s | 0s | get_Annotations | Bio::AnnotationCollectionI::
0 | 0 | 0 | 0s | 0s | get_all_annotation_keys | Bio::AnnotationCollectionI::
0 | 0 | 0 | 0s | 0s | get_num_of_annotations | Bio::AnnotationCollectionI::
0 | 0 | 0 | 0s | 0s | remove_Annotations | Bio::AnnotationCollectionI::
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; |