Bio/Ontology/Relationship.pm

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