1GO::AnnotationProvider(U3s)er Contributed Perl DocumentatGiOo:n:AnnotationProvider(3)
2
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 GO (Gene Ontology) is a project of the Gene Ontology Consortium
15 (http://www.geneontology.org). The GO project has 3 'aspects' :
16 Biological Process
18 Molecular Function
19 Cellular Component
20 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 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 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 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 nameIsAmbiguous
76 NB: API change:
77 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 Usage:
87 if ($annotationProvider->nameIsAmbiguous($name)){
89 do something useful....or not....
91 }
93 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 B: API change:
100 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 Usage:
110 my @databaseIds = $annotationProvider->databaseIdsForAmbiguousName($name);
112 ambiguousNames
114 This method returns an array of names, which from the annotation source
115 have been deemed to be ambiguous.
116 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 Usage:
123 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 Usage:
135 my $goidsRef = $annotationProvider->goIdsByDatabaseId(databaseId=>$databaseId,
137 aspect=><P|F|C>);
138 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 Usage:
148 my $goidsRef = $annotationProvider->goIdsByStandardName(standardName=>$databaseId,
150 aspect=><P|F|C>);
151 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 NB: API change:
166 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 Usage:
176 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 NB: API change
185 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 Usage:
195 my $standardName = $annotationProvider->standardNameByDatabaseId($databaseId);
197 databaseIdByStandardName
199 This method returns the database id for a standard name.
200 NB: API change
202 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 Usage:
212 my $databaseId = $annotationProvider->databaseIdByStandardName($standardName);
214 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 NB: API change
223 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 Usage:
233 my $databaseId = $annotationProvider->databaseIdByName($name);
235 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 NB: API change
244 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 Usage:
252 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 NB : API change.
261 This is now case insensitive. If you provide abC1, and ABc1 is a
263 standard name, then it will return true.
264 Usage :
266 if ($annotationProvider->nameIsStandardName($name)){
268 # do something
270 }
272 nameIsDatabaseId
274 This method returns a boolean to indicate whether the supplied name is
275 used as a database id.
276 NB : API change.
278 This is now case insensitive. If you provide abC1, and ABc1 is a
280 database id, then it will return true.
281 Usage :
283 if ($annotationProvider->nameIsDatabaseId($name)){
285 # do something
287 }
289 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 NB: API change.
297 This is now case insensitive. If you provide abC1, and ABc1 has
299 annotation, then it will return true.
300 Usage :
302 if ($annotationProvider->nameIsAnnotated(name => $name)){
304 # blah
306 }
308 or:
310 if ($annotationProvider->nameIsAnnotated(name => $name,
312 aspect => $aspect)){
313 # blah
315 }
317
319 databaseName
320 This method returns the name of the annotating authority of the
321 annotations.
322 Usage :
324 my $databaseName = $annotationProvider->databaseName;
326 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 Usage:
334 my $numAnnotatedGenes = $annotationProvider->numAnnotatedGenes;
336 my $numAnnotatedGenes = $annotationProvider->numAnnotatedGenes($aspect);
338 allDatabaseIds
340 This public method returns an array of all the database identifiers
341 Usage:
343 my @databaseIds = $annotationProvider->allDatabaseIds;
345 allStandardNames
347 This public method returns an array of all standard names.
348 Usage:
350 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 Usage:
360 $self->_handleMissingArgument(argument=>'blah');
362
364 Gavin Sherlock, sherlock@genome.stanford.edu
365perl v5.28.0 2006-07-27 GO::AnnotationProvider(3)