Bio/Ontology/Term.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::Term - implementation of the 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->each_synonym() ) {
  38       print $synonym, "\n";
  39   }
  40
  41 =head1 DESCRIPTION
  42
  43 This is a simple implementation for ontology terms providing basic
  44 methods (it provides no functionality related to graphs). It
  45 implements the L<Bio::Ontology::TermI> interface.
  46
  47 This class also implements L<Bio::IdentifiableI> and
  48 L<Bio::DescribableI>.
  49
  50 =head1 FEEDBACK
  51
  52 =head2 Mailing Lists
  53
  54 User feedback is an integral part of the evolution of this and other
  55 Bioperl modules. Send your comments and suggestions preferably to one
  56 of the Bioperl mailing lists.  Your participation is much appreciated.
  57
  58   bioperl-l@bioperl.org                  - General discussion
  59   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  60
  61 =head2 Reporting Bugs
  62
  63 Report bugs to the Bioperl bug tracking system to help us keep track
  64 the bugs and their resolution.  Bug reports can be submitted via the web:
  65
  66   http://bugzilla.open-bio.org/
  67
  68 =head1 AUTHOR
  69
  70 Christian M. Zmasek
  71
  72 Email: czmasek@gnf.org  or  cmzmasek@yahoo.com
  73
  74 WWW:   http://www.genetics.wustl.edu/eddy/people/zmasek/
  75
  76 Address:
  77
  78   Genomics Institute of the Novartis Research Foundation
  79   10675 John Jay Hopkins Drive
  80   San Diego, CA 92121
  81
  82 =head1 APPENDIX
  83
  84 The rest of the documentation details each of the object
  85 methods.
  86
  87 =cut
  88
  89
  90 # Let the code begin...
  91
  92 package Bio::Ontology::Term;
  93 use strict;
  94 use Bio::Ontology::Ontology;
  95 use Bio::Ontology::OntologyStore;
  96 use Bio::Annotation::DBLink;
  97 use Data::Dumper;
  98
  99 use constant TRUE    => 1;
 100 use constant FALSE   => 0;
 101
 102 use base qw(Bio::Root::Root Bio::Ontology::TermI Bio::IdentifiableI Bio::DescribableI);
 103
 104 =head2 new
 105
 106  Title   : new
 107  Usage   : $term = Bio::Ontology::Term->new(
 108                 -identifier  => "16847",
 109                 -name        => "1-aminocyclopropane-1-carboxylate synthase",
 110                 -definition  => "Catalysis of ...",
 111                 -is_obsolete => 0,
 112                 -comment     => "" );
 113  Function: Creates a new Bio::Ontology::Term.
 114  Returns : A new Bio::Ontology::Term object.
 115  Args    : -identifier            => the identifier of this term [scalar]
 116            -name                  => the name of this term [scalar]
 117            -definition            => the definition of this term [scalar]
 118            -ontology              => the ontology this term lives in
 119                                      (a Bio::Ontology::OntologyI object)
 120            -version               => version information [scalar]
 121            -is_obsolete           => the obsoleteness of this term [0 or 1]
 122            -comment               => a comment [scalar]
 123            -dblinks               => Bio::Annotation::DBLink objects
 124                                      [reference to array]
 125            -references            => Bio::Annotation::Reference objects
 126                                      [reference to array]
 127
 128 See L<Bio::Ontology::OntologyI>, L<Bio::Annotation::Reference>,
 129 L<Bio::Annotation::DBLink>.
 130
 131 =cut
 132
 133 sub new {
 134
 135     my( $class,@args ) = @_;
 136
 137     my $self = $class->SUPER::new( @args );
 138     my ( $identifier,
 139         $name,
 140         $definition,
 141         $category,
 142         $ont,
 143         $version,
 144         $is_obsolete,
 145         $comment,
 146         $dblinks,
 147         $dbxrefs,
 148         $references)
 149         = $self->_rearrange( [
 150         qw(IDENTIFIER
 151         NAME
 152         DEFINITION
 153         CATEGORY
 154         ONTOLOGY
 155         VERSION
 156         IS_OBSOLETE
 157         COMMENT
 158         DBLINKS
 159         DBXREFS
 160         REFERENCES
 161        ) ], @args );
 162
 163     $self->init();
 164
 165     defined($identifier)   && $self->identifier( $identifier );
 166     defined($name)         && $self->name( $name );
 167     defined($definition)   && $self->definition( $definition );
 168     defined($category)     && $self->category( $category );
 169     defined($ont)          && $self->ontology( $ont );
 170     defined($version)      && $self->version( $version );
 171     defined($is_obsolete)  && $self->is_obsolete( $is_obsolete );
 172     defined($comment)      && $self->comment( $comment  );
 173     defined($dbxrefs)      && $self->add_dbxref(-dbxrefs => $dbxrefs);
 174     # deprecated methods, allow to pass on to get the dep. notification
 175     ref($dblinks)          && $self->add_dblink(@$dblinks);
 176     ref($references)       && $self->add_reference(@$references);
 177
 178     return $self;
 179 } # new
 180
 181
 182
 183 sub init {
 184
 185     my $self = shift;
 186
 187     $self->identifier(undef);
 188     $self->name(undef);
 189     $self->comment(undef);
 190     $self->definition(undef);
 191     $self->ontology(undef);
 192     $self->is_obsolete(0);
 193     $self->remove_synonyms();
 194     $self->remove_dbxrefs();
 195     $self->remove_references;
 196     $self->remove_secondary_ids();
 197
 198 } # init
 199
 200
 201
 202 =head2 identifier
 203
 204  Title   : identifier
 205  Usage   : $term->identifier( "GO:0003947" );
 206            or
 207            print $term->identifier();
 208  Function: Set/get for the identifier of this Term.
 209  Returns : The identifier [scalar].
 210  Args    : The identifier [scalar] (optional).
 211
 212 =cut
 213
 214 sub identifier {
 215     my $self = shift;
 216
 217     return $self->{'identifier'} = shift if @_;
 218     return $self->{'identifier'};
 219 } # identifier
 220
 221
 222 =head2 name
 223
 224  Title   : name
 225  Usage   : $term->name( "N-acetylgalactosaminyltransferase" );
 226            or
 227            print $term->name();
 228  Function: Set/get for the name of this Term.
 229  Returns : The name [scalar].
 230  Args    : The name [scalar] (optional).
 231
 232 =cut
 233
 234 sub name {
 235     my $self = shift;
 236
 237     return $self->{'name'} = shift if @_;
 238     return $self->{'name'};
 239 } # name
 240
 241
 242 =head2 definition
 243
 244  Title   : definition
 245  Usage   : $term->definition( "Catalysis of ..." );
 246            or
 247            print $term->definition();
 248  Function: Set/get for the definition of this Term.
 249  Returns : The definition [scalar].
 250  Args    : The definition [scalar] (optional).
 251
 252 =cut
 253
 254 sub definition {
 255     my $self = shift;
 256
 257     return $self->{'definition'} = shift if @_;
 258     return $self->{'definition'};
 259 } # definition
 260
 261
 262 =head2 ontology
 263
 264  Title   : ontology
 265  Usage   : $ont = $term->ontology();
 266            or
 267            $term->ontology( $ont );
 268  Function: Get the ontology this term is in.
 269
 270            Note that with the ontology in hand you can query for all
 271            related terms etc.
 272
 273  Returns : The ontology of this Term as a Bio::Ontology::OntologyI
 274            implementing object.
 275  Args    : On set, the  ontology of this Term as a Bio::Ontology::OntologyI
 276            implementing object or a string representing its name.
 277
 278 See L<Bio::Ontology::OntologyI>.
 279
 280 =cut
 281
 282 sub ontology {
 283     my $self = shift;
 284     my $ont;
 285
 286     if(@_) {
 287         $ont = shift;
 288         if($ont) {
 289             $ont = Bio::Ontology::Ontology->new(-name => $ont) if ! ref($ont);
 290             if(! $ont->isa("Bio::Ontology::OntologyI")) {
 291                 $self->throw(ref($ont)." does not implement ".
 292                              "Bio::Ontology::OntologyI. Bummer.");
 293             }
 294         }
 295         return $self->{"_ontology"} = $ont;
 296     }
 297     return $self->{"_ontology"};
 298 } # ontology
 299
 300 =head2 version
 301
 302  Title   : version
 303  Usage   : $term->version( "1.00" );
 304            or
 305            print $term->version();
 306  Function: Set/get for version information.
 307  Returns : The version [scalar].
 308  Args    : The version [scalar] (optional).
 309
 310 =cut
 311
 312 sub version {
 313     my $self = shift;
 314
 315     return $self->{'version'} = shift if @_;
 316     return $self->{'version'};
 317 } # version
 318
 319 =head2 is_obsolete
 320
 321  Title   : is_obsolete
 322  Usage   : $term->is_obsolete( 1 );
 323            or
 324            if ( $term->is_obsolete() )
 325  Function: Set/get for the obsoleteness of this Term.
 326  Returns : the obsoleteness [0 or 1].
 327  Args    : the obsoleteness [0 or 1] (optional).
 328
 329 =cut
 330
 331 sub is_obsolete{
 332     my $self = shift;
 333
 334     return $self->{'is_obsolete'} = shift if @_;
 335     return $self->{'is_obsolete'};
 336 } # is_obsolete
 337
 338
 339 =head2 comment
 340
 341  Title   : comment
 342  Usage   : $term->comment( "Consider the term ..." );
 343            or
 344            print $term->comment();
 345  Function: Set/get for an arbitrary comment about this Term.
 346  Returns : A comment.
 347  Args    : A comment (optional).
 348
 349 =cut
 350
 351 sub comment{
 352     my $self = shift;
 353
 354     return $self->{'comment'} = shift if @_;
 355     return $self->{'comment'};
 356 } # comment
 357
 358 =head2 get_synonyms
 359
 360  Title   : get_synonyms
 361  Usage   : @aliases = $term->get_synonyms;
 362  Function: Returns a list of aliases of this Term.
 363  Returns : A list of aliases [array of [scalar]].
 364  Args    :
 365
 366 =cut
 367
 368 sub get_synonyms {
 369     my $self = shift;
 370
 371     return @{ $self->{ "_synonyms" } } if exists($self->{ "_synonyms" });
 372     return ();
 373 } # get_synonyms
 374
 375
 376 =head2 add_synonym
 377
 378  Title   : add_synonym
 379  Usage   : $term->add_synonym( @asynonyms );
 380            or
 381            $term->add_synonym( $synonym );
 382  Function: Pushes one or more synonyms into the list of synonyms.
 383  Returns :
 384  Args    : One synonym [scalar] or a list of synonyms [array of [scalar]].
 385
 386 =cut
 387
 388 sub add_synonym {
 389     my ( $self, @values ) = @_;
 390
 391     return unless( @values );
 392
 393     # avoid duplicates
 394     foreach my $syn (@values) {
 395         next if grep { $_ eq $syn; } @{$self->{ "_synonyms" }};
 396         push( @{ $self->{ "_synonyms" } }, $syn );
 397     }
 398
 399 } # add_synonym
 400
 401
 402 =head2 remove_synonyms
 403
 404  Title   : remove_synonyms()
 405  Usage   : $term->remove_synonyms();
 406  Function: Deletes (and returns) the synonyms of this Term.
 407  Returns : A list of synonyms [array of [scalar]].
 408  Args    :
 409
 410 =cut
 411
 412 sub remove_synonyms {
 413     my ( $self ) = @_;
 414
 415     my @a = $self->get_synonyms();
 416     $self->{ "_synonyms" } = [];
 417     return @a;
 418
 419 } # remove_synonyms
 420
 421 =head2 get_dblinks
 422
 423  Title   : get_dblinks()
 424  Usage   : @ds = $term->get_dblinks();
 425  Function: Returns a list of each dblinks of this GO term.
 426  Returns : A list of dblinks [array of [scalars]].
 427  Args    : A scalar indicating the context (optional).
 428            If omitted, all dblinks will be returned.
 429  Note    : deprecated method due to past use of mixed data types; use
 430            get_dbxrefs() instead, which handles both strings and DBLink
 431            instances
 432
 433 =cut
 434
 435 sub get_dblinks {
 436     my ($self, $context) = @_;
 437     $self->deprecated("Use of get_dblinks is deprecated.  Note that prior use\n".
 438                       "of this method could return either simple scalar values\n".
 439                       "or Bio::Annotation::DBLink instances; only \n".
 440                       "Bio::Annotation::DBLink is now supported.\n ".
 441                       "Use get_dbxrefs() instead");
 442     $self->get_dbxrefs($context);
 443 } # get_dblinks
 444
 445 =head2 get_dbxrefs
 446
 447  Title   : get_dbxrefs()
 448  Usage   : @ds = $term->get_dbxrefs();
 449  Function: Returns a list of each link for this term.
 450
 451            If an implementor of this interface permits modification of
 452            this array property, the class should define at least
 453            methods add_dbxref() and remove_dbxrefs(), with obvious
 454            functionality.
 455
 456  Returns : A list of L<Bio::Annotation::DBLink> instances
 457  Args    : [optional] string which specifies context (default : returns all dbxrefs)
 458
 459 =cut
 460
 461 sub get_dbxrefs {
 462     my ($self, $context) = shift;
 463     my @dbxrefs;
 464     if (defined($context)) {
 465         if (exists($self->{_dblinks}->{$context})) {
 466             @dbxrefs =  @{$self->{_dblinks}->{$context}};
 467         }
 468     } else {
 469         @dbxrefs = map { @$_ } values %{$self->{_dblinks}} ;
 470     }
 471     return @dbxrefs;
 472 } # get_dbxrefs
 473
 474 =head2 get_dblink_context
 475
 476   Title   : get_dblink_context
 477   Usage   : @context = $term->get_dblink_context;
 478   Function: Return all context existing in Term
 479   Returns : a list of scalar
 480   Args    : [none]
 481   Note    : deprecated method due to past use of mixed data types; use
 482             get_dbxref_context() instead
 483
 484 =cut
 485
 486 sub get_dblink_context {
 487     my $self=shift;
 488     $self->deprecated("Use of get_dblink_context() is deprecated; use get_dbxref_context() instead");
 489     return $self->get_dbxref_context(@_);
 490 }
 491
 492 =head2 get_dbxref_context
 493
 494   Title   : get_dbxref_context
 495   Usage   : @context = $term->get_dbxref_context;
 496   Function: Return all context strings existing in Term
 497   Returns : a list of scalars
 498   Args    : [none]
 499
 500 =cut
 501
 502 sub get_dbxref_context {
 503     my $self=shift;
 504     return keys %{$self->{_dblinks}};
 505 }
 506
 507 =head2 add_dblink
 508
 509  Title   : add_dblink
 510  Usage   : $term->add_dblink( @dbls );
 511            or
 512            $term->add_dblink( $dbl );
 513  Function: Pushes one or more dblinks onto the list of dblinks.
 514  Returns :
 515  Args    : One or more L<Bio::Annotation::DBLink> instances
 516  Note    : deprecated method due to past use of mixed data types; use
 517            add_dbxref() instead, which handles both strings and
 518            DBLink instances
 519
 520 =cut
 521
 522 sub add_dblink {
 523     my $self = shift;
 524     $self->deprecated("Use of simple strings and add_dblink() is deprecated; use\n".
 525                       "Bio::Annotation::DBLink instances and add_dbxref() instead");
 526     # here we're assuming the data is in a simple DB:ID format
 527     my @dbxrefs;
 528     for my $string (@_) {
 529         my ($db, $id) = split(':',$string);
 530         push @dbxrefs, Bio::Annotation::DBLink->new(-database => $db, -primary_id => $id);
 531     }
 532     return $self->add_dbxref(-dbxrefs => \@dbxrefs, -context => '_default');
 533 } # add_dblink
 534
 535 =head2 add_dbxref
 536
 537  Title   : add_dbxref
 538  Usage   : $term->add_dbxref( @dbls );
 539            or
 540            $term->add_dbxref( $dbl );
 541  Function: Pushes one or more dblinks onto the list of dblinks.
 542  Returns :
 543  Args    : -dbxrefs : array ref of Bio::Annotation::DBLink instances
 544            -context : string designating the context for the DBLink
 545                        (default : '_default' - contextless)
 546
 547 =cut
 548
 549 sub add_dbxref {
 550     my $self = shift;
 551     my ($links, $context) = $self->_rearrange([qw(DBXREFS CONTEXT)],@_);
 552     return unless defined $links;
 553     $context ||= '_default';
 554     $self->throw("DBLinks must be passed as an array reference") if ref $links ne 'ARRAY';
 555     foreach my $dbxref (@{$links}) {
 556         $self->throw("$dbxref is not a DBLink") unless ref $dbxref &&
 557             $dbxref->isa('Bio::Annotation::DBLink');
 558         $self->throw("'all' is a reserved word for context.") if $context eq 'all';
 559         if (! exists($self->{_dblinks}->{$context})) {
 560             $self->{_dblinks}->{$context} = [];
 561         }
 562         my $linktext = ref $dbxref ? $dbxref->display_text : $dbxref;
 563         if (grep {$_->display_text eq $linktext}
 564             @{$self->{_dblinks}->{$context}})
 565         {
 566             $self->warn("DBLink exists in the dblink of $context");
 567         }
 568         push @{$self->{_dblinks}->{$context}}, $dbxref;
 569     }
 570 } # add_dbxref
 571
 572 =head2 has_dblink
 573
 574   Title   : has_dblink
 575   Usage   : $term->has_dblink($dblink);
 576   Function: Checks if a DBXref is already existing in the OBOterm object
 577   Return  : TRUE/FALSE
 578   Args    : [arg1] A DBxref identifier
 579   Note    : deprecated method due to past use of mixed data types; use
 580             has_dbxref() instead, which handles both strings and
 581             DBLink instances
 582
 583 =cut
 584
 585 sub has_dblink {
 586     my ( $self, $value ) = @_;
 587     $self->deprecated("use of has_dblink() is deprecated; use has_dbxref() instead");
 588     return $self->has_dbxref($value);
 589 }
 590
 591 =head2 has_dbxref
 592
 593   Title   : has_dbxref
 594   Usage   : $term->has_dbxref($dbxref);
 595   Function: Checks if a dbxref string is already existing in the OBOterm object
 596   Return  : TRUE/FALSE
 597   Args    : [arg1] A DBxref identifier (string).
 598             Bio::Annotation::DBLink::display_text() is used for comparison
 599             against the string.
 600
 601 =cut
 602
 603 sub has_dbxref {
 604     my ( $self, $value ) = @_;
 605     return unless defined $value;
 606     my $context = "_default";
 607     $self->throw("'all' is a reserved word for context.") if $context eq 'all';
 608     $context ||= '_default';
 609     if ( ( $self->{_dblinks}->{$context} ) &&
 610         grep { $_->display_text eq $value }
 611         @{ $self->{_dblinks}->{$context} } )
 612     {
 613         return TRUE;
 614     }
 615     else {
 616         return FALSE;
 617     }
 618 }
 619
 620 =head2 add_dblink_context
 621
 622   Title   : add_dblink_context
 623   Usage   : $term->add_dblink_context($db, $context);
 624   Function: add a dblink with its context
 625   Return  : [none]
 626   Args    : [arg1] a Bio::Annotation::DBLink instance
 627             [arg2] a string for context; if omitted, the
 628                    default/context-less one will be used.
 629   Note    : deprecated method due to past use of mixed data types; use
 630             add_dbxref() instead
 631
 632 =cut
 633
 634 sub add_dblink_context {
 635     my ($self, $value, $context) = @_;
 636     $self->deprecated("Use of simple strings and add_dblink_context() is deprecated; use\n
 637                       Bio::Annotation::DBLink instances and add_dbxref() instead");
 638     return $self->add_dbxref([$value],$context);
 639 }
 640
 641 =head2 remove_dblinks
 642
 643  Title   : remove_dblinks()
 644  Usage   : $term->remove_dblinks();
 645  Function: Deletes (and returns) the definition references of this GO term.
 646  Returns : A list of definition references [array of [scalars]].
 647  Args    : Context. If omitted or equal to 'all', all dblinks
 648            will be removed.
 649  Note    : deprecated method due to past use of mixed data types; use
 650            remove_dblinks() instead, which handles both strings and
 651            DBLink instances
 652
 653 =cut
 654
 655 sub remove_dblinks {
 656     my ($self, $context) = @_;
 657     $self->deprecated("use of remove_dblinks() is deprecated; use remove_dbxrefs() instead");
 658     return $self->remove_dbxrefs(@_);
 659 } # remove_dblinks
 660
 661 =head2 remove_dbxrefs
 662
 663  Title   : remove_dbxrefs()
 664  Usage   : $term->remove_dbxrefs();
 665  Function: Deletes (and returns) the definition references of this GO term.
 666  Returns : A list of definition references [array of [scalars]].
 667  Args    : Context. If omitted or equal to 'all', all dblinks
 668            will be removed.
 669
 670 =cut
 671
 672 sub remove_dbxrefs {
 673     my ($self, $context) = @_;
 674     $context = undef if $context && ($context eq "all");
 675     my @old = $self->get_dbxrefs($context);
 676     if (defined($context)) {
 677         $self->{_dblinks}->{$context}=[];
 678     } else {
 679         $self->{_dblinks} = {};
 680     }
 681     return @old;
 682 } # remove_dbxrefs
 683
 684 =head2 get_references
 685
 686   Title   : get_references
 687   Usage   : @references = $self->get_references
 688   Fuctnion: Returns a list of references
 689   Return  : A list of objects
 690   Args    : [none]
 691
 692 =cut
 693
 694 sub get_references {
 695     my $self=shift;
 696     return @{$self->{_references}} if exists $self->{_references};
 697     return ();
 698 }
 699
 700 =head2 add_reference
 701
 702   Title   : add_reference
 703   Usage   : $self->add_reference($reference);
 704             $self->add_reference($reference1, $reference2);
 705   Fuctnion: Add one or more references
 706   Returns : [none]
 707
 708 =cut
 709
 710 sub add_reference {
 711     my ($self, @values) =@_;
 712     return unless @values;
 713     # avoid duplicates and undefs
 714     foreach my $reference (@values){
 715         $self->throw("Passed data not an Bio::Annotation::Reference") unless ref $reference &&
 716             $reference->isa('Bio::AnnotationI');
 717         next unless defined $reference;
 718         next if grep{$_ eq $reference} @{$self->{_references}};
 719         push @{$self->{_references}}, $reference;
 720     }
 721 }
 722
 723 =head2 remove_references
 724
 725   Title   : remove_references
 726   Usage   : $self->remove_references;
 727   Function: Deletes (and returns) all references
 728   Returns : A list of references
 729   Args    : [none]
 730
 731 =cut
 732
 733 sub remove_references {
 734     my $self=shift;
 735     my @references=$self->get_references;
 736     $self->{_references}=[];
 737     return @references;
 738 }
 739
 740 =head2 get_secondary_ids
 741
 742  Title   : get_secondary_ids
 743  Usage   : @ids = $term->get_secondary_ids();
 744  Function: Returns a list of secondary identifiers of this Term.
 745
 746            Secondary identifiers mostly originate from merging terms,
 747            or possibly also from splitting terms.
 748
 749  Returns : A list of secondary identifiers [array of [scalar]]
 750  Args    :
 751
 752 =cut
 753
 754 sub get_secondary_ids {
 755     my $self = shift;
 756
 757     return @{$self->{"_secondary_ids"}} if exists($self->{"_secondary_ids"});
 758     return ();
 759 } # get_secondary_ids
 760
 761
 762 =head2 add_secondary_id
 763
 764  Title   : add_secondary_id
 765  Usage   : $term->add_secondary_id( @ids );
 766            or
 767            $term->add_secondary_id( $id );
 768  Function: Adds one or more secondary identifiers to this term.
 769  Returns :
 770  Args    : One or more secondary identifiers [scalars]
 771
 772 =cut
 773
 774 sub add_secondary_id {
 775     my $self = shift;
 776
 777     return unless @_;
 778
 779     # avoid duplicates
 780     foreach my $id (@_) {
 781         next if grep { !$_ or $_ eq $id; } @{$self->{ "_secondary_ids" }};
 782         push( @{ $self->{ "_secondary_ids" } }, $id );
 783     }
 784
 785 } # add_secondary_id
 786
 787
 788 =head2 remove_secondary_ids
 789
 790  Title   : remove_secondary_ids
 791  Usage   : $term->remove_secondary_ids();
 792  Function: Deletes (and returns) the secondary identifiers of this Term.
 793  Returns : The previous list of secondary identifiers [array of [scalars]]
 794  Args    :
 795
 796 =cut
 797
 798 sub remove_secondary_ids {
 799     my $self = shift;
 800
 801     my @a = $self->get_secondary_ids();
 802     $self->{ "_secondary_ids" } = [];
 803     return @a;
 804
 805 } # remove_secondary_ids
 806
 807
 808 # Title   :_is_true_or_false
 809 # Function: Checks whether the argument is TRUE or FALSE.
 810 # Returns :
 811 # Args    : The value to be checked.
 812 sub _is_true_or_false {
 813     my ( $self, $value ) = @_;
 814     unless ( $value !~ /\D/ && ( $value == TRUE || $value == FALSE ) ) {
 815         $self->throw( "Found [" . $value
 816         . "] where " . TRUE . " or " . FALSE . " expected" );
 817     }
 818 } # _is_true_or_false
 819
 820 =head1 Methods implementing L<Bio::IdentifiableI> and L<Bio::DescribableI>
 821
 822 =cut
 823
 824 =head2 object_id
 825
 826  Title   : object_id
 827  Usage   : $string    = $obj->object_id()
 828  Function: a string which represents the stable primary identifier
 829            in this namespace of this object.
 830
 831            This is a synonym for identifier().
 832
 833  Returns : A scalar
 834
 835 =cut
 836
 837 sub object_id {
 838     return shift->identifier(@_);
 839 }
 840
 841 =head2 authority
 842
 843  Title   : authority
 844  Usage   : $authority    = $obj->authority()
 845  Function: a string which represents the organisation which
 846            granted the namespace, written as the DNS name for
 847            organisation (eg, wormbase.org)
 848
 849            This forwards to ontology()->authority(). Note that you
 850            cannot set the authority before having set the ontology or
 851            the namespace (which will set the ontology).
 852
 853  Returns : A scalar
 854  Args    : on set, the new value (a scalar)
 855
 856 =cut
 857
 858 sub authority {
 859     my $self = shift;
 860     my $ont = $self->ontology();
 861
 862     return $ont->authority(@_) if $ont;
 863     $self->throw("cannot manipulate authority prior to ".
 864                  "setting the namespace or ontology") if @_;
 865     return;
 866 }
 867
 868
 869 =head2 namespace
 870
 871  Title   : namespace
 872  Usage   : $string    = $obj->namespace()
 873  Function: A string representing the name space this identifier
 874            is valid in, often the database name or the name
 875            describing the collection.
 876
 877            This forwards to ontology() (set mode) and
 878            ontology()->name() (get mode). I.e., setting the namespace
 879            will set the ontology to one matching that name in the
 880            ontology store, or to one newly created.
 881
 882  Returns : A scalar
 883  Args    : on set, the new value (a scalar)
 884
 885 =cut
 886
 887 sub namespace {
 888     my $self = shift;
 889
 890     $self->ontology(@_) if(@_);
 891     my $ont = $self->ontology();
 892     return defined($ont) ? $ont->name() : undef;
 893 }
 894
 895 =head2 display_name
 896
 897  Title   : display_name
 898  Usage   : $string    = $obj->display_name()
 899  Function: A string which is what should be displayed to the user.
 900
 901            The definition in Bio::DescribableI states that the
 902            string should not contain spaces. As this is not very
 903            sensible for ontology terms, we relax this here. The
 904            implementation just forwards to name().
 905
 906  Returns : A scalar
 907  Args    : on set, the new value (a scalar)
 908
 909 =cut
 910
 911 sub display_name {
 912     return shift->name(@_);
 913 }
 914
 915
 916 =head2 description
 917
 918  Title   : description
 919  Usage   : $string    = $obj->description()
 920  Function: A text string suitable for displaying to the user a
 921            description. This string is likely to have spaces, but
 922            should not have any newlines or formatting - just plain
 923            text.
 924
 925            This forwards to definition(). The caveat is that the text
 926            will often be longer for ontology term definitions than the
 927            255 characters stated in the definition in
 928            Bio::DescribableI.
 929
 930  Returns : A scalar
 931  Args    : on set, the new value (a scalar)
 932
 933 =cut
 934
 935 sub description {
 936     return shift->definition(@_);
 937 }
 938
 939 #################################################################
 940 # aliases or forwards to maintain backward compatibility
 941 #################################################################
 942
 943 =head1  Deprecated methods
 944
 945 Used for looking up the methods that supercedes them.
 946
 947 =cut
 948
 949 sub each_dblink {shift->throw("use of each_dblink() is deprecated; use get_dbxrefs() instead")}
 950 sub add_dblinks {shift->throw("use of add_dblinks() is deprecated; use add_dbxref() instead")}
 951 *each_synonym = \&get_synonyms;
 952 *add_synonyms = \&add_synonym;
 953
 954 1;