Bio/SeqFeature/AnnotationAdaptor.pm

filter: Statementstmt 78.4% 73 / 93 Branchbran 48.1% 26 / 54 Conditioncond 41.6% 10 / 24 MC/DCmcdc 14.2% 2 / 14 Subroutinesub 91.6% 11 / 12 Podpod 100% 9 / 9 totaltotal 63.5% 131 / 206 CC 40 SCAR 29.6
CC
40
Cov
64%
remove_Annotations
56.0
add_Annotation
29.5
get_Annotations
7.5
CRAP 19.3
« Bio/AlignIO/clustalw.pm ↑ Summary Bio/SearchIO/Writer/HSPTableWriter.pm »
1 #
2 # BioPerl module for Bio::SeqFeature::AnnotationAdaptor
3 #
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
5 #
6 # Cared for by Hilmar Lapp <hlapp at gmx.net>
7 #
8 # Copyright Hilmar Lapp
9 #
10 # You may distribute this module under the same terms as perl itself
11  
12 #
13 # (c) Hilmar Lapp, hlapp at gmx.net, 2002.
14 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
15 #
16 # You may distribute this module under the same terms as perl itself.
17 # Refer to the Perl Artistic License (see the license accompanying this
18 # software package, or see http://www.perl.com/language/misc/Artistic.html)
19 # for the terms under which you may use, modify, and redistribute this module.
20 #
21 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
22 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
23 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
24 #
25  
26 # POD documentation - main docs before the code
27  
28 =head1 NAME
29  
30 Bio::SeqFeature::AnnotationAdaptor - integrates SeqFeatureIs annotation
31  
32 =head1 SYNOPSIS
33  
34 use Bio::SeqFeature::Generic;
35 use Bio::SeqFeature::AnnotationAdaptor;
36  
37 # obtain a SeqFeatureI implementing object somehow
38 my $feat = Bio::SeqFeature::Generic->new(-start => 10, -end => 20);
39  
40 # add tag/value annotation
41 $feat->add_tag_value("mytag", "value of tag mytag");
42 $feat->add_tag_value("mytag", "another value of tag mytag");
43  
44 # Bio::SeqFeature::Generic also provides annotation(), which returns a
45 # Bio::AnnotationCollectionI compliant object
46 $feat->annotation->add_Annotation("dbxref", $dblink);
47  
48 # to integrate tag/value annotation with AnnotationCollectionI
49 # annotation, use this adaptor, which also implements
50 # Bio::AnnotationCollectionI
51 my $anncoll = Bio::SeqFeature::AnnotationAdaptor->new(-feature => $feat);
52  
53 # this will now return tag/value pairs as
54 # Bio::Annotation::SimpleValue objects
55 my @anns = $anncoll->get_Annotations("mytag");
56 # other added before annotation is available too
57 my @dblinks = $anncoll->get_Annotations("dbxref");
58  
59 # also supports transparent adding of tag/value pairs in
60 # Bio::AnnotationI flavor
61 my $tagval = Bio::Annotation::SimpleValue->new(-value => "some value",
62 -tagname => "some tag");
63 $anncoll->add_Annotation($tagval);
64 # this is now also available from the feature's tag/value system
65 my @vals = $feat->get_tag_values("some tag");
66  
67 =head1 DESCRIPTION
68  
69 L<Bio::SeqFeatureI> defines light-weight annotation of features
70 through tag/value pairs. Conversely, L<Bio::AnnotationCollectionI>
71 together with L<Bio::AnnotationI> defines an annotation bag, which is
72 better typed, but more heavy-weight because it contains every single
73 piece of annotation as objects. The frequently used base
74 implementation of Bio::SeqFeatureI, Bio::SeqFeature::Generic, defines
75 an additional slot for AnnotationCollectionI-compliant annotation.
76  
77 This adaptor provides a L<Bio::AnnotationCollectionI> compliant,
78 unified, and integrated view on the annotation of L<Bio::SeqFeatureI>
79 objects, including tag/value pairs, and annotation through the
80 annotation() method, if the object supports it. Code using this
81 adaptor does not need to worry about the different ways of possibly
82 annotating a SeqFeatureI object, but can instead assume that it
83 strictly follows the AnnotationCollectionI scheme. The price to pay is
84 that retrieving and adding annotation will always use objects instead
85 of light-weight tag/value pairs.
86  
87 In other words, this adaptor allows us to keep the best of both
88 worlds. If you create tens of thousands of feature objects, and your
89 only annotation is tag/value pairs, you are best off using the
90 features' native tag/value system. If you create a smaller number of
91 features, but with rich and typed annotation mixed with tag/value
92 pairs, this adaptor may be for you. Since its implementation is by
93 double-composition, you only need to create one instance of the
94 adaptor. In order to transparently annotate a feature object, set the
95 feature using the feature() method. Every annotation you add will be
96 added to the feature object, and hence will not be lost when you set
97 feature() to the next object.
98  
99 =head1 FEEDBACK
100  
101 =head2 Mailing Lists
102  
103 User feedback is an integral part of the evolution of this and other
104 Bioperl modules. Send your comments and suggestions preferably to
105 the Bioperl mailing list. Your participation is much appreciated.
106  
107 bioperl-l@bioperl.org - General discussion
108 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
109  
110 =head2 Support
111  
112 Please direct usage questions or support issues to the mailing list:
113  
114 I<bioperl-l@bioperl.org>
115  
116 rather than to the module maintainer directly. Many experienced and
117 reponsive experts will be able look at the problem and quickly
118 address it. Please include a thorough description of the problem
119 with code and data examples if at all possible.
120  
121 =head2 Reporting Bugs
122  
123 Report bugs to the Bioperl bug tracking system to help us keep track
124 of the bugs and their resolution. Bug reports can be submitted via the
125 web:
126  
127 https://github.com/bioperl/bioperl-live/issues
128  
129 =head1 AUTHOR - Hilmar Lapp
130  
131 Email hlapp at gmx.net
132  
133 =head1 APPENDIX
134  
135 The rest of the documentation details each of the object methods.
136 Internal methods are usually preceded with a _
137  
138 =cut
139  
140  
141 #' Let the code begin...
142  
143  
144 package Bio::SeqFeature::AnnotationAdaptor;
145 3 $Bio::SeqFeature::AnnotationAdaptor::VERSION = '1.7.8';
146 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
147  
148 # Object preamble - inherits from Bio::Root::Root
149  
150 3 ▶use Bio::Annotation::SimpleValue;
Subroutine BEGIN: called CC=1 SCAR=0.0
151  
152 3 ▶use base qw(Bio::Root::Root Bio::AnnotationCollectionI Bio::AnnotatableI);
Subroutine BEGIN: called CC=1 SCAR=0.0
153  
154 =head2 new
155  
156 Title : new
157 Usage : my $obj = Bio::SeqFeature::AnnotationAdaptor->new();
158 Function: Builds a new Bio::SeqFeature::AnnotationAdaptor object
159 Returns : an instance of Bio::SeqFeature::AnnotationAdaptor
160 Args : Named parameters
161 -feature the Bio::SeqFeatureI implementing object to adapt
162 (mandatory to be passed here, or set via feature()
163 before calling other methods)
164 -annotation the Bio::AnnotationCollectionI implementing object
165 for storing richer annotation (this will default to
166 the $feature->annotation() if it supports it)
167 -tagvalue_factory the object factory to use for creating tag/value
168 pair representing objects
169  
170  
171 =cut
172  
173 3 ▶sub new {
Subroutine new: called CC=4 SCAR=14.3
Pod documented
174 3 my($class,@args) = @_;
175  
176 3 my $self = $class->SUPER::new(@args);
177  
178 3 my ($feat,$anncoll,$fact) =
179 $self->_rearrange([qw(FEATURE
180 ANNOTATION
181 TAGVALUE_FACTORY)], @args);
182  
183 3 ▶ $self->feature($feat) if $feat;
Branch: 1 branch
BranchTrueFalseTotal
if $feat 3 0 3
184 3 ▶ $self->annotation($anncoll) if $feat;
Branch: 1 branch
BranchTrueFalseTotal
if $feat 3 0 3
185 3 ▶ $self->tagvalue_object_factory($fact) if $fact;
Branch: 1 branch
BranchTrueFalseTotal
if $fact 0 3 3
186  
187 3 return $self;
188 }
189  
190 =head2 feature
191  
192 Title : feature
193 Usage : $obj->feature($newval)
194 Function: Get/set the feature that this object adapts to an
195 AnnotationCollectionI.
196 Example :
197 Returns : value of feature (a Bio::SeqFeatureI compliant object)
198 Args : new value (a Bio::SeqFeatureI compliant object, optional)
199  
200  
201 =cut
202  
203 171 ▶sub feature{
Subroutine feature: called CC=2 SCAR=6.9
Pod documented
204 171 my ($self,$value) = @_;
205 171 ▶ if( defined $value) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value) 3 168 171
206 3 $self->{'feature'} = $value;
207 }
208 171 return $self->{'feature'};
209 }
210  
211 =head2 annotation
212  
213 Title : annotation
214 Usage : $obj->annotation($newval)
215 Function: Get/set the AnnotationCollectionI implementing object used by
216 this adaptor to store additional annotation that cannot be stored
217 by the SeqFeatureI itself.
218  
219 If requested before having been set, the value will default to the
220 annotation object of the feature if it has one.
221 Example :
222 Returns : value of annotation (a Bio::AnnotationCollectionI compliant object)
223 Args : new value (a Bio::AnnotationCollectionI compliant object, optional)
224  
225  
226 =cut
227  
228 14 ▶sub annotation{
Subroutine annotation: called CC=4 SCAR=17.2
Pod documented
229 14 my ($self,$value) = @_;
230  
231 14 ▶ if( defined $value) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value) 0 14 14
232 0 $self->{'annotation'} = $value;
233 }
234 14 ▶ if((! exists($self->{'annotation'})) &&
Branch: 1 branch
BranchTrueFalseTotal
if (not exists $self->{"annotation"} and $self->feature->can("annotation")) 14 0 14
Condition33%1/3
not exists $self->{"annotation"} and $self->feature->can("annotation")
!ll&&!rl&&r
0014
MC/DC0%0/2
not exists $self->{"annotation"} and $self->feature->can("annotation")
not exists $self->{"annotation"} $self->feature->can("annotation")
Truth table33%1/3
not(A) and B
A= not exists $self->{"annotation"}B= $self->feature->can("annotation")
ABresult
0X0
100
111
235 $self->feature()->can('annotation')) {
236 14 return $self->feature()->annotation();
237 }
238 0 return $self->{'annotation'};
239 }
240  
241 =head1 AnnotationCollectionI implementing methods
242  
243 =cut
244  
245 =head2 get_all_annotation_keys
246  
247 Title : get_all_annotation_keys
248 Usage : $ac->get_all_annotation_keys()
249 Function: gives back a list of annotation keys, which are simple text strings
250 Returns : list of strings
251 Args : none
252  
253 =cut
254  
255 1 ▶sub get_all_annotation_keys{
Subroutine get_all_annotation_keys: called CC=3 SCAR=11.3
Pod documented
256 1 my ($self) = @_;
257 1 my @keys = ();
258  
259 # get the tags from the feature object
260 1 ▶ if ($self->feature()->can('get_all_tags')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->feature->can('get_all_tags')) { } 1 0 1
261 1 push(@keys, $self->feature()->get_all_tags());
262 } else {
263 0 push(@keys, $self->feature()->all_tags());
264 }
265 # ask the annotation implementation in addition, while avoiding duplicates
266 1 ▶ if($self->annotation()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->annotation) 1 0 1
267 push(@keys,
268 1 grep { ! $self->feature->has_tag($_); }
269 $self->annotation()->get_all_annotation_keys());
270 }
271 # done
272 1 return @keys;
273 }
274  
275  
276 =head2 get_Annotations
277  
278 Title : get_Annotations
279 Usage : my @annotations = $collection->get_Annotations('key')
280 Function: Retrieves all the Bio::AnnotationI objects for a specific key
281 Returns : list of Bio::AnnotationI - empty if no objects stored for a key
282 Args : string which is key for annotations
283  
284 =cut
285  
286 3 ▶sub get_Annotations{
Subroutine get_Annotations: called CC=7 SCAR=20.2
Pod documented
287 3 my ($self, @keys) = @_;
288 3 my @anns = ();
289  
290 # we need a annotation object factory
291 3 my $fact = $self->tagvalue_object_factory();
292  
293 # get all tags if no keys have been provided
294 3 ▶ @keys = $self->feature->all_tags() unless @keys;
Branch: 1 branch
BranchTrueFalseTotal
unless @keys 0 3 3
295  
296 # build object for each value for each tag
297 3 foreach my $key (@keys) {
298 # protect against keys that aren't tags
299 3 ▶ next unless $self->feature->has_tag($key);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->feature->has_tag($key) 0 3 3
300 # add each tag/value pair as a SimpleValue object
301 3 foreach my $val ($self->feature()->get_tag_values($key)) {
302 5 my $ann;
303 5 ▶ if($fact) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fact) { } 0 5 5
304 0 $ann = $fact->create_object(-value => $val, -tagname => $key);
305 } else {
306 5 $ann = Bio::Annotation::SimpleValue->new(-value => $val,
307 -tagname => $key);
308 }
309 5 push(@anns, $ann);
310 }
311 }
312  
313 # add what is in the annotation implementation if any
314 3 ▶ if($self->annotation()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->annotation) 3 0 3
315 3 push(@anns, $self->annotation->get_Annotations(@keys));
316 }
317  
318 # done
319 3 return @anns;
320 }
321  
322 =head2 get_num_of_annotations
323  
324 Title : get_num_of_annotations
325 Usage : my $count = $collection->get_num_of_annotations()
326 Function: Returns the count of all annotations stored in this collection
327 Returns : integer
328 Args : none
329  
330  
331 =cut
332  
333 1 ▶sub get_num_of_annotations{
Subroutine get_num_of_annotations: called CC=3 SCAR=11.0
Pod documented
334 1 my ($self) = @_;
335  
336 # first, count the number of tags on the feature
337 1 my $num_anns = 0;
338  
339 1 foreach ($self->feature()->all_tags()) {
340 2 $num_anns += scalar( $self->feature()->get_tag_values($_));
341 }
342  
343 # add from the annotation implementation if any
344 1 ▶ if($self->annotation()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->annotation) 1 0 1
345 1 $num_anns += $self->annotation()->get_num_of_annotations();
346 }
347  
348 # done
349 1 return $num_anns;
350 }
351  
352 =head1 Implementation specific functions - to allow adding
353  
354 =cut
355  
356 =head2 add_Annotation
357  
358 Title : add_Annotation
359 Usage : $self->add_Annotation('reference',$object);
360 $self->add_Annotation($object,'Bio::MyInterface::DiseaseI');
361 $self->add_Annotation($object);
362 $self->add_Annotation('disease',$object,'Bio::MyInterface::DiseaseI');
363 Function: Adds an annotation for a specific key.
364  
365 If the key is omitted, the object to be added must provide a value
366 via its tagname().
367  
368 If the archetype is provided, this and future objects added under
369 that tag have to comply with the archetype and will be rejected
370 otherwise.
371  
372 This implementation will add all Bio::Annotation::SimpleValue
373 objects to the adapted features as tag/value pairs. Caveat: this
374 may potentially result in information loss if a derived object
375 is supplied.
376  
377 Returns : none
378 Args : annotation key ('disease', 'dblink', ...)
379 object to store (must be Bio::AnnotationI compliant)
380 [optional] object archetype to map future storage of object
381 of these types to
382  
383 =cut
384  
385 65 ▶sub add_Annotation{
Subroutine add_Annotation: called CC=16 SCAR=33.8
Pod documented
386 65 my ($self,$key,$object,$archetype) = @_;
387  
388 # if there's no key we use the tagname() as key
389 65 ▶ if(ref($key) && $key->isa("Bio::AnnotationI") &&
Branch: 1 branch
BranchTrueFalseTotal
if (ref $key and $key->isa("Bio::AnnotationI") and not $object && ref $object) 64 1 65
Condition55%5/9
ref $key and $key->isa("Bio::AnnotationI") and not $object && ref $object
!ll&&!rl&&r
1064
ref $key and $key->isa("Bio::AnnotationI")
!ll&&!rl&&r
1064
$object && ref $object
!ll&&!rl&&r
6400
MC/DC25%1/4
ref $key and $key->isa("Bio::AnnotationI") and not $object && ref $object
ref $key $key->isa("Bio::AnnotationI") $object ref $object
Truth table40%2/5
A and B and not(C && D)
A= ref $keyB= $key->isa("Bio::AnnotationI")C= $objectD= ref $object
ABCDresult
0XXX0
10XX0
11110
110X1
11101
390 (! ($object && ref($object)))) {
391 64 ▶ $archetype = $object if $object;
Branch: 1 branch
BranchTrueFalseTotal
if $object 0 64 64
392 64 $object = $key;
393 64 $key = $object->tagname();
394 64 ▶ $key = $key->name() if $key && ref($key); # OntologyTermI
Branch: 1 branch
BranchTrueFalseTotal
if $key and ref $key 0 64 64
Condition33%1/3
$key and ref $key
!ll&&!rl&&r
0640
MC/DC0%0/2
$key and ref $key
$key ref $key
Truth table33%1/3
A and B
A= $keyB= ref $key
ABresult
0X0
100
111
395 64 ▶ $self->throw("Annotation object must have a tagname if key omitted")
Branch: 1 branch
BranchTrueFalseTotal
unless $key 0 64 64
396 unless $key;
397 }
398  
399 65 ▶ if( !defined $object ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $object) 0 65 65
400 0 $self->throw("Must have at least key and object in add_Annotation");
401 }
402  
403 65 ▶ if( ! (ref($object) && $object->isa("Bio::AnnotationI")) ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $object and $object->isa("Bio::AnnotationI")) 0 65 65
Condition33%1/3
ref $object and $object->isa("Bio::AnnotationI")
!ll&&!rl&&r
0065
MC/DC0%0/2
ref $object and $object->isa("Bio::AnnotationI")
ref $object $object->isa("Bio::AnnotationI")
Truth table33%1/3
A and B
A= ref $objectB= $object->isa("Bio::AnnotationI")
ABresult
0X0
100
111
404 0 $self->throw("object must be a Bio::AnnotationI compliant object, otherwise we won't add it!");
405 }
406  
407 # ready to add -- if it's a SimpleValue, we add to the feature's tags,
408 # otherwise we'll add to the annotation collection implementation
409  
410 65 ▶ if($object->isa("Bio::Annotation::SimpleValue") &&
Branch: 1 branch
BranchTrueFalseTotal
if ($object->isa('Bio::Annotation::SimpleValue') and $self->feature->can('add_tag_value')) { } 64 1 65
Condition66%2/3
$object->isa("Bio::Annotation::SimpleValue") and $self->feature->can("add_tag_value")
!ll&&!rl&&r
1064
MC/DC50%1/2
$object->isa("Bio::Annotation::SimpleValue") and $self->feature->can("add_tag_value")
$object->isa("Bio::Annotation::SimpleValue") $self->feature->can("add_tag_value")
Truth table66%2/3
A and B
A= $object->isa("Bio::Annotation::SimpleValue")B= $self->feature->can("add_tag_value")
ABresult
0X0
100
111
411 $self->feature()->can('add_tag_value')) {
412 64 return $self->feature()->add_tag_value($key, $object->value());
413 } else {
414 1 my $anncoll = $self->annotation();
415 1 ▶ if(! $anncoll) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($anncoll) 0 1 1
416 0 $anncoll = Bio::Annotation::Collection->new();
417 0 $self->annotation($anncoll);
418 }
419 1 ▶ if($anncoll->can('add_Annotation')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($anncoll->can("add_Annotation")) 1 0 1
420 1 return $anncoll->add_Annotation($key,$object,$archetype);
421 }
422 0 $self->throw("Annotation implementation does not allow adding!");
423 }
424 }
425  
426 =head2 remove_Annotations
427  
428 Title : remove_Annotations
429 Usage :
430 Function: Remove the annotations for the specified key from this
431 collection.
432  
433 If the key happens to be a tag, then the tag is removed
434 from the feature.
435  
436 Example :
437 Returns : an array Bio::AnnotationI compliant objects which were stored
438 under the given key(s)
439 Args : the key(s) (tag name(s), one or more strings) for which to
440 remove annotations (optional; if none given, flushes all
441 annotations)
442  
443  
444 =cut
445  
446 0 ▶sub remove_Annotations{
Subroutine remove_Annotations: not called CC=7 SCAR=40.3
Pod documented
447 0 my ($self, @keys) = @_;
448  
449 # set to all keys if none are supplied
450 0 ▶ @keys = $self->get_all_annotation_keys() unless @keys;
Branch: 1 branch
BranchTrueFalseTotal
unless @keys 0 0 0
451 # collect existing annotation
452 0 my @anns = $self->get_Annotations(@keys);
453 # flush
454 0 foreach my $key (@keys) {
455 # delete the tag if it is one
456 0 ▶ $self->feature->remove_tag($key) if $self->feature->has_tag($key);
Branch: 1 branch
BranchTrueFalseTotal
if $self->feature->has_tag($key) 0 0 0
457 # and delegate to the annotation implementation
458 0 my $anncoll = $self->annotation();
459 0 ▶ if($anncoll && $anncoll->can('remove_Annotations')) {
Branch: 2 branches
BranchTrueFalseTotal
if ($anncoll and $anncoll->can('remove_Annotations')) { } 0 0 0
elsif ($anncoll) { } 0 0 0
Condition0%0/3
$anncoll and $anncoll->can("remove_Annotations")
!ll&&!rl&&r
000
MC/DC0%0/2
$anncoll and $anncoll->can("remove_Annotations")
$anncoll $anncoll->can("remove_Annotations")
Truth table0%0/3
A and B
A= $anncollB= $anncoll->can("remove_Annotations")
ABresult
0X0
100
111
460 0 $anncoll->remove_Annotations($key);
461 } elsif($anncoll) {
462 0 $self->warn("Annotation bundle implementation ".ref($anncoll).
463 " does not allow remove!");
464 }
465 }
466 0 return @anns;
467 }
468  
469 =head1 Additional methods
470  
471 =cut
472  
473 =head2 tagvalue_object_factory
474  
475 Title : tagvalue_object_factory
476 Usage : $obj->tagval_object_factory($newval)
477 Function: Get/set the object factory to use for creating objects that
478 represent tag/value pairs (e.g.,
479 Bio::Annotation::SimpleValue).
480  
481 The object to be created is expected to follow
482 Bio::Annotation::SimpleValue in terms of supported
483 arguments at creation time, and the methods.
484  
485 Example :
486 Returns : A Bio::Factory::ObjectFactoryI compliant object
487 Args : new value (a Bio::Factory::ObjectFactoryI compliant object,
488 optional)
489  
490  
491 =cut
492  
493 3 ▶sub tagvalue_object_factory{
Subroutine tagvalue_object_factory: called CC=2 SCAR=7.6
Pod documented
494 3 my ($self,$value) = @_;
495 3 ▶ if( defined $value) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value) 0 3 3
496 0 $self->{'tagval_object_factory'} = $value;
497 }
498 3 return $self->{'tagval_object_factory'};
499 }
500  
501 3 1;
« Bio/AlignIO/clustalw.pm ↑ Summary Bio/SearchIO/Writer/HSPTableWriter.pm »