Bio/AnnotationCollectionI.pm

filter: Statementstmt 61.5% 8 / 13 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 28.5% 2 / 7 Podpod 100% 5 / 5 totaltotal 60.0% 15 / 25 CC 1 SCAR 5.4
CC
1
Cov
62%
get_all_annotation_keys
2.0
get_Annotations
2.0
add_Annotation
2.0
CRAP 1.7
« Bio/Matrix/PSM/InstanceSiteI.pm ↑ Summary Bio/Ontology/RelationshipI.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 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;
« Bio/Matrix/PSM/InstanceSiteI.pm ↑ Summary Bio/Ontology/RelationshipI.pm »