| 1 | # | ||
| 2 | # BioPerl module for Bio::AnnotationI | ||
| 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::AnnotationI - Annotation interface | ||
| 17 | |||
| 18 | =head1 SYNOPSIS | ||
| 19 | |||
| 20 | # generally you get AnnotationI's from AnnotationCollectionI's | ||
| 21 | |||
| 22 | foreach $key ( $ac->get_all_annotation_keys() ) { | ||
| 23 | @values = $ac->get_Annotations($key); | ||
| 24 | foreach $value ( @values ) { | ||
| 25 | # value is an Bio::AnnotationI, and defines a "as_text" method | ||
| 26 | print "Annotation ",$key," stringified value ",$value->as_text,"\n"; | ||
| 27 | # you can also use a generic hash_tree method for getting | ||
| 28 | # stuff out say into XML format | ||
| 29 | $hash_tree = $value->hash_tree(); | ||
| 30 | } | ||
| 31 | } | ||
| 32 | |||
| 33 | =head1 DESCRIPTION | ||
| 34 | |||
| 35 | Interface all annotations must support. There are two things that each | ||
| 36 | annotation has to support. | ||
| 37 | |||
| 38 | $annotation->as_text() | ||
| 39 | |||
| 40 | Annotations have to support an "as_text" method. This should be a | ||
| 41 | single text string, without newlines representing the annotation, | ||
| 42 | mainly for human readability. It is not aimed at being able to | ||
| 43 | store/represent the annotation. | ||
| 44 | |||
| 45 | The second method allows annotations to at least attempt to represent | ||
| 46 | themselves as pure data for storage/display/whatever. The method | ||
| 47 | hash_tree should return an anonymous hash with "XML-like" formatting: | ||
| 48 | |||
| 49 | $hash = $annotation->hash_tree(); | ||
| 50 | |||
| 51 | The formatting is as follows. | ||
| 52 | |||
| 53 | (1) For each key in the hash, if the value is a reference'd array - | ||
| 54 | |||
| 55 | (2) For each element of the array if the value is a object - | ||
| 56 | Assume the object has the method "hash_tree"; | ||
| 57 | (3) else if the value is a reference to a hash | ||
| 58 | Recurse again from point (1) | ||
| 59 | (4) else | ||
| 60 | Assume the value is a scalar, and handle it directly as text | ||
| 61 | (5) else (if not an array) apply rules 2,3 and 4 to value | ||
| 62 | |||
| 63 | The XML path in tags is represented by the keys taken in the | ||
| 64 | hashes. When arrays are encountered they are all present in the path | ||
| 65 | level of this tag | ||
| 66 | |||
| 67 | This is a pretty "natural" representation of an object tree in an XML | ||
| 68 | style, without forcing everything to inherit off some super-generic | ||
| 69 | interface for representing things in the hash. | ||
| 70 | |||
| 71 | =head1 FEEDBACK | ||
| 72 | |||
| 73 | =head2 Mailing Lists | ||
| 74 | |||
| 75 | User feedback is an integral part of the evolution of this | ||
| 76 | and other Bioperl modules. Send your comments and suggestions preferably | ||
| 77 | to one of the Bioperl mailing lists. | ||
| 78 | Your participation is much appreciated. | ||
| 79 | |||
| 80 | bioperl-l@bioperl.org | ||
| 81 | |||
| 82 | =head2 Support | ||
| 83 | |||
| 84 | Please direct usage questions or support issues to the mailing list: | ||
| 85 | |||
| 86 | I<bioperl-l@bioperl.org> | ||
| 87 | |||
| 88 | rather than to the module maintainer directly. Many experienced and | ||
| 89 | reponsive experts will be able look at the problem and quickly | ||
| 90 | address it. Please include a thorough description of the problem | ||
| 91 | with code and data examples if at all possible. | ||
| 92 | |||
| 93 | =head2 Reporting Bugs | ||
| 94 | |||
| 95 | Report bugs to the Bioperl bug tracking system to help us keep track | ||
| 96 | the bugs and their resolution. Bug reports can be submitted via the | ||
| 97 | web: | ||
| 98 | |||
| 99 | https://github.com/bioperl/bioperl-live/issues | ||
| 100 | |||
| 101 | =head1 AUTHOR - Ewan Birney | ||
| 102 | |||
| 103 | Email birney@ebi.ac.uk | ||
| 104 | |||
| 105 | =head1 APPENDIX | ||
| 106 | |||
| 107 | The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ | ||
| 108 | |||
| 109 | =cut | ||
| 110 | |||
| 111 | #' | ||
| 112 | # Let the code begin... | ||
| 113 | |||
| 114 | |||
| 115 | package Bio::AnnotationI; | ||
| 116 | 346 | $Bio::AnnotationI::VERSION = '1.7.8'; | |
| 117 | 346 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 118 | |||
| 119 | # Object preamble - inherits from Bio::Root::Root | ||
| 120 | |||
| 121 | 346 | ▶ | use base qw(Bio::Root::RootI); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 122 | |||
| 123 | =head2 as_text | ||
| 124 | |||
| 125 | Title : as_text | ||
| 126 | Usage : | ||
| 127 | Function: single text string, without newlines representing the | ||
| 128 | annotation, mainly for human readability. It is not aimed | ||
| 129 | at being able to store/represent the annotation. | ||
| 130 | Example : | ||
| 131 | Returns : a string | ||
| 132 | Args : none | ||
| 133 | |||
| 134 | |||
| 135 | =cut | ||
| 136 | |||
| 137 | 0 | ▶ | sub as_text{ |
|
Subroutine
as_text: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 138 | 0 | shift->throw_not_implemented(); | |
| 139 | } | ||
| 140 | |||
| 141 | =head2 display_text | ||
| 142 | |||
| 143 | Title : display_text | ||
| 144 | Usage : my $str = $ann->display_text(); | ||
| 145 | Function: returns a string. Unlike as_text(), this method returns a string | ||
| 146 | formatted as would be expected for the specific implementation. | ||
| 147 | |||
| 148 | Implementations should allow passing a callback as an argument which | ||
| 149 | allows custom text generation; the callback will be passed the | ||
| 150 | current implementation. | ||
| 151 | |||
| 152 | Note that this is meant to be used as a simple representation | ||
| 153 | of the annotation data but probably shouldn't be used in cases | ||
| 154 | where more complex comparisons are needed or where data is | ||
| 155 | stored. | ||
| 156 | Example : | ||
| 157 | Returns : a string | ||
| 158 | Args : [optional] callback | ||
| 159 | |||
| 160 | =cut | ||
| 161 | |||
| 162 | 0 | ▶ | sub display_text { |
|
Subroutine
display_text: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 163 | 0 | shift->throw_not_implemented(); | |
| 164 | } | ||
| 165 | |||
| 166 | =head2 hash_tree | ||
| 167 | |||
| 168 | Title : hash_tree | ||
| 169 | Usage : | ||
| 170 | Function: should return an anonymous hash with "XML-like" formatting | ||
| 171 | Example : | ||
| 172 | Returns : a hash reference | ||
| 173 | Args : none | ||
| 174 | |||
| 175 | =cut | ||
| 176 | |||
| 177 | 0 | ▶ | sub hash_tree{ |
|
Subroutine
hash_tree: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 178 | 0 | shift->throw_not_implemented(); | |
| 179 | } | ||
| 180 | |||
| 181 | =head2 tagname | ||
| 182 | |||
| 183 | Title : tagname | ||
| 184 | Usage : $obj->tagname($newval) | ||
| 185 | Function: Get/set the tagname for this annotation value. | ||
| 186 | |||
| 187 | Setting this is optional. If set, it obviates the need to | ||
| 188 | provide a tag to Bio::AnnotationCollectionI when adding | ||
| 189 | this object. When obtaining an AnnotationI object from the | ||
| 190 | collection, the collection will set the value to the tag | ||
| 191 | under which it was stored unless the object has a tag | ||
| 192 | stored already. | ||
| 193 | |||
| 194 | Example : | ||
| 195 | Returns : value of tagname (a scalar) | ||
| 196 | Args : new value (a scalar, optional) | ||
| 197 | |||
| 198 | |||
| 199 | =cut | ||
| 200 | |||
| 201 | 0 | ▶ | sub tagname{ |
|
Subroutine
tagname: not called CC=1 SCAR=6.9
Pod
documented
| |||
| 202 | 0 | shift->throw_not_implemented(); | |
| 203 | } | ||
| 204 | |||
| 205 | 346 | 1; | |