lib/Bio/Annotation/OntologyTerm.pm

   1 #
   2 # BioPerl module for Bio::Annotation::OntologyTerm
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Hilmar Lapp <hlapp at gmx.net>
   7 #
   8 # Copyright Hilmar Lapp
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 #
  13 # (c) Hilmar Lapp, hlapp at gmx.net, 2002.
  14 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  15 #
  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.
  20 #
  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.
  24 #
  25
  26 # POD documentation - main docs before the code
  27
  28 =head1 NAME
  29
  30 Bio::Annotation::OntologyTerm - An ontology term adapted to AnnotationI
  31
  32 =head1 SYNOPSIS
  33
  34    use Bio::Annotation::OntologyTerm;
  35    use Bio::Annotation::Collection;
  36    use Bio::Ontology::Term;
  37
  38    my $coll = Bio::Annotation::Collection->new();
  39
  40    # this also implements a tag/value pair, where tag _and_ value are treated
  41    # as ontology terms
  42    my $annterm = Bio::Annotation::OntologyTerm->new(-label => 'ABC1',
  43                                                    -tagname => 'Gene Name');
  44    # ontology terms can be added directly - they implicitly have a tag
  45    $coll->add_Annotation($annterm);
  46
  47    # implementation is by composition - you can get/set the term object
  48    # e.g.
  49    my $term = $annterm->term(); # term is-a Bio::Ontology::TermI
  50    print "ontology term ",$term->name()," (ID ",$term->identifier(),
  51          "), ontology ",$term->ontology()->name(),"\n";
  52    $term = Bio::Ontology::Term->new(-name => 'ABC2',
  53                                     -ontology => 'Gene Name');
  54    $annterm->term($term);
  55
  56 =head1 DESCRIPTION
  57
  58 Ontology term annotation object
  59
  60 =head1 FEEDBACK
  61
  62 =head2 Mailing Lists
  63
  64 User feedback is an integral part of the evolution of this and other
  65 Bioperl modules. Send your comments and suggestions preferably to one
  66 of the Bioperl mailing lists. Your participation is much appreciated.
  67
  68   bioperl-l@bioperl.org                  - General discussion
  69   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  70
  71 =head2 Support
  72
  73 Please direct usage questions or support issues to the mailing list:
  74
  75 I<bioperl-l@bioperl.org>
  76
  77 rather than to the module maintainer directly. Many experienced and
  78 reponsive experts will be able look at the problem and quickly
  79 address it. Please include a thorough description of the problem
  80 with code and data examples if at all possible.
  81
  82 =head2 Reporting Bugs
  83
  84 Report bugs to the Bioperl bug tracking system to help us keep track
  85 the bugs and their resolution.  Bug reports can be submitted via
  86 the web:
  87
  88   https://github.com/bioperl/bioperl-live/issues
  89
  90 =head1 AUTHOR - Hilmar Lapp
  91
  92 Email hlapp at gmx.net
  93
  94
  95 =head1 APPENDIX
  96
  97 The rest of the documentation details each of the object methods.
  98 Internal methods are usually preceded with a _
  99
 100 =cut
 101
 102
 103 # Let the code begin...
 104
 105
 106 package Bio::Annotation::OntologyTerm;
 107 use strict;
 108
 109 # Object preamble - inherits from Bio::Root::Root
 110
 111 use Bio::Ontology::Term;
 112
 113 use base qw(Bio::Root::Root Bio::AnnotationI Bio::Ontology::TermI);
 114
 115 =head2 new
 116
 117  Title   : new
 118  Usage   : my $sv = Bio::Annotation::OntologyTerm->new();
 119  Function: Instantiate a new OntologyTerm object
 120  Returns : Bio::Annotation::OntologyTerm object
 121  Args    : -term => $term to initialize the term data field [optional]
 122            Most named arguments that Bio::Ontology::Term accepts will work
 123            here too. -label is a synonym for -name, -tagname is a synonym for
 124            -ontology.
 125
 126 =cut
 127
 128 sub new{
 129     my ($class,@args) = @_;
 130
 131     my $self = $class->SUPER::new(@args);
 132     my ($term,$name,$label,$identifier,$definition,$ont,$tag) =
 133         $self->_rearrange([qw(TERM
 134                           NAME
 135                           LABEL
 136                           IDENTIFIER
 137                           DEFINITION
 138                           ONTOLOGY
 139                           TAGNAME)],
 140                       @args);
 141     if($term) {
 142         $self->term($term);
 143     } else {
 144         $self->name($name || $label) if $name || $label;
 145         $self->identifier($identifier) if $identifier;
 146         $self->definition($definition) if $definition;
 147     }
 148     $self->ontology($ont || $tag) if $ont || $tag;
 149     return $self;
 150 }
 151
 152
 153 =head1 AnnotationI implementing functions
 154
 155 =cut
 156
 157 =head2 as_text
 158
 159  Title   : as_text
 160  Usage   : my $text = $obj->as_text
 161  Function: Returns a textual representation of the annotation that
 162            this object holds. Presently, it is tag name, name of the
 163            term, and the is_obsolete attribute concatenated togather
 164            with a delimiter (|).
 165
 166  Returns : string
 167  Args    : none
 168
 169
 170 =cut
 171
 172 sub as_text{
 173    my ($self) = @_;
 174
 175    return $self->tagname()."|".$self->name()."|".($self->is_obsolete()||'');
 176 }
 177
 178 =head2 display_text
 179
 180  Title   : display_text
 181  Usage   : my $str = $ann->display_text();
 182  Function: returns a string. Unlike as_text(), this method returns a string
 183            formatted as would be expected for te specific implementation.
 184
 185            One can pass a callback as an argument which allows custom text
 186            generation; the callback is passed the current instance and any text
 187            returned
 188  Example :
 189  Returns : a string
 190  Args    : [optional] callback
 191
 192 =cut
 193
 194 {
 195   my $DEFAULT_CB = sub { $_[0]->identifier || ''};
 196
 197   sub display_text {
 198     my ($self, $cb) = @_;
 199     $cb ||= $DEFAULT_CB;
 200     $self->throw("Callback must be a code reference") if ref $cb ne 'CODE';
 201     return $cb->($self);
 202   }
 203
 204 }
 205
 206 =head2 hash_tree
 207
 208  Title   : hash_tree
 209  Usage   : my $hashtree = $value->hash_tree
 210  Function: For supporting the AnnotationI interface just returns the value
 211            as a hashref with the key 'value' pointing to the value
 212  Returns : hashrf
 213  Args    : none
 214
 215
 216 =cut
 217
 218 sub hash_tree{
 219    my ($self) = @_;
 220
 221    my $h = {};
 222    $h->{'name'} = $self->name();
 223    $h->{'identifier'} = $self->identifier();
 224    $h->{'definition'} = $self->definition();
 225    $h->{'synonyms'} = [$self->get_synonyms()];
 226 }
 227
 228
 229 =head2 tagname
 230
 231  Title   : tagname
 232  Usage   : $obj->tagname($newval)
 233  Function: Get/set the tagname for this annotation value.
 234
 235            Setting this is optional. If set, it obviates the need to provide
 236            a tag to AnnotationCollection when adding this object.
 237
 238            This is aliased to ontology() here.
 239  Example :
 240  Returns : value of tagname (a scalar)
 241  Args    : new value (a scalar, optional)
 242
 243
 244 =cut
 245
 246 sub tagname{
 247     my $self = shift;
 248
 249     return $self->ontology(@_) if @_;
 250     # if in get mode we need to get the name from the ontology
 251     my $ont = $self->ontology();
 252     return ref($ont) ? $ont->name() : $ont;
 253 }
 254
 255 =head1 Methods for Bio::Ontology::TermI compliance
 256
 257 =cut
 258
 259 =head2 term
 260
 261  Title   : term
 262  Usage   : $obj->term($newval)
 263  Function: Get/set the Bio::Ontology::TermI implementing object.
 264
 265            We implement TermI by composition, and this method sets/gets the
 266            object we delegate to.
 267  Example :
 268  Returns : value of term (a Bio::Ontology::TermI compliant object)
 269  Args    : new value (a Bio::Ontology::TermI compliant object, optional)
 270
 271
 272 =cut
 273
 274 sub term{
 275     my ($self,$value) = @_;
 276     if( defined $value) {
 277         $self->{'term'} = $value;
 278     }
 279     if(! exists($self->{'term'})) {
 280         $self->{'term'} = Bio::Ontology::Term->new();
 281     }
 282     return $self->{'term'};
 283 }
 284
 285 =head2 identifier
 286
 287  Title   : identifier
 288  Usage   : $term->identifier( "0003947" );
 289            or
 290            print $term->identifier();
 291  Function: Set/get for the identifier of this Term.
 292  Returns : The identifier [scalar].
 293  Args    : The identifier [scalar] (optional).
 294
 295 =cut
 296
 297 sub identifier {
 298     return shift->term()->identifier(@_);
 299 } # identifier
 300
 301 =head2 name
 302
 303  Title   : name
 304  Usage   : $term->name( "N-acetylgalactosaminyltransferase" );
 305            or
 306            print $term->name();
 307  Function: Set/get for the name of this Term.
 308  Returns : The name [scalar].
 309  Args    : The name [scalar] (optional).
 310
 311 =cut
 312
 313 sub name {
 314     return shift->term()->name(@_);
 315 } # name
 316
 317
 318 =head2 definition
 319
 320  Title   : definition
 321  Usage   : $term->definition( "Catalysis of ..." );
 322            or
 323            print $term->definition();
 324  Function: Set/get for the definition of this Term.
 325  Returns : The definition [scalar].
 326  Args    : The definition [scalar] (optional).
 327
 328 =cut
 329
 330 sub definition {
 331     return shift->term()->definition(@_);
 332 } # definition
 333
 334 =head2 ontology
 335
 336  Title   : ontology
 337  Usage   : $term->ontology( $top );
 338            or
 339            $top = $term->ontology();
 340  Function: Set/get for a relationship between this Term and
 341            another Term (e.g. the top level of the ontology).
 342  Returns : The ontology of this Term [TermI].
 343  Args    : The ontology of this Term [TermI or scalar -- which
 344            becomes the name of the category term] (optional).
 345
 346 =cut
 347
 348 sub ontology {
 349     return shift->term()->ontology(@_);
 350 }
 351
 352 =head2 is_obsolete
 353
 354  Title   : is_obsolete
 355  Usage   : $term->is_obsolete( 1 );
 356            or
 357            if ( $term->is_obsolete() )
 358  Function: Set/get for the obsoleteness of this Term.
 359  Returns : the obsoleteness [0 or 1].
 360  Args    : the obsoleteness [0 or 1] (optional).
 361
 362 =cut
 363
 364 sub is_obsolete {
 365     return shift->term()->is_obsolete(@_);
 366 } # is_obsolete
 367
 368 =head2 comment
 369
 370  Title   : comment
 371  Usage   : $term->comment( "Consider the term ..." );
 372            or
 373            print $term->comment();
 374  Function: Set/get for an arbitrary comment about this Term.
 375  Returns : A comment.
 376  Args    : A comment (optional).
 377
 378 =cut
 379
 380 sub comment {
 381     return shift->term()->comment(@_);
 382 } # comment
 383
 384 =head2 get_synonyms
 385
 386  Title   : get_synonyms()
 387  Usage   : @aliases = $term->get_synonyms();
 388  Function: Returns a list of aliases of this Term.
 389  Returns : A list of aliases [array of [scalar]].
 390  Args    :
 391
 392 =cut
 393
 394 sub get_synonyms {
 395     return shift->term()->get_synonyms(@_);
 396 } # get_synonyms
 397
 398 =head2 add_synonym
 399
 400  Title   : add_synonym
 401  Usage   : $term->add_synonym( @asynonyms );
 402            or
 403            $term->add_synonym( $synonym );
 404  Function: Pushes one or more synonyms into the list of synonyms.
 405  Returns :
 406  Args    : One synonym [scalar] or a list of synonyms [array of [scalar]].
 407
 408 =cut
 409
 410 sub add_synonym {
 411     return shift->term()->add_synonym(@_);
 412 } # add_synonym
 413
 414
 415 =head2 remove_synonyms
 416
 417  Title   : remove_synonyms()
 418  Usage   : $term->remove_synonyms();
 419  Function: Deletes (and returns) the synonyms of this Term.
 420  Returns : A list of synonyms [array of [scalar]].
 421  Args    :
 422
 423 =cut
 424
 425 sub remove_synonyms {
 426     return shift->term()->remove_synonyms(@_);
 427 } # remove_synonyms
 428
 429 =head2 get_dblinks
 430
 431  Title   : get_dblinks()
 432  Usage   : @ds = $term->get_dblinks();
 433  Function: Returns a list of each dblinks of this GO term.
 434  Returns : A list of dblinks [array of [scalars]].
 435  Args    :
 436  Note    : this is deprecated in favor of get_dbxrefs(), which works with strings
 437            or L<Bio::Annotation::DBLink> instances
 438
 439 =cut
 440
 441 sub get_dblinks {
 442     my $self = shift;
 443     $self->deprecated('get_dblinks() is deprecated; use get_dbxrefs()');
 444     return $self->term->get_dbxrefs(@_);
 445 } # get_dblinks
 446
 447 =head2 get_dbxrefs
 448
 449  Title   : get_dbxrefs()
 450  Usage   : @ds = $term->get_dbxrefs();
 451  Function: Returns a list of each dblinks of this GO term.
 452  Returns : A list of dblinks [array of [scalars] or Bio::Annotation::DBLink instances].
 453  Args    :
 454
 455 =cut
 456
 457 sub get_dbxrefs {
 458     return shift->term->get_dbxrefs(@_);
 459 } # get_dblinks
 460
 461 =head2 add_dblink
 462
 463  Title   : add_dblink
 464  Usage   : $term->add_dblink( @dbls );
 465            or
 466            $term->add_dblink( $dbl );
 467  Function: Pushes one or more dblinks
 468            into the list of dblinks.
 469  Returns :
 470  Args    : One  dblink [scalar] or a list of
 471             dblinks [array of [scalars]].
 472  Note    : this is deprecated in favor of add_dbxref(), which works with strings
 473            or L<Bio::Annotation::DBLink> instances
 474
 475 =cut
 476
 477 sub add_dblink {
 478     my $self = shift;
 479     $self->deprecated('add_dblink() is deprecated; use add_dbxref()');
 480     return $self->term->add_dbxref(@_);
 481 } # add_dblink
 482
 483 =head2 add_dbxref
 484
 485  Title   : add_dbxref
 486  Usage   : $term->add_dbxref( @dbls );
 487            or
 488            $term->add_dbxref( $dbl );
 489  Function: Pushes one or more dblinks
 490            into the list of dblinks.
 491  Returns :
 492  Args    :
 493
 494 =cut
 495
 496 sub add_dbxref {
 497     return shift->term->add_dbxref(@_);
 498 }
 499
 500 =head2 remove_dblinks
 501
 502  Title   : remove_dblinks()
 503  Usage   : $term->remove_dblinks();
 504  Function: Deletes (and returns) the definition references of this GO term.
 505  Returns : A list of definition references [array of [scalars]].
 506  Args    :
 507  Note    : this is deprecated in favor of remove_dbxrefs(), which works with strings
 508            or L<Bio::Annotation::DBLink> instances
 509
 510 =cut
 511
 512 sub remove_dblinks {
 513     my $self = shift;
 514     $self->deprecated('remove_dblinks() is deprecated; use remove_dbxrefs()');
 515     return $self->term->remove_dbxrefs(@_);
 516 } # remove_dblinks
 517
 518 =head2 remove_dbxrefs
 519
 520  Title   : remove_dbxrefs()
 521  Usage   : $term->remove_dbxrefs();
 522  Function: Deletes (and returns) the definition references of this GO term.
 523  Returns : A list of definition references [array of [scalars]].
 524  Args    :
 525
 526 =cut
 527
 528 sub remove_dbxrefs {
 529     return shift->term->remove_dbxrefs(@_);
 530 }
 531
 532 =head2 get_secondary_ids
 533
 534  Title   : get_secondary_ids
 535  Usage   : @ids = $term->get_secondary_ids();
 536  Function: Returns a list of secondary identifiers of this Term.
 537
 538            Secondary identifiers mostly originate from merging terms,
 539            or possibly also from splitting terms.
 540
 541  Returns : A list of secondary identifiers [array of [scalar]]
 542  Args    :
 543
 544 =cut
 545
 546 sub get_secondary_ids {
 547     return shift->term->get_secondary_ids(@_);
 548 } # get_secondary_ids
 549
 550
 551 =head2 add_secondary_id
 552
 553  Title   : add_secondary_id
 554  Usage   : $term->add_secondary_id( @ids );
 555            or
 556            $term->add_secondary_id( $id );
 557  Function: Adds one or more secondary identifiers to this term.
 558  Returns :
 559  Args    : One or more secondary identifiers [scalars]
 560
 561 =cut
 562
 563 sub add_secondary_id {
 564     return shift->term->add_secondary_id(@_);
 565 } # add_secondary_id
 566
 567
 568 =head2 remove_secondary_ids
 569
 570  Title   : remove_secondary_ids
 571  Usage   : $term->remove_secondary_ids();
 572  Function: Deletes (and returns) the secondary identifiers of this Term.
 573  Returns : The previous list of secondary identifiers [array of [scalars]]
 574  Args    :
 575
 576 =cut
 577
 578 sub remove_secondary_ids {
 579     return shift->term->remove_secondary_ids(@_);
 580 } # remove_secondary_ids
 581
 582
 583 1;