Bio/Ontology/Relationship.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Relationship
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Christian M. Zmasek <czmasek@gnf.org> or <cmzmasek@yahoo.com>
   8 #
   9 # (c) Christian M. Zmasek, czmasek@gnf.org, 2002.
  10 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
  11 #
  12 # You may distribute this module under the same terms as perl itself.
  13 # Refer to the Perl Artistic License (see the license accompanying this
  14 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  15 # for the terms under which you may use, modify, and redistribute this module.
  16 #
  17 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  18 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  19 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  20 #
  21 # You may distribute this module under the same terms as perl itself
  22
  23 # POD documentation - main docs before the code
  24
  25 =head1 NAME
  26
  27 Bio::Ontology::Relationship - a relationship for an ontology
  28
  29 =head1 SYNOPSIS
  30
  31   $rel = Bio::Ontology::Relationship->new( -identifier     => "16847",
  32                                            -subject_term   => $subj,
  33                                            -object_term    => $obj,
  34                                            -predicate_term => $pred );
  35
  36 =head1 DESCRIPTION
  37
  38 This is a basic implementation of Bio::Ontology::RelationshipI.
  39
  40 The terminology we use here is the one commonly used for ontologies,
  41 namely the triple of (subject, predicate, object), which in addition
  42 is scoped in a namespace (ontology). It is called triple because it is
  43 a tuple of three ontology terms.
  44
  45 There are other terminologies in use for expressing relationships. For
  46 those who it helps to better understand the concept, the triple of
  47 (child, relationship type, parent) would be equivalent to the
  48 terminology chosen here, disregarding the question whether the notion
  49 of parent and child is sensible in the context of the relationship
  50 type or not. Especially in the case of ontologies with a wide variety
  51 of predicates the parent/child terminology and similar ones can
  52 quickly become ambiguous (e.g., A synthesises B), meaningless (e.g., A
  53 binds B), or even conflicting (e.g., A is-parent-of B), and are
  54 therefore strongly discouraged.
  55
  56 =head1 FEEDBACK
  57
  58 =head2 Mailing Lists
  59
  60 User feedback is an integral part of the evolution of this and other
  61 Bioperl modules. Send your comments and suggestions preferably to the
  62 Bioperl mailing lists  Your participation is much appreciated.
  63
  64   bioperl-l@bioperl.org                  - General discussion
  65   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  66
  67 =head2 Support
  68
  69 Please direct usage questions or support issues to the mailing list:
  70
  71 L<bioperl-l@bioperl.org>
  72
  73 rather than to the module maintainer directly. Many experienced and
  74 reponsive experts will be able look at the problem and quickly
  75 address it. Please include a thorough description of the problem
  76 with code and data examples if at all possible.
  77
  78 =head2 Reporting Bugs
  79
  80 Report bugs to the Bioperl bug tracking system to help us keep track
  81 the bugs and their resolution.  Bug reports can be submitted via
  82 the web:
  83
  84   http://bugzilla.open-bio.org/
  85
  86 =head1 AUTHOR
  87
  88 Christian M. Zmasek
  89
  90 Email: czmasek@gnf.org  or  cmzmasek@yahoo.com
  91
  92 WWW:   http://www.genetics.wustl.edu/eddy/people/zmasek/
  93
  94 Address:
  95
  96   Genomics Institute of the Novartis Research Foundation
  97   10675 John Jay Hopkins Drive
  98   San Diego, CA 92121
  99
 100 =head1 CONTRIBUTORS
 101
 102  Hilmar Lapp, email: hlapp at gmx.net
 103
 104 =head1 APPENDIX
 105
 106 The rest of the documentation details each of the object
 107 methods. Internal methods are usually preceded with a _
 108
 109 =cut
 110
 111
 112 # Let the code begin...
 113
 114
 115 package Bio::Ontology::Relationship;
 116 use strict;
 117 use Bio::Ontology::TermI;
 118
 119 use base qw(Bio::Root::Root Bio::Ontology::RelationshipI);
 120
 121
 122
 123
 124 =head2 new
 125
 126  Title   : new
 127  Usage   : $rel = Bio::Ontology::Relationship->new(-identifier   => "16847",
 128                                                    -subject_term => $subject,
 129                                                    -object_term  => $object,
 130                                                    -predicate_term => $type );
 131  Function: Creates a new Bio::Ontology::Relationship.
 132  Returns : A new Bio::Ontology::Relationship object.
 133  Args    : -identifier     => the identifier of this relationship [scalar]
 134            -subject_term   => the subject term [Bio::Ontology::TermI]
 135            -object_term    => the object term [Bio::Ontology::TermI]
 136            -predicate_term => the predicate term [Bio::Ontology::TermI]
 137
 138 =cut
 139
 140 sub new {
 141
 142     my( $class, @args ) = @_;
 143
 144     my $self = $class->SUPER::new( @args );
 145
 146     my ( $identifier,
 147          $subject_term,
 148                         $child,        # for backwards compatibility
 149          $object_term,
 150                         $parent,       # for backwards compatibility
 151          $predicate_term,
 152                         $reltype,      # for backwards compatibility
 153                         $ont)
 154         = $self->_rearrange( [qw( IDENTIFIER
 155                                   SUBJECT_TERM
 156                                   CHILD_TERM
 157                                   OBJECT_TERM
 158                                   PARENT_TERM
 159                                   PREDICATE_TERM
 160                                   RELATIONSHIP_TYPE
 161                                   ONTOLOGY)
 162                               ], @args );
 163
 164     $self->init();
 165
 166     $self->identifier( $identifier );
 167     $subject_term = $child unless $subject_term;
 168     $object_term = $parent unless $object_term;
 169     $predicate_term = $reltype unless $predicate_term;
 170     $self->subject_term( $subject_term) if $subject_term;
 171     $self->object_term( $object_term) if $object_term;
 172     $self->predicate_term( $predicate_term ) if $predicate_term;
 173     $self->ontology($ont) if $ont;
 174
 175     return $self;
 176
 177 } # new
 178
 179
 180
 181 =head2 init
 182
 183  Title   : init()
 184  Usage   : $rel->init();
 185  Function: Initializes this Relationship to all undef.
 186  Returns :
 187  Args    :
 188
 189 =cut
 190
 191 sub init {
 192     my( $self ) = @_;
 193
 194     $self->{ "_identifier" }     = undef;
 195     $self->{ "_subject_term" }   = undef;
 196     $self->{ "_object_term" }    = undef;
 197     $self->{ "_predicate_term" } = undef;
 198     $self->ontology(undef);
 199
 200 } # init
 201
 202
 203
 204 =head2 identifier
 205
 206  Title   : identifier
 207  Usage   : $rel->identifier( "100050" );
 208            or
 209            print $rel->identifier();
 210  Function: Set/get for the identifier of this Relationship.
 211  Returns : The identifier [scalar].
 212  Args    : The identifier [scalar] (optional).
 213
 214 =cut
 215
 216 sub identifier {
 217     my ( $self, $value ) = @_;
 218
 219     if ( defined $value ) {
 220         $self->{ "_identifier" } = $value;
 221     }
 222
 223     return $self->{ "_identifier" };
 224 } # identifier
 225
 226
 227
 228
 229 =head2 subject_term
 230
 231  Title   : subject_term
 232  Usage   : $rel->subject_term( $subject );
 233            or
 234            $subject = $rel->subject_term();
 235  Function: Set/get for the subject term of this Relationship.
 236
 237            The common convention for ontologies is to express
 238            relationships between terms as triples (subject, predicate,
 239            object).
 240
 241  Returns : The subject term [Bio::Ontology::TermI].
 242  Args    : The subject term [Bio::Ontology::TermI] (optional).
 243
 244 =cut
 245
 246 sub subject_term {
 247     my ( $self, $term ) = @_;
 248
 249     if ( defined $term ) {
 250         $self->_check_class( $term, "Bio::Ontology::TermI" );
 251         $self->{ "_subject_term" } = $term;
 252     }
 253
 254     return $self->{ "_subject_term" };
 255
 256 } # subject_term
 257
 258
 259
 260 =head2 object_term
 261
 262  Title   : object_term
 263  Usage   : $rel->object_term( $object );
 264            or
 265            $object = $rel->object_term();
 266  Function: Set/get for the object term of this Relationship.
 267
 268            The common convention for ontologies is to express
 269            relationships between terms as triples (subject, predicate,
 270            object).
 271
 272  Returns : The object term [Bio::Ontology::TermI].
 273  Args    : The object term [Bio::Ontology::TermI] (optional).
 274
 275 =cut
 276
 277 sub object_term {
 278     my ( $self, $term ) = @_;
 279
 280     if ( defined $term ) {
 281         $self->_check_class( $term, "Bio::Ontology::TermI" );
 282         $self->{ "_object_term" } = $term;
 283     }
 284
 285     return $self->{ "_object_term" };
 286 }
 287
 288
 289
 290 =head2 predicate_term
 291
 292  Title   : predicate_term
 293  Usage   : $rel->predicate_term( $type );
 294            or
 295            $type = $rel->predicate_term();
 296  Function: Set/get for the predicate (relationship type) of this
 297            relationship.
 298
 299            The common convention for ontologies is to express
 300            relationships between terms as triples (subject, predicate,
 301            object).
 302
 303  Returns : The predicate term [Bio::Ontology::TermI].
 304  Args    : The predicate term [Bio::Ontology::TermI] (optional).
 305
 306 =cut
 307
 308 sub predicate_term {
 309     my ( $self, $term ) = @_;
 310
 311     if ( defined $term ) {
 312         $self->_check_class( $term, "Bio::Ontology::TermI" );
 313         $self->{ "_predicate_term" } = $term;
 314     }
 315
 316     return $self->{ "_predicate_term" };
 317 }
 318
 319
 320 =head2 ontology
 321
 322  Title   : ontology
 323  Usage   : $ont = $obj->ontology()
 324  Function: Get/set the ontology that defined this relationship.
 325  Example :
 326  Returns : an object implementing L<Bio::Ontology::OntologyI>
 327  Args    : on set, undef or an object implementing
 328            Bio::Ontology::OntologyI (optional)
 329
 330 See L<Bio::Ontology::OntologyI>.
 331
 332 =cut
 333
 334 sub ontology{
 335     my $self = shift;
 336     my $ont;
 337
 338     if(@_) {
 339         $ont = shift;
 340         if($ont) {
 341             $ont = Bio::Ontology::Ontology->new(-name => $ont) if ! ref($ont);
 342             if(! $ont->isa("Bio::Ontology::OntologyI")) {
 343                 $self->throw(ref($ont)." does not implement ".
 344                              "Bio::Ontology::OntologyI. Bummer.");
 345             }
 346         }
 347         return $self->{"_ontology"} = $ont;
 348     }
 349     return $self->{"_ontology"};
 350 }
 351
 352 =head2 to_string
 353
 354  Title   : to_string()
 355  Usage   : print $rel->to_string();
 356  Function: to_string method for Relationship.
 357  Returns : A string representation of this Relationship.
 358  Args    :
 359
 360 =cut
 361
 362 sub to_string {
 363     my( $self ) = @_;
 364
 365     local $^W = 0;
 366
 367     my $s = "";
 368
 369     $s .= "-- Identifier:\n";
 370     $s .= $self->identifier()."\n";
 371     $s .= "-- Subject Term Identifier:\n";
 372     $s .= $self->subject_term()->identifier()."\n";
 373     $s .= "-- Object Term Identifier:\n";
 374     $s .= $self->object_term()->identifier()."\n";
 375     $s .= "-- Relationship Type Identifier:\n";
 376     $s .= $self->predicate_term()->identifier();
 377
 378     return $s;
 379
 380 } # to_string
 381
 382
 383
 384 sub _check_class {
 385     my ( $self, $value, $expected_class ) = @_;
 386
 387     if ( ! defined( $value ) ) {
 388         $self->throw( "Found [undef] where [$expected_class] expected" );
 389     }
 390     elsif ( ! ref( $value ) ) {
 391         $self->throw( "Found [scalar] where [$expected_class] expected" );
 392     }
 393     elsif ( ! $value->isa( $expected_class ) ) {
 394         $self->throw( "Found [" . ref( $value ) . "] where [$expected_class] expected" );
 395     }
 396
 397 } # _check_type
 398
 399 #################################################################
 400 # aliases for backwards compatibility
 401 #################################################################
 402
 403 =head1 Deprecated Methods
 404
 405   These methods are deprecated and defined here solely to preserve
 406   backwards compatibility.
 407
 408 =cut
 409
 410 *child_term        = \&subject_term;
 411 *parent_term       = \&object_term;
 412 *relationship_type = \&predicate_term;
 413
 414 1;