2 # BioPerl module for Bio::Das::FeatureTypeI
4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
6 # Cared for by Lincoln Stein <lstein@cshl.org>
8 # Copyright Lincoln Stein
10 # You may distribute this module under the same terms as perl itself
12 # POD documentation - main docs before the code
16 Bio::Das::FeatureTypeI - Simple interface to Sequence Ontology feature types
20 # Get a Bio::Das::FeatureTypeI object from somewhere
21 $term = $db->fetch....
23 # Get the name of the term
24 $definition = $term->name;
26 # Get the accession of the term
27 $accession = $term->accession;
29 # Get the definition of the term
30 $definition = $term->definition;
32 # Get the parents of the term, optionally filtered by relationship
33 @parents = $term->parents($relationship);
35 # Get the children of the term, optionally filtered by relationship
36 @children = $term->children($relationship);
38 # Given a parent and child, returns their relationship, or undef if
39 # not directly related
40 $relationship = $parent->relationship($child);
42 # Return true if two terms are identical
43 $match = $term1->equals($term2);
45 # Return true if $term2 is a descendent of $term1, optionally
46 # filtering by relationship ("isa" assumed)
47 $match = $term1->is_descendent($term2,$relationship);
49 # Return true if $term2 is a parent of $term1, optionally
50 # filtering by relationship ("isa" assumed)
51 $match = $term1->is_parent($term2,$relationship);
53 # Return true if $term2 is equal to $term1 or if $term2 descends
54 # from term 1 via the "isa" relationship
55 $match = $term1->match($term2);
57 # Create a new term de novo
58 $term = Bio::Das::FeatureTypeI->new(-name => $name,
59 -accession => $accession,
60 -definition => $definition);
62 # Add a child to a term
63 $term1->add_child($term2,$relationship);
65 # Delete a child from a term
66 $term1->delete_child($term2);
70 Bio::Das::FeatureTypeI is an interface to the Gene Ontology
71 Consortium's Sequence Ontology (SO). The SO, like other ontologies,
72 is a directed acyclic graph in which a child node may have multiple
73 parents. The relationship between parent and child is one of a list
74 of relationships. The SO currently recognizes two relationships "isa"
77 The intent of this interface is to interoperate with older software
78 that uses bare strings to represent feature types. For this reason,
79 the interface overloads the stringify ("") and string equals (eq)
86 User feedback is an integral part of the evolution of this
87 and other Bioperl modules. Send your comments and suggestions preferably
88 to one of the Bioperl mailing lists.
89 Your participation is much appreciated.
91 bioperl-l@bio.perl.org
95 Please direct usage questions or support issues to the mailing list:
97 I<bioperl-l@bioperl.org>
99 rather than to the module maintainer directly. Many experienced and
100 reponsive experts will be able look at the problem and quickly
101 address it. Please include a thorough description of the problem
102 with code and data examples if at all possible.
104 =head2 Reporting Bugs
106 Report bugs to the Bioperl bug tracking system to help us keep track
107 the bugs and their resolution. Bug reports can be submitted via the
110 https://github.com/bioperl/bioperl-live/issues
112 =head1 AUTHOR - Lincoln Stein
114 Email lstein@cshl.org
118 The rest of the documentation details each of the object
119 methods. Internal methods are usually preceded with a _
124 # Let the code begin...
126 package Bio
::Das
::FeatureTypeI
;
130 use overload
'""' => 'name',
134 # Object preamble - inherits from Bio::Root::RootI;
138 this is somehow FUBAR, implementation classes cannot successfully inherit from Bio::Das::FeatureTypeI
142 use base
qw(Bio::Root::RootI);
147 Usage : $string = $term->name
148 Function: return the term for the type
155 sub name
{ shift->throw_not_implemented }
160 Usage : $string = $term->accession
161 Function: return the accession number for the term
168 sub accession
{ shift->throw_not_implemented }
173 Usage : $string = $term->definition
174 Function: return the human-readable definition for the term
181 sub definition
{ shift->throw_not_implemented }
186 Usage : @terms = $term->parents($relationship)
187 Function: return parent terms
188 Returns : list of Bio::Das::FeatureTypeI
192 Returns the parents for the current term, empty if there are none. An
193 optional relationship argument will return those parents
194 that are related via the specified relationship type.
196 The relationship is one of "isa" or "partof".
200 sub parents
{ shift->throw_not_implemented; }
205 Usage : @terms = $term->children($relationship)
206 Function: return children terms
207 Returns : list of Bio::Das::FeatureTypeI
211 Returns the children for the current term, empty if there are none. An
212 optional relationship argument will return those children
213 that are related via the specified relationship type.
215 The relationship is one of "isa" or "partof".
219 sub children
{ shift->throw_not_implemented; }
224 Usage : $relationship = $parent->relationship($child)
225 Function: return the relationship between a parent and a child
226 Returns : one of "isa" or "partof"
230 This method returns the relationship between a parent and one of its
231 immediate descendents. It can return "isa", "partof", or undef if
232 there is not a direct parent/child relationship (kissing cousins are
237 sub relationship
{ shift->throw_not_implemented }
242 Usage : $boolean = $term1->equals($term2)
243 Function: return true if $term1 and $term2 are the same
248 The two terms must be identical. In practice, this means that if
249 term2 is a Bio::Das::FeatureI object, then its accession number must
250 match the first term's accession number. Otherwise, if term2 is a
251 bare string, then it must equal (in a case insensitive manner)
254 NOTE TO IMPLEMENTORS: This method is defined in terms of other
255 methods, so does not need to be implemented.
263 if ($term2->isa('Bio::Das::FeatureTypeI')) {
264 return $self->accession eq $term2->accession;
266 return lc $self->name eq lc $term2;
272 Title : is_descendent
273 Usage : $boolean = $term1->is_descendent($term2 [,$relationship])
274 Function: return true of $term2 is a descendent of $term1
279 This method returns true if $term2 descends from $term1. The
280 operation traverses the tree. The traversal can be limited to the
281 relationship type ("isa" or "partof") if desired. $term2 can be a
282 bare string, in which case the term names will be used as the basis
283 for term matching (see equals()).
285 NOTE TO IMPLEMENTORS: this method is defined as the inverse of
286 is_parent(). Do not implement it directly, but do implement
293 my ($term,$relationship) = @_;
294 $self->throw("$term is not a Bio::Das::FeatureTypeI")
295 unless $term->isa('Bio::Das::FeatureTypeI');
296 $term->is_parent($self,$relationship);
302 Usage : $boolean = $term1->is_parent($term2 [,$relationship])
303 Function: return true of $term2 is a parent of $term1
308 This method returns true if $term2 is a parent of $term1. The
309 operation traverses the tree. The traversal can be limited to the
310 relationship type ("isa" or "partof") if desired. $term2 can be a
311 bare string, in which case the term names will be used as the basis
312 for term matching (see equals()).
314 NOTE TO IMPLEMENTORS: Implementing this method will also implement
319 sub is_parent
{ shift->throw_not_implemented }
324 Usage : $boolean = $term1->match($term2)
325 Function: return true if $term1 equals $term2 or if $term2 is an "isa" descendent
330 This method combines equals() and is_descendent() in such a way that
331 the two terms will match if they are the same or if the second term is
332 an instance of the first one. This is also the basis of the operator
335 NOTE TO IMPLEMENTORS: This method is defined in terms of other methods
336 and does not need to be implemented.
343 return 1 if $self->equals($term2);
344 return $self->is_descendent($term2,'isa');
350 Usage : $term = Bio::Das::FeatureTypeI->new(@args)
351 Function: create a new term
356 This method creates a new Bio::Das::FeatureTypeI. Arguments:
359 -------- ------------
361 -name Name of this term
363 -accession Accession number for the term
365 -definition Definition of the term
369 sub new
{ shift->throw_not_implemented }
374 Usage : $boolean = $term->add_child($term2,$relationship)
375 Function: add a child to a term
376 Returns : a boolean indicating success
378 Throws : a "cycle detected" exception
381 This method adds a new child to the indicated node. It may detect a
382 cycle in the DAG and throw a "cycle detected" exception.
386 sub add_child
{ shift->throw_not_implemented }
392 Usage : $boolean = $term->delete_child($term2);
393 Function: delete a child of the term
394 Returns : a boolean indicating success
395 Args : child to be deleted
396 Throws : a "not a child" exception
399 This method deletes a new child from the indicated node. It will
400 throw an exception if the indicated child is not a direct descendent.
404 sub delete_child
{ shift->throw_not_implemented }