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 use Carp;
 110
 111 # Object preamble - inherits from Bio::Root::Root
 112
 113 use Bio::Ontology::Term;
 114
 115 use base qw(Bio::Root::Root Bio::AnnotationI Bio::Ontology::TermI);
 116
 117 =head2 new
 118
 119  Title   : new
 120  Usage   : my $sv = Bio::Annotation::OntologyTerm->new();
 121  Function: Instantiate a new OntologyTerm object
 122  Returns : Bio::Annotation::OntologyTerm object
 123  Args    : -term => $term to initialize the term data field [optional]
 124            Most named arguments that Bio::Ontology::Term accepts will work
 125            here too. -label is a synonym for -name, -tagname is a synonym for
 126            -ontology.
 127
 128 =cut
 129
 130 sub new{
 131     my ($class,@args) = @_;
 132
 133     my $self = $class->SUPER::new(@args);
 134     my ($term,$name,$label,$identifier,$definition,$ont,$tag) =
 135         $self->_rearrange([qw(TERM
 136                           NAME
 137                           LABEL
 138                           IDENTIFIER
 139                           DEFINITION
 140                           ONTOLOGY
 141                           TAGNAME)],
 142                       @args);
 143     if($term) {
 144         $self->term($term);
 145     } else {
 146         $self->name($name || $label) if $name || $label;
 147         $self->identifier($identifier) if $identifier;
 148         $self->definition($definition) if $definition;
 149     }
 150     $self->ontology($ont || $tag) if $ont || $tag;
 151     return $self;
 152 }
 153
 154
 155 =head1 AnnotationI implementing functions
 156
 157 =cut
 158
 159 =head2 as_text
 160
 161  Title   : as_text
 162  Usage   : my $text = $obj->as_text
 163  Function: Returns a textual representation of the annotation that
 164            this object holds. Presently, it is tag name, name of the
 165            term, and the is_obsolete attribute concatenated togather
 166            with a delimiter (|).
 167
 168  Returns : string
 169  Args    : none
 170
 171
 172 =cut
 173
 174 sub as_text{
 175    my ($self) = @_;
 176
 177    return $self->tagname()."|".$self->name()."|".($self->is_obsolete()||'');
 178 }
 179
 180 =head2 display_text
 181
 182  Title   : display_text
 183  Usage   : my $str = $ann->display_text();
 184  Function: returns a string. Unlike as_text(), this method returns a string
 185            formatted as would be expected for te specific implementation.
 186
 187            One can pass a callback as an argument which allows custom text
 188            generation; the callback is passed the current instance and any text
 189            returned
 190  Example :
 191  Returns : a string
 192  Args    : [optional] callback
 193
 194 =cut
 195
 196 {
 197   my $DEFAULT_CB = sub { $_[0]->identifier || ''};
 198
 199   sub display_text {
 200     my ($self, $cb) = @_;
 201     $cb ||= $DEFAULT_CB;
 202     $self->throw("Callback must be a code reference") if ref $cb ne 'CODE';
 203     return $cb->($self);
 204   }
 205
 206 }
 207
 208 =head2 hash_tree
 209
 210  Title   : hash_tree
 211  Usage   : my $hashtree = $value->hash_tree
 212  Function: For supporting the AnnotationI interface just returns the value
 213            as a hashref with the key 'value' pointing to the value
 214  Returns : hashrf
 215  Args    : none
 216
 217
 218 =cut
 219
 220 sub hash_tree{
 221    my ($self) = @_;
 222
 223    my $h = {};
 224    $h->{'name'} = $self->name();
 225    $h->{'identifier'} = $self->identifier();
 226    $h->{'definition'} = $self->definition();
 227    $h->{'synonyms'} = [$self->get_synonyms()];
 228 }
 229
 230
 231 =head2 tagname
 232
 233  Title   : tagname
 234  Usage   : $obj->tagname($newval)
 235  Function: Get/set the tagname for this annotation value.
 236
 237            Setting this is optional. If set, it obviates the need to provide
 238            a tag to AnnotationCollection when adding this object.
 239
 240            This is aliased to ontology() here.
 241  Example :
 242  Returns : value of tagname (a scalar)
 243  Args    : new value (a scalar, optional)
 244
 245
 246 =cut
 247
 248 sub tagname{
 249     my $self = shift;
 250
 251     return $self->ontology(@_) if @_;
 252     # if in get mode we need to get the name from the ontology
 253     my $ont = $self->ontology();
 254     return ref($ont) ? $ont->name() : $ont;
 255 }
 256
 257 =head1 Methods for Bio::Ontology::TermI compliance
 258
 259 =cut
 260
 261 =head2 term
 262
 263  Title   : term
 264  Usage   : $obj->term($newval)
 265  Function: Get/set the Bio::Ontology::TermI implementing object.
 266
 267            We implement TermI by composition, and this method sets/gets the
 268            object we delegate to.
 269  Example :
 270  Returns : value of term (a Bio::Ontology::TermI compliant object)
 271  Args    : new value (a Bio::Ontology::TermI compliant object, optional)
 272
 273
 274 =cut
 275
 276 sub term{
 277     my ($self,$value) = @_;
 278     if( defined $value) {
 279         $self->{'term'} = $value;
 280     }
 281     if(! exists($self->{'term'})) {
 282         $self->{'term'} = Bio::Ontology::Term->new();
 283     }
 284     return $self->{'term'};
 285 }
 286
 287 =head2 identifier
 288
 289  Title   : identifier
 290  Usage   : $term->identifier( "0003947" );
 291            or
 292            print $term->identifier();
 293  Function: Set/get for the identifier of this Term.
 294  Returns : The identifier [scalar].
 295  Args    : The identifier [scalar] (optional).
 296
 297 =cut
 298
 299 sub identifier {
 300     return shift->term()->identifier(@_);
 301 } # identifier
 302
 303 =head2 name
 304
 305  Title   : name
 306  Usage   : $term->name( "N-acetylgalactosaminyltransferase" );
 307            or
 308            print $term->name();
 309  Function: Set/get for the name of this Term.
 310  Returns : The name [scalar].
 311  Args    : The name [scalar] (optional).
 312
 313 =cut
 314
 315 sub name {
 316     return shift->term()->name(@_);
 317 } # name
 318
 319
 320 =head2 definition
 321
 322  Title   : definition
 323  Usage   : $term->definition( "Catalysis of ..." );
 324            or
 325            print $term->definition();
 326  Function: Set/get for the definition of this Term.
 327  Returns : The definition [scalar].
 328  Args    : The definition [scalar] (optional).
 329
 330 =cut
 331
 332 sub definition {
 333     return shift->term()->definition(@_);
 334 } # definition
 335
 336 =head2 ontology
 337
 338  Title   : ontology
 339  Usage   : $term->ontology( $top );
 340            or
 341            $top = $term->ontology();
 342  Function: Set/get for a relationship between this Term and
 343            another Term (e.g. the top level of the ontology).
 344  Returns : The ontology of this Term [TermI].
 345  Args    : The ontology of this Term [TermI or scalar -- which
 346            becomes the name of the category term] (optional).
 347
 348 =cut
 349
 350 sub ontology {
 351     return shift->term()->ontology(@_);
 352 }
 353
 354 =head2 is_obsolete
 355
 356  Title   : is_obsolete
 357  Usage   : $term->is_obsolete( 1 );
 358            or
 359            if ( $term->is_obsolete() )
 360  Function: Set/get for the obsoleteness of this Term.
 361  Returns : the obsoleteness [0 or 1].
 362  Args    : the obsoleteness [0 or 1] (optional).
 363
 364 =cut
 365
 366 sub is_obsolete {
 367     return shift->term()->is_obsolete(@_);
 368 } # is_obsolete
 369
 370 =head2 comment
 371
 372  Title   : comment
 373  Usage   : $term->comment( "Consider the term ..." );
 374            or
 375            print $term->comment();
 376  Function: Set/get for an arbitrary comment about this Term.
 377  Returns : A comment.
 378  Args    : A comment (optional).
 379
 380 =cut
 381
 382 sub comment {
 383     return shift->term()->comment(@_);
 384 } # comment
 385
 386 =head2 get_synonyms
 387
 388  Title   : get_synonyms()
 389  Usage   : @aliases = $term->get_synonyms();
 390  Function: Returns a list of aliases of this Term.
 391  Returns : A list of aliases [array of [scalar]].
 392  Args    :
 393
 394 =cut
 395
 396 sub get_synonyms {
 397     return shift->term()->get_synonyms(@_);
 398 } # get_synonyms
 399
 400 =head2 add_synonym
 401
 402  Title   : add_synonym
 403  Usage   : $term->add_synonym( @asynonyms );
 404            or
 405            $term->add_synonym( $synonym );
 406  Function: Pushes one or more synonyms into the list of synonyms.
 407  Returns :
 408  Args    : One synonym [scalar] or a list of synonyms [array of [scalar]].
 409
 410 =cut
 411
 412 sub add_synonym {
 413     return shift->term()->add_synonym(@_);
 414 } # add_synonym
 415
 416
 417 =head2 remove_synonyms
 418
 419  Title   : remove_synonyms()
 420  Usage   : $term->remove_synonyms();
 421  Function: Deletes (and returns) the synonyms of this Term.
 422  Returns : A list of synonyms [array of [scalar]].
 423  Args    :
 424
 425 =cut
 426
 427 sub remove_synonyms {
 428     return shift->term()->remove_synonyms(@_);
 429 } # remove_synonyms
 430
 431 =head2 get_dblinks
 432
 433  Title   : get_dblinks()
 434  Usage   : @ds = $term->get_dblinks();
 435  Function: Returns a list of each dblinks of this GO term.
 436  Returns : A list of dblinks [array of [scalars]].
 437  Args    :
 438  Note    : this is deprecated in favor of get_dbxrefs(), which works with strings
 439            or L<Bio::Annotation::DBLink> instances
 440
 441 =cut
 442
 443 sub get_dblinks {
 444     my $self = shift;
 445     Carp::carp('get_dblinks() is deprecated; use get_dbxrefs()');
 446     return $self->term->get_dbxrefs(@_);
 447 } # get_dblinks
 448
 449 =head2 get_dbxrefs
 450
 451  Title   : get_dbxrefs()
 452  Usage   : @ds = $term->get_dbxrefs();
 453  Function: Returns a list of each dblinks of this GO term.
 454  Returns : A list of dblinks [array of [scalars] or Bio::Annotation::DBLink instances].
 455  Args    :
 456
 457 =cut
 458
 459 sub get_dbxrefs {
 460     return shift->term->get_dbxrefs(@_);
 461 } # get_dblinks
 462
 463 =head2 add_dblink
 464
 465  Title   : add_dblink
 466  Usage   : $term->add_dblink( @dbls );
 467            or
 468            $term->add_dblink( $dbl );
 469  Function: Pushes one or more dblinks
 470            into the list of dblinks.
 471  Returns :
 472  Args    : One  dblink [scalar] or a list of
 473             dblinks [array of [scalars]].
 474  Note    : this is deprecated in favor of add_dbxref(), which works with strings
 475            or L<Bio::Annotation::DBLink> instances
 476
 477 =cut
 478
 479 sub add_dblink {
 480     my $self = shift;
 481     Carp::carp('add_dblink() is deprecated; use add_dbxref()');
 482     return $self->term->add_dbxref(@_);
 483 } # add_dblink
 484
 485 =head2 add_dbxref
 486
 487  Title   : add_dbxref
 488  Usage   : $term->add_dbxref( @dbls );
 489            or
 490            $term->add_dbxref( $dbl );
 491  Function: Pushes one or more dblinks
 492            into the list of dblinks.
 493  Returns :
 494  Args    :
 495
 496 =cut
 497
 498 sub add_dbxref {
 499     return shift->term->add_dbxref(@_);
 500 }
 501
 502 =head2 remove_dblinks
 503
 504  Title   : remove_dblinks()
 505  Usage   : $term->remove_dblinks();
 506  Function: Deletes (and returns) the definition references of this GO term.
 507  Returns : A list of definition references [array of [scalars]].
 508  Args    :
 509  Note    : this is deprecated in favor of remove_dbxrefs(), which works with strings
 510            or L<Bio::Annotation::DBLink> instances
 511
 512 =cut
 513
 514 sub remove_dblinks {
 515     my $self = shift;
 516     Carp::carp('remove_dblinks() is deprecated; use remove_dbxrefs()');
 517     return $self->term->remove_dbxrefs(@_);
 518 } # remove_dblinks
 519
 520 =head2 remove_dbxrefs
 521
 522  Title   : remove_dbxrefs()
 523  Usage   : $term->remove_dbxrefs();
 524  Function: Deletes (and returns) the definition references of this GO term.
 525  Returns : A list of definition references [array of [scalars]].
 526  Args    :
 527
 528 =cut
 529
 530 sub remove_dbxrefs {
 531     return shift->term->remove_dbxrefs(@_);
 532 }
 533
 534 =head2 get_secondary_ids
 535
 536  Title   : get_secondary_ids
 537  Usage   : @ids = $term->get_secondary_ids();
 538  Function: Returns a list of secondary identifiers of this Term.
 539
 540            Secondary identifiers mostly originate from merging terms,
 541            or possibly also from splitting terms.
 542
 543  Returns : A list of secondary identifiers [array of [scalar]]
 544  Args    :
 545
 546 =cut
 547
 548 sub get_secondary_ids {
 549     return shift->term->get_secondary_ids(@_);
 550 } # get_secondary_ids
 551
 552
 553 =head2 add_secondary_id
 554
 555  Title   : add_secondary_id
 556  Usage   : $term->add_secondary_id( @ids );
 557            or
 558            $term->add_secondary_id( $id );
 559  Function: Adds one or more secondary identifiers to this term.
 560  Returns :
 561  Args    : One or more secondary identifiers [scalars]
 562
 563 =cut
 564
 565 sub add_secondary_id {
 566     return shift->term->add_secondary_id(@_);
 567 } # add_secondary_id
 568
 569
 570 =head2 remove_secondary_ids
 571
 572  Title   : remove_secondary_ids
 573  Usage   : $term->remove_secondary_ids();
 574  Function: Deletes (and returns) the secondary identifiers of this Term.
 575  Returns : The previous list of secondary identifiers [array of [scalars]]
 576  Args    :
 577
 578 =cut
 579
 580 sub remove_secondary_ids {
 581     return shift->term->remove_secondary_ids(@_);
 582 } # remove_secondary_ids
 583
 584
 585 1;