maint: fix multiple typos identified by lintian
[bioperl-live.git] / Bio / Ontology / TermI.pm
blobcc5338a070133eadc67d2e97f1aae6db0f2b1f12
2 # BioPerl module for Bio::Ontology::Term
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Christian M. Zmasek <czmasek-at-burnham.org> or <cmzmasek@yahoo.com>
8 # (c) Christian M. Zmasek, czmasek-at-burnham.org, 2002.
9 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
11 # You may distribute this module under the same terms as perl itself.
12 # Refer to the Perl Artistic License (see the license accompanying this
13 # software package, or see http://www.perl.com/language/misc/Artistic.html)
14 # for the terms under which you may use, modify, and redistribute this module.
16 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
17 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
18 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
20 # You may distribute this module under the same terms as perl itself
22 # POD documentation - main docs before the code
24 =head1 NAME
26 Bio::Ontology::TermI - interface for ontology terms
28 =head1 SYNOPSIS
30 #get Bio::Ontology::TermI somehow.
32 print $term->identifier(), "\n";
33 print $term->name(), "\n";
34 print $term->definition(), "\n";
35 print $term->is_obsolete(), "\n";
36 print $term->comment(), "\n";
38 foreach my $synonym ( $term->get_synonyms() ) {
39 print $synonym, "\n";
43 =head1 DESCRIPTION
45 This is "dumb" interface for ontology terms providing basic methods
46 (it provides no functionality related to graphs).
48 =head1 FEEDBACK
50 =head2 Mailing Lists
52 User feedback is an integral part of the evolution of this and other
53 Bioperl modules. Send your comments and suggestions preferably to one
54 of the Bioperl mailing lists. Your participation is much appreciated.
56 bioperl-l@bioperl.org - General discussion
57 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
59 =head2 Support
61 Please direct usage questions or support issues to the mailing list:
63 I<bioperl-l@bioperl.org>
65 rather than to the module maintainer directly. Many experienced and
66 reponsive experts will be able look at the problem and quickly
67 address it. Please include a thorough description of the problem
68 with code and data examples if at all possible.
70 =head2 Reporting Bugs
72 Report bugs to the Bioperl bug tracking system to help us keep track
73 the bugs and their resolution. Bug reports can be submitted via
74 the web:
76 https://github.com/bioperl/bioperl-live/issues
78 =head1 AUTHOR
80 Christian M. Zmasek
82 Email: czmasek-at-burnham.org or cmzmasek@yahoo.com
84 WWW: http://monochrome-effect.net/
86 Address:
88 Genomics Institute of the Novartis Research Foundation
89 10675 John Jay Hopkins Drive
90 San Diego, CA 92121
92 =head1 APPENDIX
94 The rest of the documentation details each of the object
95 methods.
97 =cut
100 # Let the code begin...
102 package Bio::Ontology::TermI;
103 use strict;
105 use base qw(Bio::Root::RootI);
109 =head2 identifier
111 Title : identifier
112 Usage : $term->identifier( "0003947" );
114 print $term->identifier();
115 Function: Set/get for the identifier of this Term.
116 Returns : The identifier [scalar].
117 Args : The identifier [scalar] (optional).
119 =cut
121 sub identifier {
122 shift->throw_not_implemented();
123 } # identifier
128 =head2 name
130 Title : name
131 Usage : $term->name( "N-acetylgalactosaminyltransferase" );
133 print $term->name();
134 Function: Set/get for the name of this Term.
135 Returns : The name [scalar].
136 Args : The name [scalar] (optional).
138 =cut
140 sub name {
141 shift->throw_not_implemented();
142 } # name
148 =head2 definition
150 Title : definition
151 Usage : $term->definition( "Catalysis of ..." );
153 print $term->definition();
154 Function: Set/get for the definition of this Term.
155 Returns : The definition [scalar].
156 Args : The definition [scalar] (optional).
158 =cut
160 sub definition {
161 shift->throw_not_implemented();
162 } # definition
166 =head2 ontology
168 Title : ontology
169 Usage : $ont = $term->ontology();
171 $term->ontology( $ont );
172 Function: Get the ontology this term is in.
174 An implementation may not permit the value of this
175 attribute to be changed once it is set, since that may have
176 serious consequences (note that with the ontology in hand
177 you can query for all related terms etc).
179 Note for implementors: you will almost certainly have to
180 take special precaution in order not to create cyclical
181 references in memory.
183 Returns : The ontology of this Term as a Bio::Ontology::OntologyI
184 implementing object.
185 Args : On set, the ontology of this Term as a Bio::Ontology::OntologyI
186 implementing object or a string representing its name.
188 See L<Bio::Ontology::OntologyI>.
190 =cut
192 sub ontology {
193 shift->throw_not_implemented();
194 } # ontology
198 =head2 version
200 Title : version
201 Usage : $term->version( "1.00" );
203 print $term->version();
204 Function: Set/get for version information.
205 Returns : The version [scalar].
206 Args : The version [scalar] (optional).
208 =cut
210 sub version {
211 shift->throw_not_implemented();
212 } # version
217 =head2 is_obsolete
219 Title : is_obsolete
220 Usage : $term->is_obsolete( 1 );
222 if ( $term->is_obsolete() )
223 Function: Set/get for the obsoleteness of this Term.
224 Returns : the obsoleteness [0 or 1].
225 Args : the obsoleteness [0 or 1] (optional).
227 =cut
229 sub is_obsolete {
230 shift->throw_not_implemented();
231 } # is_obsolete
235 =head2 comment
237 Title : comment
238 Usage : $term->comment( "Consider the term ..." );
240 print $term->comment();
241 Function: Set/get for an arbitrary comment about this Term.
242 Returns : A comment.
243 Args : A comment (optional).
245 =cut
247 sub comment {
248 shift->throw_not_implemented();
249 } # comment
254 =head2 get_synonyms
256 Title : get_synonyms
257 Usage : @aliases = $term->get_synonyms();
258 Function: Returns a list of aliases of this Term.
260 If an implementor of this interface permits modification of
261 this array property, the class should define at least
262 methods add_synonym() and remove_synonyms(), with obvious
263 functionality.
265 Returns : A list of aliases [array of [scalar]].
266 Args :
268 =cut
270 sub get_synonyms {
271 shift->throw_not_implemented();
272 } # get_synonyms
274 =head2 get_dblinks
276 Title : get_dblinks()
277 Usage : @ds = $term->get_dblinks();
278 Function: Returns a list of each dblink of this term.
280 If an implementor of this interface permits modification of
281 this array property, the class should define at least
282 methods add_dblink() and remove_dblinks(), with obvious
283 functionality.
285 Returns : A list of dblinks [array of [scalars]].
286 Args :
287 Note : This has been deprecated in favor of get_dbxrefs()
289 =cut
291 sub get_dblinks {
292 shift->throw('get_dblinks() is deprecated, use get_dbxrefs() instead');
293 } # get_dblinks
295 =head2 get_dbxrefs
297 Title : get_dbxrefs()
298 Usage : @ds = $term->get_dbxrefs();
299 Function: Returns a list of each link for this term.
301 If an implementor of this interface permits modification of
302 this array property, the class should define at least
303 methods add_dbxref() and remove_dbxrefs(), with obvious
304 functionality.
306 Returns : A list of dblinks. This can return a mixed 'bag' of scalars and
307 L<Bio::Annotation::DBLink> instances, or specific subgroups
308 can be returned based on passed arguments
309 Args : implementation-specific
311 =cut
313 sub get_dbxrefs {
314 shift->throw_not_implemented();
315 } # get_dblinks
317 =head2 get_secondary_ids
319 Title : get_secondary_ids
320 Usage : @ids = $term->get_secondary_ids();
321 Function: Returns a list of secondary identifiers of this Term.
323 Secondary identifiers mostly originate from merging terms,
324 or possibly also from splitting terms.
326 If an implementor of this interface permits modification of
327 this array property, the class should define at least
328 methods add_secondary_id() and remove_secondary_ids(), with
329 obvious functionality.
331 Returns : A list of secondary identifiers [array of [scalar]]
332 Args :
334 =cut
336 sub get_secondary_ids {
337 shift->throw_not_implemented();
338 } # get_secondary_ids
341 =head1 Deprecated methods
343 Used for looking up the methods that supersedes them.
345 =cut
347 =head2 category
349 Title : category
350 Usage :
351 Function: This method is deprecated. Use ontology() instead. We provide
352 an implementation here that preserves backwards compatibility,
353 but if you do not have legacy code using it you should not be
354 calling this method.
355 Example :
356 Returns :
357 Args :
359 =cut
361 sub category {
362 my $self = shift;
364 $self->warn("TermI::category is deprecated and being phased out. ".
365 "Use TermI::ontology instead.");
367 # called in set mode?
368 if(@_) {
369 # yes; what is incompatible with ontology() is if we were given
370 # a TermI object
371 my $arg = shift;
372 $arg = $arg->name() if ref($arg) && $arg->isa("Bio::Ontology::TermI");
373 return $self->ontology($arg,@_);
374 } else {
375 # No, called in get mode. This is always incompatible with ontology()
376 # since category is supposed to return a TermI.
377 my $ont = $self->ontology();
378 my $term;
379 if(defined($ont)) {
380 $term = Bio::Ontology::Term->new(-name => $ont->name(),
381 -identifier =>$ont->identifier());
383 return $term;
385 } # category