|
0
|
1 # $Id: Relationship.pm,v 1.4.2.3 2003/03/27 10:07:56 lapp Exp $
|
|
|
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 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://bio.perl.org/MailList.html - 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 email or the web:
|
|
|
70
|
|
|
71 bioperl-bugs@bio.perl.org
|
|
|
72 http://bugzilla.bioperl.org/
|
|
|
73
|
|
|
74 =head1 AUTHOR
|
|
|
75
|
|
|
76 Christian M. Zmasek
|
|
|
77
|
|
|
78 Email: czmasek@gnf.org or cmzmasek@yahoo.com
|
|
|
79
|
|
|
80 WWW: http://www.genetics.wustl.edu/eddy/people/zmasek/
|
|
|
81
|
|
|
82 Address:
|
|
|
83
|
|
|
84 Genomics Institute of the Novartis Research Foundation
|
|
|
85 10675 John Jay Hopkins Drive
|
|
|
86 San Diego, CA 92121
|
|
|
87
|
|
|
88 =head1 CONTRIBUTORS
|
|
|
89
|
|
|
90 Hilmar Lapp, email: hlapp at gmx.net
|
|
|
91
|
|
|
92 =head1 APPENDIX
|
|
|
93
|
|
|
94 The rest of the documentation details each of the object
|
|
|
95 methods. Internal methods are usually preceded with a _
|
|
|
96
|
|
|
97 =cut
|
|
|
98
|
|
|
99
|
|
|
100 # Let the code begin...
|
|
|
101
|
|
|
102
|
|
|
103 package Bio::Ontology::Relationship;
|
|
|
104 use vars qw( @ISA );
|
|
|
105 use strict;
|
|
|
106 use Bio::Root::Root;
|
|
|
107 use Bio::Ontology::TermI;
|
|
|
108 use Bio::Ontology::RelationshipI;
|
|
|
109
|
|
|
110 @ISA = qw( Bio::Root::Root
|
|
|
111 Bio::Ontology::RelationshipI );
|
|
|
112
|
|
|
113
|
|
|
114
|
|
|
115
|
|
|
116 =head2 new
|
|
|
117
|
|
|
118 Title : new
|
|
|
119 Usage : $rel = Bio::Ontology::Relationship->new(-identifier => "16847",
|
|
|
120 -subject_term => $subject,
|
|
|
121 -object_term => $object,
|
|
|
122 -predicate_term => $type );
|
|
|
123 Function: Creates a new Bio::Ontology::Relationship.
|
|
|
124 Returns : A new Bio::Ontology::Relationship object.
|
|
|
125 Args : -identifier => the identifier of this relationship [scalar]
|
|
|
126 -subject_term => the subject term [Bio::Ontology::TermI]
|
|
|
127 -object_term => the object term [Bio::Ontology::TermI]
|
|
|
128 -predicate_term => the predicate term [Bio::Ontology::TermI]
|
|
|
129
|
|
|
130 =cut
|
|
|
131
|
|
|
132 sub new {
|
|
|
133
|
|
|
134 my( $class, @args ) = @_;
|
|
|
135
|
|
|
136 my $self = $class->SUPER::new( @args );
|
|
|
137
|
|
|
138 my ( $identifier,
|
|
|
139 $subject_term,
|
|
|
140 $child, # for backwards compatibility
|
|
|
141 $object_term,
|
|
|
142 $parent, # for backwards compatibility
|
|
|
143 $predicate_term,
|
|
|
144 $reltype, # for backwards compatibility
|
|
|
145 $ont)
|
|
|
146 = $self->_rearrange( [qw( IDENTIFIER
|
|
|
147 SUBJECT_TERM
|
|
|
148 CHILD_TERM
|
|
|
149 OBJECT_TERM
|
|
|
150 PARENT_TERM
|
|
|
151 PREDICATE_TERM
|
|
|
152 RELATIONSHIP_TYPE
|
|
|
153 ONTOLOGY)
|
|
|
154 ], @args );
|
|
|
155
|
|
|
156 $self->init();
|
|
|
157
|
|
|
158 $self->identifier( $identifier );
|
|
|
159 $subject_term = $child unless $subject_term;
|
|
|
160 $object_term = $parent unless $object_term;
|
|
|
161 $predicate_term = $reltype unless $predicate_term;
|
|
|
162 $self->subject_term( $subject_term) if $subject_term;
|
|
|
163 $self->object_term( $object_term) if $object_term;
|
|
|
164 $self->predicate_term( $predicate_term ) if $predicate_term;
|
|
|
165 $self->ontology($ont) if $ont;
|
|
|
166
|
|
|
167 return $self;
|
|
|
168
|
|
|
169 } # new
|
|
|
170
|
|
|
171
|
|
|
172
|
|
|
173 =head2 init
|
|
|
174
|
|
|
175 Title : init()
|
|
|
176 Usage : $rel->init();
|
|
|
177 Function: Initializes this Relationship to all undef.
|
|
|
178 Returns :
|
|
|
179 Args :
|
|
|
180
|
|
|
181 =cut
|
|
|
182
|
|
|
183 sub init {
|
|
|
184 my( $self ) = @_;
|
|
|
185
|
|
|
186 $self->{ "_identifier" } = undef;
|
|
|
187 $self->{ "_subject_term" } = undef;
|
|
|
188 $self->{ "_object_term" } = undef;
|
|
|
189 $self->{ "_predicate_term" } = undef;
|
|
|
190 $self->ontology(undef);
|
|
|
191
|
|
|
192 } # init
|
|
|
193
|
|
|
194
|
|
|
195
|
|
|
196 =head2 identifier
|
|
|
197
|
|
|
198 Title : identifier
|
|
|
199 Usage : $rel->identifier( "100050" );
|
|
|
200 or
|
|
|
201 print $rel->identifier();
|
|
|
202 Function: Set/get for the identifier of this Relationship.
|
|
|
203 Returns : The identifier [scalar].
|
|
|
204 Args : The identifier [scalar] (optional).
|
|
|
205
|
|
|
206 =cut
|
|
|
207
|
|
|
208 sub identifier {
|
|
|
209 my ( $self, $value ) = @_;
|
|
|
210
|
|
|
211 if ( defined $value ) {
|
|
|
212 $self->{ "_identifier" } = $value;
|
|
|
213 }
|
|
|
214
|
|
|
215 return $self->{ "_identifier" };
|
|
|
216 } # identifier
|
|
|
217
|
|
|
218
|
|
|
219
|
|
|
220
|
|
|
221 =head2 subject_term
|
|
|
222
|
|
|
223 Title : subject_term
|
|
|
224 Usage : $rel->subject_term( $subject );
|
|
|
225 or
|
|
|
226 $subject = $rel->subject_term();
|
|
|
227 Function: Set/get for the subject term of this Relationship.
|
|
|
228
|
|
|
229 The common convention for ontologies is to express
|
|
|
230 relationships between terms as triples (subject, predicate,
|
|
|
231 object).
|
|
|
232
|
|
|
233 Returns : The subject term [Bio::Ontology::TermI].
|
|
|
234 Args : The subject term [Bio::Ontology::TermI] (optional).
|
|
|
235
|
|
|
236 =cut
|
|
|
237
|
|
|
238 sub subject_term {
|
|
|
239 my ( $self, $term ) = @_;
|
|
|
240
|
|
|
241 if ( defined $term ) {
|
|
|
242 $self->_check_class( $term, "Bio::Ontology::TermI" );
|
|
|
243 $self->{ "_subject_term" } = $term;
|
|
|
244 }
|
|
|
245
|
|
|
246 return $self->{ "_subject_term" };
|
|
|
247
|
|
|
248 } # subject_term
|
|
|
249
|
|
|
250
|
|
|
251
|
|
|
252 =head2 object_term
|
|
|
253
|
|
|
254 Title : object_term
|
|
|
255 Usage : $rel->object_term( $object );
|
|
|
256 or
|
|
|
257 $object = $rel->object_term();
|
|
|
258 Function: Set/get for the object term of this Relationship.
|
|
|
259
|
|
|
260 The common convention for ontologies is to express
|
|
|
261 relationships between terms as triples (subject, predicate,
|
|
|
262 object).
|
|
|
263
|
|
|
264 Returns : The object term [Bio::Ontology::TermI].
|
|
|
265 Args : The object term [Bio::Ontology::TermI] (optional).
|
|
|
266
|
|
|
267 =cut
|
|
|
268
|
|
|
269 sub object_term {
|
|
|
270 my ( $self, $term ) = @_;
|
|
|
271
|
|
|
272 if ( defined $term ) {
|
|
|
273 $self->_check_class( $term, "Bio::Ontology::TermI" );
|
|
|
274 $self->{ "_object_term" } = $term;
|
|
|
275 }
|
|
|
276
|
|
|
277 return $self->{ "_object_term" };
|
|
|
278 }
|
|
|
279
|
|
|
280
|
|
|
281
|
|
|
282 =head2 predicate_term
|
|
|
283
|
|
|
284 Title : predicate_term
|
|
|
285 Usage : $rel->predicate_term( $type );
|
|
|
286 or
|
|
|
287 $type = $rel->predicate_term();
|
|
|
288 Function: Set/get for the predicate (relationship type) of this
|
|
|
289 relationship.
|
|
|
290
|
|
|
291 The common convention for ontologies is to express
|
|
|
292 relationships between terms as triples (subject, predicate,
|
|
|
293 object).
|
|
|
294
|
|
|
295 Returns : The predicate term [Bio::Ontology::TermI].
|
|
|
296 Args : The predicate term [Bio::Ontology::TermI] (optional).
|
|
|
297
|
|
|
298 =cut
|
|
|
299
|
|
|
300 sub predicate_term {
|
|
|
301 my ( $self, $term ) = @_;
|
|
|
302
|
|
|
303 if ( defined $term ) {
|
|
|
304 $self->_check_class( $term, "Bio::Ontology::TermI" );
|
|
|
305 $self->{ "_predicate_term" } = $term;
|
|
|
306 }
|
|
|
307
|
|
|
308 return $self->{ "_predicate_term" };
|
|
|
309 }
|
|
|
310
|
|
|
311
|
|
|
312 =head2 ontology
|
|
|
313
|
|
|
314 Title : ontology
|
|
|
315 Usage : $ont = $obj->ontology()
|
|
|
316 Function: Get/set the ontology that defined this relationship.
|
|
|
317 Example :
|
|
|
318 Returns : an object implementing L<Bio::Ontology::OntologyI>
|
|
|
319 Args : on set, undef or an object implementing
|
|
|
320 L<Bio::Ontology::OntologyI> (optional)
|
|
|
321
|
|
|
322
|
|
|
323 =cut
|
|
|
324
|
|
|
325 sub ontology{
|
|
|
326 my $self = shift;
|
|
|
327 my $ont;
|
|
|
328
|
|
|
329 if(@_) {
|
|
|
330 $ont = shift;
|
|
|
331 if($ont) {
|
|
|
332 $ont = Bio::Ontology::Ontology->new(-name => $ont) if ! ref($ont);
|
|
|
333 if(! $ont->isa("Bio::Ontology::OntologyI")) {
|
|
|
334 $self->throw(ref($ont)." does not implement ".
|
|
|
335 "Bio::Ontology::OntologyI. Bummer.");
|
|
|
336 }
|
|
|
337 }
|
|
|
338 return $self->{"_ontology"} = $ont;
|
|
|
339 }
|
|
|
340 return $self->{"_ontology"};
|
|
|
341 }
|
|
|
342
|
|
|
343 =head2 to_string
|
|
|
344
|
|
|
345 Title : to_string()
|
|
|
346 Usage : print $rel->to_string();
|
|
|
347 Function: to_string method for Relationship.
|
|
|
348 Returns : A string representation of this Relationship.
|
|
|
349 Args :
|
|
|
350
|
|
|
351 =cut
|
|
|
352
|
|
|
353 sub to_string {
|
|
|
354 my( $self ) = @_;
|
|
|
355
|
|
|
356 local $^W = 0;
|
|
|
357
|
|
|
358 my $s = "";
|
|
|
359
|
|
|
360 $s .= "-- Identifier:\n";
|
|
|
361 $s .= $self->identifier()."\n";
|
|
|
362 $s .= "-- Subject Term Identifier:\n";
|
|
|
363 $s .= $self->subject_term()->identifier()."\n";
|
|
|
364 $s .= "-- Object Term Identifier:\n";
|
|
|
365 $s .= $self->object_term()->identifier()."\n";
|
|
|
366 $s .= "-- Relationship Type Identifier:\n";
|
|
|
367 $s .= $self->predicate_term()->identifier();
|
|
|
368
|
|
|
369 return $s;
|
|
|
370
|
|
|
371 } # to_string
|
|
|
372
|
|
|
373
|
|
|
374
|
|
|
375 sub _check_class {
|
|
|
376 my ( $self, $value, $expected_class ) = @_;
|
|
|
377
|
|
|
378 if ( ! defined( $value ) ) {
|
|
|
379 $self->throw( "Found [undef] where [$expected_class] expected" );
|
|
|
380 }
|
|
|
381 elsif ( ! ref( $value ) ) {
|
|
|
382 $self->throw( "Found [scalar] where [$expected_class] expected" );
|
|
|
383 }
|
|
|
384 elsif ( ! $value->isa( $expected_class ) ) {
|
|
|
385 $self->throw( "Found [" . ref( $value ) . "] where [$expected_class] expected" );
|
|
|
386 }
|
|
|
387
|
|
|
388 } # _check_type
|
|
|
389
|
|
|
390 #################################################################
|
|
|
391 # aliases for backwards compatibility
|
|
|
392 #################################################################
|
|
|
393
|
|
|
394 =head1 Deprecated Methods
|
|
|
395
|
|
|
396 These methods are deprecated and defined here solely to preserve
|
|
|
397 backwards compatibility.
|
|
|
398
|
|
|
399 =cut
|
|
|
400
|
|
|
401 *child_term = \&subject_term;
|
|
|
402 *parent_term = \&object_term;
|
|
|
403 *relationship_type = \&predicate_term;
|
|
|
404
|
|
|
405 1;
|
