Bio/Ontology/TermI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Ontology::Term
   4 #
   5 # Cared for by Christian M. Zmasek <czmasek@gnf.org> or <cmzmasek@yahoo.com>
   6 #
   7 # (c) Christian M. Zmasek, czmasek@gnf.org, 2002.
   8 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
   9 #
  10 # You may distribute this module under the same terms as perl itself.
  11 # Refer to the Perl Artistic License (see the license accompanying this
  12 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  13 # for the terms under which you may use, modify, and redistribute this module.
  14 #
  15 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  16 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  17 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  18 #
  19 # You may distribute this module under the same terms as perl itself
  20
  21 # POD documentation - main docs before the code
  22
  23 =head1 NAME
  24
  25 Bio::Ontology::TermI - interface for ontology terms
  26
  27 =head1 SYNOPSIS
  28
  29   #get Bio::Ontology::TermI somehow.
  30
  31   print $term->identifier(), "\n";
  32   print $term->name(), "\n";
  33   print $term->definition(), "\n";
  34   print $term->is_obsolete(), "\n";
  35   print $term->comment(), "\n";
  36
  37   foreach my $synonym ( $term->get_synonyms() ) {
  38       print $synonym, "\n";
  39   }
  40
  41
  42 =head1 DESCRIPTION
  43
  44 This is "dumb" interface for ontology terms providing basic methods
  45 (it provides no functionality related to graphs).
  46
  47 =head1 FEEDBACK
  48
  49 =head2 Mailing Lists
  50
  51 User feedback is an integral part of the evolution of this and other
  52 Bioperl modules. Send your comments and suggestions preferably to one
  53 of the Bioperl mailing lists.  Your participation is much appreciated.
  54
  55   bioperl-l@bioperl.org                  - General discussion
  56   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  57
  58 =head2 Reporting Bugs
  59
  60 Report bugs to the Bioperl bug tracking system to help us keep track
  61 the bugs and their resolution.  Bug reports can be submitted via
  62 the web:
  63
  64   http://bugzilla.open-bio.org/
  65
  66 =head1 AUTHOR
  67
  68 Christian M. Zmasek
  69
  70 Email: czmasek@gnf.org  or  cmzmasek@yahoo.com
  71
  72 WWW:   http://www.genetics.wustl.edu/eddy/people/zmasek/
  73
  74 Address:
  75
  76   Genomics Institute of the Novartis Research Foundation
  77   10675 John Jay Hopkins Drive
  78   San Diego, CA 92121
  79
  80 =head1 APPENDIX
  81
  82 The rest of the documentation details each of the object
  83 methods.
  84
  85 =cut
  86
  87
  88 # Let the code begin...
  89
  90 package Bio::Ontology::TermI;
  91 use strict;
  92
  93 use base qw(Bio::Root::RootI);
  94
  95
  96
  97 =head2 identifier
  98
  99  Title   : identifier
 100  Usage   : $term->identifier( "0003947" );
 101            or
 102            print $term->identifier();
 103  Function: Set/get for the identifier of this Term.
 104  Returns : The identifier [scalar].
 105  Args    : The identifier [scalar] (optional).
 106
 107 =cut
 108
 109 sub identifier {
 110     shift->throw_not_implemented();
 111 } # identifier
 112
 113
 114
 115
 116 =head2 name
 117
 118  Title   : name
 119  Usage   : $term->name( "N-acetylgalactosaminyltransferase" );
 120            or
 121            print $term->name();
 122  Function: Set/get for the name of this Term.
 123  Returns : The name [scalar].
 124  Args    : The name [scalar] (optional).
 125
 126 =cut
 127
 128 sub name {
 129     shift->throw_not_implemented();
 130 } # name
 131
 132
 133
 134
 135
 136 =head2 definition
 137
 138  Title   : definition
 139  Usage   : $term->definition( "Catalysis of ..." );
 140            or
 141            print $term->definition();
 142  Function: Set/get for the definition of this Term.
 143  Returns : The definition [scalar].
 144  Args    : The definition [scalar] (optional).
 145
 146 =cut
 147
 148 sub definition {
 149     shift->throw_not_implemented();
 150 } # definition
 151
 152
 153
 154 =head2 ontology
 155
 156  Title   : ontology
 157  Usage   : $ont = $term->ontology();
 158            or
 159            $term->ontology( $ont );
 160  Function: Get the ontology this term is in.
 161
 162            An implementation may not permit the value of this
 163            attribute to be changed once it is set, since that may have
 164            serious consequences (note that with the ontology in hand
 165            you can query for all related terms etc).
 166
 167            Note for implementors: you will almost certainly have to
 168            take special precaution in order not to create cyclical
 169            references in memory.
 170
 171  Returns : The ontology of this Term as a Bio::Ontology::OntologyI
 172            implementing object.
 173  Args    : On set, the  ontology of this Term as a Bio::Ontology::OntologyI
 174            implementing object or a string representing its name.
 175
 176 See L<Bio::Ontology::OntologyI>.
 177
 178 =cut
 179
 180 sub ontology {
 181     shift->throw_not_implemented();
 182 } # ontology
 183
 184
 185
 186 =head2 version
 187
 188  Title   : version
 189  Usage   : $term->version( "1.00" );
 190            or
 191            print $term->version();
 192  Function: Set/get for version information.
 193  Returns : The version [scalar].
 194  Args    : The version [scalar] (optional).
 195
 196 =cut
 197
 198 sub version {
 199     shift->throw_not_implemented();
 200 } # version
 201
 202
 203
 204
 205 =head2 is_obsolete
 206
 207  Title   : is_obsolete
 208  Usage   : $term->is_obsolete( 1 );
 209            or
 210            if ( $term->is_obsolete() )
 211  Function: Set/get for the obsoleteness of this Term.
 212  Returns : the obsoleteness [0 or 1].
 213  Args    : the obsoleteness [0 or 1] (optional).
 214
 215 =cut
 216
 217 sub is_obsolete {
 218     shift->throw_not_implemented();
 219 } # is_obsolete
 220
 221
 222
 223 =head2 comment
 224
 225  Title   : comment
 226  Usage   : $term->comment( "Consider the term ..." );
 227            or
 228            print $term->comment();
 229  Function: Set/get for an arbitrary comment about this Term.
 230  Returns : A comment.
 231  Args    : A comment (optional).
 232
 233 =cut
 234
 235 sub comment {
 236     shift->throw_not_implemented();
 237 } # comment
 238
 239
 240
 241
 242 =head2 get_synonyms
 243
 244  Title   : get_synonyms
 245  Usage   : @aliases = $term->get_synonyms();
 246  Function: Returns a list of aliases of this Term.
 247
 248            If an implementor of this interface permits modification of
 249            this array property, the class should define at least
 250            methods add_synonym() and remove_synonyms(), with obvious
 251            functionality.
 252
 253  Returns : A list of aliases [array of [scalar]].
 254  Args    :
 255
 256 =cut
 257
 258 sub get_synonyms {
 259     shift->throw_not_implemented();
 260 } # get_synonyms
 261
 262 =head2 get_dblinks
 263
 264  Title   : get_dblinks()
 265  Usage   : @ds = $term->get_dblinks();
 266  Function: Returns a list of each dblink of this term.
 267
 268            If an implementor of this interface permits modification of
 269            this array property, the class should define at least
 270            methods add_dblink() and remove_dblinks(), with obvious
 271            functionality.
 272
 273  Returns : A list of dblinks [array of [scalars]].
 274  Args    :
 275  Note    : This has been deprecated in favor of get_dbxrefs()
 276
 277 =cut
 278
 279 sub get_dblinks {
 280     shift->throw('get_dblinks() is deprecated, use get_dbxrefs() instead');
 281 } # get_dblinks
 282
 283 =head2 get_dbxrefs
 284
 285  Title   : get_dbxrefs()
 286  Usage   : @ds = $term->get_dbxrefs();
 287  Function: Returns a list of each link for this term.
 288
 289            If an implementor of this interface permits modification of
 290            this array property, the class should define at least
 291            methods add_dbxref() and remove_dbxrefs(), with obvious
 292            functionality.
 293
 294  Returns : A list of dblinks.  This can return a mixed 'bag' of scalars and
 295            L<Bio::Annotation::DBLink> instances, or specific subgroups
 296            can be returned based on passed arguments
 297  Args    : implementation-specific
 298
 299 =cut
 300
 301 sub get_dbxrefs {
 302     shift->throw_not_implemented();
 303 } # get_dblinks
 304
 305 =head2 get_secondary_ids
 306
 307  Title   : get_secondary_ids
 308  Usage   : @ids = $term->get_secondary_ids();
 309  Function: Returns a list of secondary identifiers of this Term.
 310
 311            Secondary identifiers mostly originate from merging terms,
 312            or possibly also from splitting terms.
 313
 314            If an implementor of this interface permits modification of
 315            this array property, the class should define at least
 316            methods add_secondary_id() and remove_secondary_ids(), with
 317            obvious functionality.
 318
 319  Returns : A list of secondary identifiers [array of [scalar]]
 320  Args    :
 321
 322 =cut
 323
 324 sub get_secondary_ids {
 325     shift->throw_not_implemented();
 326 } # get_secondary_ids
 327
 328
 329 =head1  Deprecated methods
 330
 331 Used for looking up the methods that supercedes them.
 332
 333 =cut
 334
 335 =head2 category
 336
 337  Title   : category
 338  Usage   :
 339  Function: This method is deprecated. Use ontology() instead. We provide
 340            an implementation here that preserves backwards compatibility,
 341            but if you do not have legacy code using it you should not be
 342            calling this method.
 343  Example :
 344  Returns :
 345  Args    :
 346
 347 =cut
 348
 349 sub category {
 350     my $self = shift;
 351
 352     $self->warn("TermI::category is deprecated and being phased out. ".
 353                 "Use TermI::ontology instead.");
 354
 355     # called in set mode?
 356     if(@_) {
 357         # yes; what is incompatible with ontology() is if we were given
 358         # a TermI object
 359         my $arg = shift;
 360         $arg = $arg->name() if ref($arg) && $arg->isa("Bio::Ontology::TermI");
 361         return $self->ontology($arg,@_);
 362     } else {
 363         # No, called in get mode. This is always incompatible with ontology()
 364         # since category is supposed to return a TermI.
 365         my $ont = $self->ontology();
 366         my $term;
 367         if(defined($ont)) {
 368             $term = Bio::Ontology::Term->new(-name => $ont->name(),
 369                                              -identifier =>$ont->identifier());
 370         }
 371         return $term;
 372     }
 373 } # category
 374
 375 1;