1GO::AnnotationProvider(U3s)er Contributed Perl DocumentatGiOo:n:AnnotationProvider(3)
2
3
4
6 GO::AnnotationProvider - abstract base class defining interface for how
7 Annotation information should be provided
8
10 GO::AnnotationProvider is an interface that defines an API that should
11 be implemented by specific subclasses, which may read GO annotation
12 from databases, flatfiles, XML files etc.
13
14 GO (Gene Ontology) is a project of the Gene Ontology Consortium
15 (http://www.geneontology.org). The GO project has 3 'aspects' :
16
17 Biological Process
18 Molecular Function
19 Cellular Component
20
21 When a method requires the client to refer to an aspect, it is simply
22 by a shorthand, namely P, F and C, respectively.
23
24 In GO associations, annotated entities may be identified by many
25 different names. Firstly, they should have a database identifier,
26 which should be unique for an entity. Secondly, they should have a
27 standard name. Standard names should be unique among standard names,
28 but it is possible that a standard name of one entity may be used as an
29 alias of another. An entity may have many aliases, and an alias may be
30 used for many entities. Hence, a name (drawn from databaseIds,
31 standard names, and aliases) may be ambiguous in the entity to which it
32 refers. This is an important concept for clients of concrete
33 subclasses to take into consideration, so that unexpected results are
34 avoided.
35
37 Currently this interface dictates that clients can retrieve GOIDs that
38 have been used to annotated genes. In future, this interface is likely
39 to change, such that instead of GOIDs, GO::Annotation objects are
40 instead returned, which will be richer in the terms of information they
41 can give about a given annotation. Such objects would contain a
42 GO::AnnotatedGene object, one or more GO::Reference objects, and an
43 evidence code. The retrieval of annotations for a given database id
44 could then be extended to allow filtering by evidence codes, to either
45 include or exclude certain codes.
46
47 This interface also currently only allows retrieval of GOIDs for genes,
48 in future, it will be extended such that the genes can be retrieved by
49 GOID.
50
52 Because this is an abstract class, there is no constructor. A
53 constructor must be implemented by concrete subclasses.
54
56 All of these public instance methods must be implemented by concrete
57 subclasses.
58
60 Because there are many names by which an annotated entity may be
61 referred to, that are non-unique, this interface defines a set of
62 methods for determining whether a name is ambiguous, and to what
63 database identifiers such ambiguous names may refer.
64
65 Note, that the AnnotationProvider subclasses should now be case
66 insensitive, though there are some caveats. For instance, you can use
67 'cdc6' to retrieve data for CDC6. However, This if gene has been
68 referred to as abc1, and another referred to as ABC1, then these are
69 treated as different, and unambiguous. However, the text 'Abc1' would
70 be considered ambiguous, because it could refer to either. On the
71 other hand, if a single gene is referred to as XYZ1 and xyz1, and no
72 other genes have that name (in any casing), then Xyz1 would still be
73 considered unambiguous.
74
75 nameIsAmbiguous
76 NB: API change:
77
78 nameIsAmbiguous is now case insensitive - that is, if there is a name
79 that is used twice using different casing, that will be treated as
80 ambiguous. Previous versions would have not treated these as
81 ambiguous. In the case that a name is provided in a certain casing,
82 which was encountered only once, then it will be treated as
83 unambiguous. This is the price of wanting a case insensitive
84 annotation provider...
85
86 Usage:
87
88 if ($annotationProvider->nameIsAmbiguous($name)){
89
90 do something useful....or not....
91
92 }
93
94 databaseIdsForAmbiguousName
95 This public method returns an array of database identifiers for an
96 ambiguous name. If the name is not ambiguous, an empty list will be
97 returned.
98
99 B: API change:
100
101 databaseIdsForAmbiguousName is now case insensitive - that is, if there
102 is a name that is used twice using different casing, that will be
103 treated as ambiguous. Previous versions would have not treated these
104 as ambiguous. However, if the name provided is of the exact casing as
105 a name that appeared only once with that exact casing, then it is
106 treated as unambiguous. This is the price of wanting a case insensitive
107 annotation provider...
108
109 Usage:
110
111 my @databaseIds = $annotationProvider->databaseIdsForAmbiguousName($name);
112
113 ambiguousNames
114 This method returns an array of names, which from the annotation source
115 have been deemed to be ambiguous.
116
117 Note - even though this is now case insensitive, if something is called
118 both BLAH1 and blah1, we would not deem either of these to be
119 ambiguous. However, if it appeared as blah1 twice, referring to two
120 different genes, then blah1 would be ambiguous.
121
122 Usage:
123
124 my @ambiguousNames = $annotationProvider->ambiguousNames;
125
127 goIdsByDatabaseId
128 This public method returns a reference to an array of GOIDs that are
129 associated with the supplied databaseId for a specific aspect. If no
130 annotations are associated with that databaseId in that aspect, then a
131 reference to an empty array will be returned. If the databaseId is not
132 recognized, then undef will be returned.
133
134 Usage:
135
136 my $goidsRef = $annotationProvider->goIdsByDatabaseId(databaseId=>$databaseId,
137 aspect=><P|F|C>);
138
139 goIdsByStandardName
140 This public method returns a reference to an array of GOIDs that are
141 associated with the supplied standardName for a specific aspect. If no
142 annotations are associated with the entity with that standard name in
143 that aspect, then a a reference to an empty list will be returned. If
144 the supplied name is not used as a standard name, then undef will be
145 returned.
146
147 Usage:
148
149 my $goidsRef = $annotationProvider->goIdsByStandardName(standardName=>$databaseId,
150 aspect=><P|F|C>);
151
152 goIdsByName
153 This public method returns a reference to an array of GO IDs that are
154 associated with the supplied name for a specific aspect. If there are
155 no GO associations for the entity corresponding to the supplied name in
156 the provided aspect, then a reference to an empty list will be
157 returned. If the supplied name does not correspond to any entity, then
158 undef will be returned. Because the name can be any of the databaseId,
159 the standard name, or any of the aliases, it is possible that the name
160 might be ambiguous. Clients of this object should first test whether
161 the name they are using is ambiguous, using the nameIsAmbiguous()
162 method, and handle it accordingly. If an ambiguous name is supplied,
163 then it will die.
164
165 NB: API change:
166
167 goIdsByName is now case insensitive - that is, if there is a name that
168 is used twice using different casing, that will be treated as
169 ambiguous. Previous versions would have not treated these as
170 ambiguous. This is the price of wanting a case insensitive annotation
171 provider. In the event that a name is provided that is ambiguous
172 because of case, if it matches exactly the case of one of the possible
173 matches, it will be treated unambiguously.
174
175 Usage:
176
177 my $goidsRef = $annotationProvider->goIdsByName(name=>$name,
178 aspect=><P|F|C>);
179
181 standardNameByDatabaseId
182 This method returns the standard name for a database id.
183
184 NB: API change
185
186 standardNameByDatabaseId is now case insensitive - that is, if there is
187 a databaseId that is used twice (or more) using different casing, it
188 will be treated as ambiguous. Previous versions would have not treated
189 these as ambiguous. This is the price of wanting a case insensitive
190 annotation provider. In the event that a name is provided that is
191 ambiguous because of case, if it matches exactly the case of one of the
192 possible matches, it will be treated unambiguously.
193
194 Usage:
195
196 my $standardName = $annotationProvider->standardNameByDatabaseId($databaseId);
197
198 databaseIdByStandardName
199 This method returns the database id for a standard name.
200
201 NB: API change
202
203 databaseIdByStandardName is now case insensitive - that is, if there is
204 a standard name that is used twice (or more) using different casing, it
205 will be treated as ambiguous. Previous versions would have not treated
206 these as ambiguous. This is the price of wanting a case insensitive
207 annotation provider. In the event that a name is provided that is
208 ambiguous because of case, if it matches exactly the case of one of the
209 possible matches, it will be treated unambiguously.
210
211 Usage:
212
213 my $databaseId = $annotationProvider->databaseIdByStandardName($standardName);
214
215 databaseIdByName
216 This method returns the database id for any identifier for a gene (e.g.
217 by databaseId itself, by standard name, or by alias). If the used name
218 is ambiguous, then the program will die. Thus clients should call the
219 nameIsAmbiguous() method, prior to using this method. If the name does
220 not map to any databaseId, then undef will be returned.
221
222 NB: API change
223
224 databaseIdByName is now case insensitive - that is, if there is a name
225 that is used twice using different casing, that will be treated as
226 ambiguous. Previous versions would have not treated these as
227 ambiguous. This is the price of wanting a case insensitive annotation
228 provider. In the event that a name is provided that is ambiguous
229 because of case, if it matches exactly the case of one of the possible
230 matches, it will be treated unambiguously.
231
232 Usage:
233
234 my $databaseId = $annotationProvider->databaseIdByName($name);
235
236 standardNameByName
237 This public method returns the standard name for the the gene specified
238 by the given name. Because a name may be ambiguous, the
239 nameIsAmbiguous() method should be called first. If an ambiguous name
240 is supplied, then it will die with an appropriate error message. If
241 the name does not map to a standard name, then undef will be returned.
242
243 NB: API change
244
245 standardNameByName is now case insensitive - that is, if there is a
246 name that is used twice using different casing, that will be treated as
247 ambiguous. Previous versions would have not treated these as
248 ambiguous. This is the price of wanting a case insensitive annotation
249 provider.
250
251 Usage:
252
253 my $standardName = $annotationProvider->standardNameByName($name);
254
256 nameIsStandardName
257 This method returns a boolean to indicate whether the supplied name is
258 used as a standard name.
259
260 NB : API change.
261
262 This is now case insensitive. If you provide abC1, and ABc1 is a
263 standard name, then it will return true.
264
265 Usage :
266
267 if ($annotationProvider->nameIsStandardName($name)){
268
269 # do something
270
271 }
272
273 nameIsDatabaseId
274 This method returns a boolean to indicate whether the supplied name is
275 used as a database id.
276
277 NB : API change.
278
279 This is now case insensitive. If you provide abC1, and ABc1 is a
280 database id, then it will return true.
281
282 Usage :
283
284 if ($annotationProvider->nameIsDatabaseId($name)){
285
286 # do something
287
288 }
289
290 nameIsAnnotated
291 This method returns a boolean to indicate whether the supplied name has
292 any annotations, either when considered as a databaseId, a
293 standardName, or an alias. If an aspect is also supplied, then it
294 indicates whether that name has any annotations in that aspect only.
295
296 NB: API change.
297
298 This is now case insensitive. If you provide abC1, and ABc1 has
299 annotation, then it will return true.
300
301 Usage :
302
303 if ($annotationProvider->nameIsAnnotated(name => $name)){
304
305 # blah
306
307 }
308
309 or:
310
311 if ($annotationProvider->nameIsAnnotated(name => $name,
312 aspect => $aspect)){
313
314 # blah
315
316 }
317
319 databaseName
320 This method returns the name of the annotating authority of the
321 annotations.
322
323 Usage :
324
325 my $databaseName = $annotationProvider->databaseName;
326
327 numAnnotatedGenes
328 This method returns the number of entities in the annotation file that
329 have annotations in the supplied aspect. If no aspect is provided,
330 then it will return the number of genes with an annotation in at least
331 one aspect of GO.
332
333 Usage:
334
335 my $numAnnotatedGenes = $annotationProvider->numAnnotatedGenes;
336
337 my $numAnnotatedGenes = $annotationProvider->numAnnotatedGenes($aspect);
338
339 allDatabaseIds
340 This public method returns an array of all the database identifiers
341
342 Usage:
343
344 my @databaseIds = $annotationProvider->allDatabaseIds;
345
346 allStandardNames
347 This public method returns an array of all standard names.
348
349 Usage:
350
351 my @standardNames = $annotationProvider->allStandardNames;
352
354 _handleMissingArgument
355 This protected method simply provides a simple way for concrete
356 subclasses to deal with missing arguments from method calls. It will
357 die with an appropriate error message.
358
359 Usage:
360
361 $self->_handleMissingArgument(argument=>'blah');
362
364 Gavin Sherlock, sherlock@genome.stanford.edu
365
366
367
368perl v5.28.0 2006-07-27 GO::AnnotationProvider(3)