Bio/Ontology/TermI.pm

   1 #
   2 # BioPerl module for Bio::Ontology::Term
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Christian M. Zmasek <czmasek-at-burnham.org> or <cmzmasek@yahoo.com>
   7 #
   8 # (c) Christian M. Zmasek, czmasek-at-burnham.org, 2002.
   9 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  10 #
  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.
  15 #
  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.
  19 #
  20 # You may distribute this module under the same terms as perl itself
  21
  22 # POD documentation - main docs before the code
  23
  24 =head1 NAME
  25
  26 Bio::Ontology::TermI - interface for ontology terms
  27
  28 =head1 SYNOPSIS
  29
  30   #get Bio::Ontology::TermI somehow.
  31
  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";
  37
  38   foreach my $synonym ( $term->get_synonyms() ) {
  39       print $synonym, "\n";
  40   }
  41
  42
  43 =head1 DESCRIPTION
  44
  45 This is "dumb" interface for ontology terms providing basic methods
  46 (it provides no functionality related to graphs).
  47
  48 =head1 FEEDBACK
  49
  50 =head2 Mailing Lists
  51
  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.
  55
  56   bioperl-l@bioperl.org                  - General discussion
  57   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  58
  59 =head2 Support
  60
  61 Please direct usage questions or support issues to the mailing list:
  62
  63 I<bioperl-l@bioperl.org>
  64
  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.
  69
  70 =head2 Reporting Bugs
  71
  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:
  75
  76   https://github.com/bioperl/bioperl-live/issues
  77
  78 =head1 AUTHOR
  79
  80 Christian M. Zmasek
  81
  82 Email: czmasek-at-burnham.org  or  cmzmasek@yahoo.com
  83
  84 WWW:   http://monochrome-effect.net/
  85
  86 Address:
  87
  88   Genomics Institute of the Novartis Research Foundation
  89   10675 John Jay Hopkins Drive
  90   San Diego, CA 92121
  91
  92 =head1 APPENDIX
  93
  94 The rest of the documentation details each of the object
  95 methods.
  96
  97 =cut
  98
  99
 100 # Let the code begin...
 101
 102 package Bio::Ontology::TermI;
 103 use strict;
 104
 105 use base qw(Bio::Root::RootI);
 106
 107
 108
 109 =head2 identifier
 110
 111  Title   : identifier
 112  Usage   : $term->identifier( "0003947" );
 113            or
 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).
 118
 119 =cut
 120
 121 sub identifier {
 122     shift->throw_not_implemented();
 123 } # identifier
 124
 125
 126
 127
 128 =head2 name
 129
 130  Title   : name
 131  Usage   : $term->name( "N-acetylgalactosaminyltransferase" );
 132            or
 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).
 137
 138 =cut
 139
 140 sub name {
 141     shift->throw_not_implemented();
 142 } # name
 143
 144
 145
 146
 147
 148 =head2 definition
 149
 150  Title   : definition
 151  Usage   : $term->definition( "Catalysis of ..." );
 152            or
 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).
 157
 158 =cut
 159
 160 sub definition {
 161     shift->throw_not_implemented();
 162 } # definition
 163
 164
 165
 166 =head2 ontology
 167
 168  Title   : ontology
 169  Usage   : $ont = $term->ontology();
 170            or
 171            $term->ontology( $ont );
 172  Function: Get the ontology this term is in.
 173
 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).
 178
 179            Note for implementors: you will almost certainly have to
 180            take special precaution in order not to create cyclical
 181            references in memory.
 182
 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.
 187
 188 See L<Bio::Ontology::OntologyI>.
 189
 190 =cut
 191
 192 sub ontology {
 193     shift->throw_not_implemented();
 194 } # ontology
 195
 196
 197
 198 =head2 version
 199
 200  Title   : version
 201  Usage   : $term->version( "1.00" );
 202            or
 203            print $term->version();
 204  Function: Set/get for version information.
 205  Returns : The version [scalar].
 206  Args    : The version [scalar] (optional).
 207
 208 =cut
 209
 210 sub version {
 211     shift->throw_not_implemented();
 212 } # version
 213
 214
 215
 216
 217 =head2 is_obsolete
 218
 219  Title   : is_obsolete
 220  Usage   : $term->is_obsolete( 1 );
 221            or
 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).
 226
 227 =cut
 228
 229 sub is_obsolete {
 230     shift->throw_not_implemented();
 231 } # is_obsolete
 232
 233
 234
 235 =head2 comment
 236
 237  Title   : comment
 238  Usage   : $term->comment( "Consider the term ..." );
 239            or
 240            print $term->comment();
 241  Function: Set/get for an arbitrary comment about this Term.
 242  Returns : A comment.
 243  Args    : A comment (optional).
 244
 245 =cut
 246
 247 sub comment {
 248     shift->throw_not_implemented();
 249 } # comment
 250
 251
 252
 253
 254 =head2 get_synonyms
 255
 256  Title   : get_synonyms
 257  Usage   : @aliases = $term->get_synonyms();
 258  Function: Returns a list of aliases of this Term.
 259
 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.
 264
 265  Returns : A list of aliases [array of [scalar]].
 266  Args    :
 267
 268 =cut
 269
 270 sub get_synonyms {
 271     shift->throw_not_implemented();
 272 } # get_synonyms
 273
 274 =head2 get_dblinks
 275
 276  Title   : get_dblinks()
 277  Usage   : @ds = $term->get_dblinks();
 278  Function: Returns a list of each dblink of this term.
 279
 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.
 284
 285  Returns : A list of dblinks [array of [scalars]].
 286  Args    :
 287  Note    : This has been deprecated in favor of get_dbxrefs()
 288
 289 =cut
 290
 291 sub get_dblinks {
 292     shift->throw('get_dblinks() is deprecated, use get_dbxrefs() instead');
 293 } # get_dblinks
 294
 295 =head2 get_dbxrefs
 296
 297  Title   : get_dbxrefs()
 298  Usage   : @ds = $term->get_dbxrefs();
 299  Function: Returns a list of each link for this term.
 300
 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.
 305
 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
 310
 311 =cut
 312
 313 sub get_dbxrefs {
 314     shift->throw_not_implemented();
 315 } # get_dblinks
 316
 317 =head2 get_secondary_ids
 318
 319  Title   : get_secondary_ids
 320  Usage   : @ids = $term->get_secondary_ids();
 321  Function: Returns a list of secondary identifiers of this Term.
 322
 323            Secondary identifiers mostly originate from merging terms,
 324            or possibly also from splitting terms.
 325
 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.
 330
 331  Returns : A list of secondary identifiers [array of [scalar]]
 332  Args    :
 333
 334 =cut
 335
 336 sub get_secondary_ids {
 337     shift->throw_not_implemented();
 338 } # get_secondary_ids
 339
 340
 341 =head1  Deprecated methods
 342
 343 Used for looking up the methods that supercedes them.
 344
 345 =cut
 346
 347 =head2 category
 348
 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    :
 358
 359 =cut
 360
 361 sub category {
 362     my $self = shift;
 363
 364     $self->warn("TermI::category is deprecated and being phased out. ".
 365                 "Use TermI::ontology instead.");
 366
 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());
 382         }
 383         return $term;
 384     }
 385 } # category
 386
 387 1;