|
0
|
1 # $Id: AnnotationCollectionI.pm,v 1.9 2002/10/22 07:38:24 lapp Exp $
|
|
|
2
|
|
|
3 #
|
|
|
4 # BioPerl module for Bio::AnnotationCollectionI
|
|
|
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 The trouble about this is we are not that sure what "interesting
|
|
|
44 facts" someone might want to store: the possibility is endless.
|
|
|
45
|
|
|
46 Bioperl's approach is that the "interesting facts" are represented by
|
|
|
47 Bio::AnnotationI objects. The interface Bio::AnnotationI guarentees
|
|
|
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 info read Bio::AnnotationI docs
|
|
|
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, AnnotationCollectionI's are guarentee to maintain a consistent
|
|
|
67 set object values 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 reference Bio::Annotation::Reference
|
|
|
74 comment Bio::Annotation::Comment
|
|
|
75 dblink Bio::Annotation::DBLink
|
|
|
76 gene_name Bio::Annotation::SimpleValue
|
|
|
77 description Bio::Annotation::SimpleValue
|
|
|
78
|
|
|
79 These tags are the implict tags that the SeqIO system needs to round-trip
|
|
|
80 GenBank/EMBL/Swissprot.
|
|
|
81
|
|
|
82 However, you as a user and us collectively as a community can grow the
|
|
|
83 "standard" tag mapping over time and specifically for a particular
|
|
|
84 area.
|
|
|
85
|
|
|
86
|
|
|
87 =head1 FEEDBACK
|
|
|
88
|
|
|
89 =head2 Mailing Lists
|
|
|
90
|
|
|
91 User feedback is an integral part of the evolution of this and other
|
|
|
92 Bioperl modules. Send your comments and suggestions preferably to one
|
|
|
93 of the Bioperl mailing lists. Your participation is much appreciated.
|
|
|
94
|
|
|
95 bioperl-l@bio.perl.org
|
|
|
96
|
|
|
97 =head2 Reporting Bugs
|
|
|
98
|
|
|
99 Report bugs to the Bioperl bug tracking system to help us keep track
|
|
|
100 the bugs and their resolution. Bug reports can be submitted via email
|
|
|
101 or the web:
|
|
|
102
|
|
|
103 bioperl-bugs@bio.perl.org
|
|
|
104 http://bugzilla.bioperl.org/
|
|
|
105
|
|
|
106 =head1 AUTHOR - Ewan Birney
|
|
|
107
|
|
|
108 Email birney@ebi.ac.uk
|
|
|
109
|
|
|
110 Describe contact details here
|
|
|
111
|
|
|
112 =head1 APPENDIX
|
|
|
113
|
|
|
114 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
|
|
|
115
|
|
|
116 =cut
|
|
|
117
|
|
|
118
|
|
|
119 # Let the code begin...
|
|
|
120
|
|
|
121
|
|
|
122 package Bio::AnnotationCollectionI;
|
|
|
123 use vars qw(@ISA);
|
|
|
124 use strict;
|
|
|
125
|
|
|
126 # Interface preamble - inherits from Bio::Root::RootI
|
|
|
127
|
|
|
128 use Bio::Root::RootI;
|
|
|
129
|
|
|
130 @ISA = qw(Bio::Root::RootI);
|
|
|
131
|
|
|
132
|
|
|
133 =head2 get_all_annotation_keys
|
|
|
134
|
|
|
135 Title : get_all_annotation_keys
|
|
|
136 Usage : $ac->get_all_annotation_keys()
|
|
|
137 Function: gives back a list of annotation keys, which are simple text strings
|
|
|
138 Returns : list of strings
|
|
|
139 Args : none
|
|
|
140
|
|
|
141 =cut
|
|
|
142
|
|
|
143 sub get_all_annotation_keys{
|
|
|
144 shift->throw_not_implemented();
|
|
|
145 }
|
|
|
146
|
|
|
147
|
|
|
148 =head2 get_Annotations
|
|
|
149
|
|
|
150 Title : get_Annotations
|
|
|
151 Usage : my @annotations = $collection->get_Annotations('key')
|
|
|
152 Function: Retrieves all the Bio::AnnotationI objects for a specific key
|
|
|
153 Returns : list of Bio::AnnotationI - empty if no objects stored for a key
|
|
|
154 Args : string which is key for annotations
|
|
|
155
|
|
|
156 =cut
|
|
|
157
|
|
|
158 sub get_Annotations{
|
|
|
159 shift->throw_not_implemented();
|
|
|
160 }
|
|
|
161
|
|
|
162 =head2 get_num_of_annotations
|
|
|
163
|
|
|
164 Title : get_num_of_annotations
|
|
|
165 Usage : my $count = $collection->get_num_of_annotations()
|
|
|
166 Function: Returns the count of all annotations stored in this collection
|
|
|
167 Returns : integer
|
|
|
168 Args : none
|
|
|
169
|
|
|
170
|
|
|
171 =cut
|
|
|
172
|
|
|
173 sub get_num_of_annotations{
|
|
|
174 shift->throw_not_implemented();
|
|
|
175 }
|
|
|
176
|
|
|
177 1;
|
