|
0
|
1 # $Id: AnnotationI.pm,v 1.7 2002/10/22 07:38:24 lapp Exp $
|
|
|
2
|
|
|
3 #
|
|
|
4 # BioPerl module for Bio::AnnotationI
|
|
|
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
|
|
|
34 =head1 DESCRIPTION
|
|
|
35
|
|
|
36 Interface all annotations must support. There are two things that each
|
|
|
37 annotation has to support.
|
|
|
38
|
|
|
39 $annotation->as_text()
|
|
|
40
|
|
|
41 Annotations have to support an "as_text" method. This should be a
|
|
|
42 single text string, without newlines representing the annotation,
|
|
|
43 mainly for human readability. It is not aimed at being able to
|
|
|
44 store/represent the annotation.
|
|
|
45
|
|
|
46 The second method allows annotations to at least attempt to represent
|
|
|
47 themselves as pure data for storage/display/whatever. The method
|
|
|
48 hash_tree
|
|
|
49
|
|
|
50 $hash = $annotation->hash_tree();
|
|
|
51
|
|
|
52 should return an anonymous hash with "XML-like" formatting. The
|
|
|
53 formatting is as follows.
|
|
|
54
|
|
|
55 (1) For each key in the hash, if the value is a reference'd array -
|
|
|
56
|
|
|
57 (2) For each element of the array if the value is a object -
|
|
|
58 Assumme the object has the method "hash_tree";
|
|
|
59 (3) else if the value is a referene to a hash
|
|
|
60 Recurse again from point (1)
|
|
|
61 (4) else
|
|
|
62 Assumme the value is a scalar, and handle it directly as text
|
|
|
63
|
|
|
64 (5) else (if not an array) apply rules 2,3 and 4 to value
|
|
|
65
|
|
|
66 The XML path in tags is represented by the keys taken in the
|
|
|
67 hashes. When arrays are encountered they are all present in the path
|
|
|
68 level of this tag
|
|
|
69
|
|
|
70 This is a pretty "natural" representation of an object tree in an XML
|
|
|
71 style, without forcing everything to inheriet off some super-generic
|
|
|
72 interface for representing things in the hash.
|
|
|
73
|
|
|
74 =head1 FEEDBACK
|
|
|
75
|
|
|
76 =head2 Mailing Lists
|
|
|
77
|
|
|
78 User feedback is an integral part of the evolution of this
|
|
|
79 and other Bioperl modules. Send your comments and suggestions preferably
|
|
|
80 to one of the Bioperl mailing lists.
|
|
|
81 Your participation is much appreciated.
|
|
|
82
|
|
|
83 bioperl-l@bio.perl.org
|
|
|
84
|
|
|
85 =head2 Reporting Bugs
|
|
|
86
|
|
|
87 Report bugs to the Bioperl bug tracking system to help us keep track
|
|
|
88 the bugs and their resolution.
|
|
|
89 Bug reports can be submitted via email or the web:
|
|
|
90
|
|
|
91 bioperl-bugs@bio.perl.org
|
|
|
92 http://bugzilla.bioperl.org/
|
|
|
93
|
|
|
94 =head1 AUTHOR - Ewan Birney
|
|
|
95
|
|
|
96 Email birney@ebi.ac.uk
|
|
|
97
|
|
|
98 Describe contact details here
|
|
|
99
|
|
|
100 =head1 APPENDIX
|
|
|
101
|
|
|
102 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
|
|
|
103
|
|
|
104 =cut
|
|
|
105
|
|
|
106 #'
|
|
|
107 # Let the code begin...
|
|
|
108
|
|
|
109
|
|
|
110 package Bio::AnnotationI;
|
|
|
111 use vars qw(@ISA);
|
|
|
112 use strict;
|
|
|
113
|
|
|
114 # Object preamble - inherits from Bio::Root::Root
|
|
|
115
|
|
|
116 use Bio::Root::RootI;
|
|
|
117
|
|
|
118
|
|
|
119 @ISA = qw(Bio::Root::RootI);
|
|
|
120
|
|
|
121
|
|
|
122 =head2 as_text
|
|
|
123
|
|
|
124 Title : as_text
|
|
|
125 Usage :
|
|
|
126 Function: single text string, without newlines representing the
|
|
|
127 annotation, mainly for human readability. It is not aimed
|
|
|
128 at being able to store/represent the annotation.
|
|
|
129 Example :
|
|
|
130 Returns : a string
|
|
|
131 Args : none
|
|
|
132
|
|
|
133
|
|
|
134 =cut
|
|
|
135
|
|
|
136 sub as_text{
|
|
|
137 shift->throw_not_implemented();
|
|
|
138 }
|
|
|
139
|
|
|
140 =head2 hash_tree
|
|
|
141
|
|
|
142 Title : hash_tree
|
|
|
143 Usage :
|
|
|
144 Function: should return an anonymous hash with "XML-like" formatting
|
|
|
145 Example :
|
|
|
146 Returns : a hash reference
|
|
|
147 Args : none
|
|
|
148
|
|
|
149
|
|
|
150 =cut
|
|
|
151
|
|
|
152 sub hash_tree{
|
|
|
153 shift->throw_not_implemented();
|
|
|
154 }
|
|
|
155
|
|
|
156 =head2 tagname
|
|
|
157
|
|
|
158 Title : tagname
|
|
|
159 Usage : $obj->tagname($newval)
|
|
|
160 Function: Get/set the tagname for this annotation value.
|
|
|
161
|
|
|
162 Setting this is optional. If set, it obviates the need to
|
|
|
163 provide a tag to Bio::AnnotationCollectionI when adding
|
|
|
164 this object. When obtaining an AnnotationI object from the
|
|
|
165 collection, the collection will set the value to the tag
|
|
|
166 under which it was stored unless the object has a tag
|
|
|
167 stored already.
|
|
|
168
|
|
|
169 Example :
|
|
|
170 Returns : value of tagname (a scalar)
|
|
|
171 Args : new value (a scalar, optional)
|
|
|
172
|
|
|
173
|
|
|
174 =cut
|
|
|
175
|
|
|
176 sub tagname{
|
|
|
177 shift->throw_not_implemented();
|
|
|
178 }
|
|
|
179
|
|
|
180 1;
|
