maint: restructure to use Dist::Zilla
[bioperl-live.git] / lib / Bio / Ontology / OntologyI.pm
blob81a0dadfb0962f0ed62d602e2e82a20362037342
2 # BioPerl module for Bio::Ontology::OntologyI
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Hilmar Lapp <hlapp at gmx.net>
8 # Copyright Hilmar Lapp
10 # You may distribute this module under the same terms as perl itself
13 # (c) Hilmar Lapp, hlapp at gmx.net, 2003.
14 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2003.
16 # You may distribute this module under the same terms as perl itself.
17 # Refer to the Perl Artistic License (see the license accompanying this
18 # software package, or see http://www.perl.com/language/misc/Artistic.html)
19 # for the terms under which you may use, modify, and redistribute this module.
21 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
22 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
23 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
26 # POD documentation - main docs before the code
28 =head1 NAME
30 Bio::Ontology::OntologyI - Interface for an ontology implementation
32 =head1 SYNOPSIS
34 # see method documentation
36 =head1 DESCRIPTION
38 This describes the minimal interface an ontology implementation must
39 provide. In essence, it represents a namespace with description on top
40 of the query interface OntologyEngineI.
42 This interface inherits from L<Bio::Ontology::OntologyEngineI>.
44 =head1 FEEDBACK
46 =head2 Mailing Lists
48 User feedback is an integral part of the evolution of this and other
49 Bioperl modules. Send your comments and suggestions preferably to
50 the Bioperl mailing list. Your participation is much appreciated.
52 bioperl-l@bioperl.org - General discussion
53 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
55 =head2 Support
57 Please direct usage questions or support issues to the mailing list:
59 I<bioperl-l@bioperl.org>
61 rather than to the module maintainer directly. Many experienced and
62 reponsive experts will be able look at the problem and quickly
63 address it. Please include a thorough description of the problem
64 with code and data examples if at all possible.
66 =head2 Reporting Bugs
68 Report bugs to the Bioperl bug tracking system to help us keep track
69 of the bugs and their resolution. Bug reports can be submitted via
70 email or the web:
72 https://github.com/bioperl/bioperl-live/issues
74 =head1 AUTHOR - Hilmar Lapp
76 Email hlapp at gmx.net
78 =head1 APPENDIX
80 The rest of the documentation details each of the object methods.
81 Internal methods are usually preceded with a _
83 =cut
86 # Let the code begin...
89 package Bio::Ontology::OntologyI;
90 use strict;
93 use base qw(Bio::Ontology::OntologyEngineI);
95 =head1 Methods defined in this interface.
97 =cut
99 =head2 name
101 Title : name
102 Usage : $obj->name($newval)
103 Function: Get/set the name of this ontology.
104 Example :
105 Returns : value of name (a scalar)
106 Args :
108 =cut
110 sub name{
111 shift->throw_not_implemented();
114 =head2 authority
116 Title : authority
117 Usage : $auth = $obj->authority()
118 Function: Get/set the authority for this ontology, for instance the
119 DNS base for the organization granting the name of the
120 ontology and identifiers for the terms.
122 This attribute is optional and should not generally
123 expected by applications to have been set. It is here to
124 follow the rules for namespaces, which ontologies serve as
125 for terms.
127 Example :
128 Returns : value of authority (a scalar)
129 Args :
131 =cut
133 sub authority{
134 shift->throw_not_implemented();
137 =head2 identifier
139 Title : identifier
140 Usage : $id = $obj->identifier()
141 Function: Get an identifier for this ontology.
143 This is primarily intended for look-up purposes. Clients
144 should not expect the value to be modifiable, and it may
145 not be allowed to set its value from outside. Also, the
146 identifier's uniqueness may only hold within the scope of a
147 particular application's run time, i.e., it may be a memory
148 location.
150 Example :
151 Returns : value of identifier (a scalar)
152 Args :
154 =cut
156 sub identifier{
157 shift->throw_not_implemented();
160 =head2 definition
162 Title : definition
163 Usage : $def = $obj->definition()
164 Function: Get a descriptive definition for this ontology.
165 Example :
166 Returns : value of definition (a scalar)
167 Args :
169 =cut
171 sub definition{
172 shift->throw_not_implemented();
175 =head2 close
177 Title : close
178 Usage :
179 Function: Release any resources this ontology may occupy. In order
180 to efficiently release used memory or file handles, you
181 should call this method once you are finished with an
182 ontology.
184 Example :
185 Returns : TRUE on success and FALSE otherwise
186 Args : none
188 =cut
190 sub close{
191 shift->throw_not_implemented();
194 =head1 Methods inherited from L<Bio::Ontology::OntologyEngineI>
196 Their documentations are copied here for completeness. In most use
197 cases, you will want to access the query methods of an ontology, not
198 just the name and description ...
200 =cut
202 =head2 add_term
204 Title : add_term
205 Usage : add_term(TermI term): TermI
206 Function: Adds TermI object to the ontology engine term store.
208 For ease of use, if the ontology property of the term
209 object was not set, an implementation is encouraged to set
210 it to itself upon adding the term.
212 Example : $oe->add_term($term)
213 Returns : its argument.
214 Args : object of class TermI.
216 =cut
218 =head2 add_relationship
220 Title : add_relationship
221 Usage : add_relationship(RelationshipI relationship): RelationshipI
222 Function: Adds a relationship object to the ontology engine.
223 Example :
224 Returns : Its argument.
225 Args : A RelationshipI object.
227 =cut
229 =head2 get_relationships
231 Title : get_relationships
232 Usage : get_relationships(TermI term): RelationshipI
233 Function: Retrieves all relationship objects from this ontology engine,
234 or all relationships of a term if a term is supplied.
235 Example :
236 Returns : Array of Bio::Ontology::RelationshipI objects
237 Args : None, or a Bio::Ontology::TermI compliant object for which
238 to retrieve the relationships.
240 =cut
242 =head2 get_predicate_terms
244 Title : get_predicate_terms
245 Usage : get_predicate_terms(): TermI[]
246 Function:
247 Example :
248 Returns :
249 Args :
251 =cut
253 =head2 get_child_terms
255 Title : get_child_terms
256 Usage : get_child_terms(TermI term, TermI predicate_terms): TermI
257 Function: Retrieves all child terms of a given term, that satisfy a
258 relationship among those that are specified in the second
259 argument or undef otherwise. get_child_terms is a special
260 case of get_descendant_terms, limiting the search to the
261 direct descendants.
263 Example :
264 Returns : Array of TermI objects.
265 Args : First argument is the term of interest, second is the list
266 of relationship type terms.
268 =cut
270 =head2 get_descendant_terms
272 Title : get_descendant_terms
273 Usage : get_descendant_terms(TermI term, TermI rel_types): TermI
274 Function: Retrieves all descendant terms of a given term, that
275 satisfy a relationship among those that are specified in
276 the second argument or undef otherwise.
277 Example :
278 Returns : Array of TermI objects.
279 Args : First argument is the term of interest, second is the list
280 of relationship type terms.
282 =cut
284 =head2 get_parent_terms
286 Title : get_parent_terms
287 Usage : get_parent_terms(TermI term, TermI predicate_terms): TermI
288 Function: Retrieves all parent terms of a given term, that satisfy a
289 relationship among those that are specified in the second
290 argument or undef otherwise. get_parent_terms is a special
291 case of get_ancestor_terms, limiting the search to the
292 direct ancestors.
294 Example :
295 Returns : Array of TermI objects.
296 Args : First argument is the term of interest, second is the list
297 of relationship type terms.
299 =cut
301 =head2 get_ancestor_terms
303 Title : get_ancestor_terms
304 Usage : get_ancestor_terms(TermI term, TermI predicate_terms): TermI
305 Function: Retrieves all ancestor terms of a given term, that satisfy
306 a relationship among those that are specified in the second
307 argument or undef otherwise.
309 Example :
310 Returns : Array of TermI objects.
311 Args : First argument is the term of interest, second is the list
312 of relationship type terms.
314 =cut
316 =head2 get_leaf_terms
318 Title : get_leaf_terms
319 Usage : get_leaf_terms(): TermI
320 Function: Retrieves all leaf terms from the ontology. Leaf term is a
321 term w/o descendants.
323 Example : @leaf_terms = $obj->get_leaf_terms()
324 Returns : Array of TermI objects.
325 Args :
327 =cut
329 =head2 get_root_terms()
331 Title : get_root_terms
332 Usage : get_root_terms(): TermI
333 Function: Retrieves all root terms from the ontology. Root term is a
334 term w/o descendants.
336 Example : @root_terms = $obj->get_root_terms()
337 Returns : Array of TermI objects.
338 Args :
340 =cut
342 =head2 get_all_terms
344 Title : get_all_terms
345 Usage : get_all_terms: TermI
346 Function: Retrieves all terms from the ontology.
348 We do not mandate an order here in which the terms are
349 returned. In fact, the default implementation will return
350 them in unpredictable order.
352 Example : @terms = $obj->get_all_terms()
353 Returns : Array of TermI objects.
354 Args :
356 =cut
359 =head2 find_terms
361 Title : find_terms
362 Usage : ($term) = $oe->find_terms(-identifier => "SO:0000263");
363 Function: Find term instances matching queries for their attributes.
365 An implementation may not support querying for arbitrary
366 attributes, but can generally be expected to accept
367 -identifier and -name as queries. If both are provided,
368 they are implicitly intersected.
370 Example :
371 Returns : an array of zero or more Bio::Ontology::TermI objects
372 Args : Named parameters. The following parameters should be recognized
373 by any implementation:
375 -identifier query by the given identifier
376 -name query by the given name
378 =cut
380 =head1 Factory for relationships and terms
382 =cut
384 =head2 relationship_factory
386 Title : relationship_factory
387 Usage : $fact = $obj->relationship_factory()
388 Function: Get (and set, if the implementation supports it) the object
389 factory to be used when relationship objects are created by
390 the implementation on-the-fly.
392 Example :
393 Returns : value of relationship_factory (a Bio::Factory::ObjectFactoryI
394 compliant object)
395 Args :
397 =cut
399 sub relationship_factory{
400 return shift->throw_not_implemented();
403 =head2 term_factory
405 Title : term_factory
406 Usage : $fact = $obj->term_factory()
407 Function: Get (and set, if the implementation supports it) the object
408 factory to be used when term objects are created by
409 the implementation on-the-fly.
411 Example :
412 Returns : value of term_factory (a Bio::Factory::ObjectFactoryI
413 compliant object)
414 Args :
416 =cut
418 sub term_factory{
419 return shift->throw_not_implemented();