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