Bio/Ontology/Relationship.pm

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