maint: restructure to use Dist::Zilla
[bioperl-live.git] / lib / Bio / Das / FeatureTypeI.pm
blob0e0e835be930ec7a26dd8ada03485f53d3bcb88b
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
14 =head1 NAME
16 Bio::Das::FeatureTypeI - Simple interface to Sequence Ontology feature types
18 =head1 SYNOPSIS
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);
68 =head1 DESCRIPTION
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"
75 and "partof".
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)
80 operations.
82 =head1 FEEDBACK
84 =head2 Mailing Lists
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
93 =head2 Support
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
108 web:
110 https://github.com/bioperl/bioperl-live/issues
112 =head1 AUTHOR - Lincoln Stein
114 Email lstein@cshl.org
116 =head1 APPENDIX
118 The rest of the documentation details each of the object
119 methods. Internal methods are usually preceded with a _
121 =cut
124 # Let the code begin...
126 package Bio::Das::FeatureTypeI;
127 use strict;
129 use overload '""' => 'name',
130 eq => 'match',
131 fallback => 1;
133 # Object preamble - inherits from Bio::Root::RootI;
135 =pod
137 this is somehow FUBAR, implementation classes cannot successfully inherit from Bio::Das::FeatureTypeI
139 =cut
141 use base qw(Bio::Root::RootI);
143 =head2 name
145 Title : name
146 Usage : $string = $term->name
147 Function: return the term for the type
148 Returns : a string
149 Args : none
150 Status : Public
152 =cut
154 sub name { shift->throw_not_implemented }
156 =head2 accession
158 Title : accession
159 Usage : $string = $term->accession
160 Function: return the accession number for the term
161 Returns : a string
162 Args : none
163 Status : Public
165 =cut
167 sub accession { shift->throw_not_implemented }
169 =head2 definition
171 Title : definition
172 Usage : $string = $term->definition
173 Function: return the human-readable definition for the term
174 Returns : a string
175 Args : none
176 Status : Public
178 =cut
180 sub definition { shift->throw_not_implemented }
182 =head2 parents
184 Title : parents
185 Usage : @terms = $term->parents($relationship)
186 Function: return parent terms
187 Returns : list of Bio::Das::FeatureTypeI
188 Args : none
189 Status : Public
191 Returns the parents for the current term, empty if there are none. An
192 optional relationship argument will return those parents
193 that are related via the specified relationship type.
195 The relationship is one of "isa" or "partof".
197 =cut
199 sub parents { shift->throw_not_implemented; }
201 =head2 children
203 Title : children
204 Usage : @terms = $term->children($relationship)
205 Function: return children terms
206 Returns : list of Bio::Das::FeatureTypeI
207 Args : none
208 Status : Public
210 Returns the children for the current term, empty if there are none. An
211 optional relationship argument will return those children
212 that are related via the specified relationship type.
214 The relationship is one of "isa" or "partof".
216 =cut
218 sub children { shift->throw_not_implemented; }
220 =head2 relationship
222 Title : relationship
223 Usage : $relationship = $parent->relationship($child)
224 Function: return the relationship between a parent and a child
225 Returns : one of "isa" or "partof"
226 Args : none
227 Status : Public
229 This method returns the relationship between a parent and one of its
230 immediate descendents. It can return "isa", "partof", or undef if
231 there is not a direct parent/child relationship (kissing cousins are
232 *not* recognized).
234 =cut
236 sub relationship { shift->throw_not_implemented }
238 =head2 equals
240 Title : equals
241 Usage : $boolean = $term1->equals($term2)
242 Function: return true if $term1 and $term2 are the same
243 Returns : boolean
244 Args : second term
245 Status : Public
247 The two terms must be identical. In practice, this means that if
248 term2 is a Bio::Das::FeatureI object, then its accession number must
249 match the first term's accession number. Otherwise, if term2 is a
250 bare string, then it must equal (in a case insensitive manner)
251 the name of term1.
253 NOTE TO IMPLEMENTORS: This method is defined in terms of other
254 methods, so does not need to be implemented.
256 =cut
259 sub equals {
260 my $self = shift;
261 my $term2 = shift;
262 if ($term2->isa('Bio::Das::FeatureTypeI')) {
263 return $self->accession eq $term2->accession;
264 } else {
265 return lc $self->name eq lc $term2;
269 =head2 is_descendent
271 Title : is_descendent
272 Usage : $boolean = $term1->is_descendent($term2 [,$relationship])
273 Function: return true of $term2 is a descendent of $term1
274 Returns : boolean
275 Args : second term
276 Status : Public
278 This method returns true if $term2 descends from $term1. The
279 operation traverses the tree. The traversal can be limited to the
280 relationship type ("isa" or "partof") if desired. $term2 can be a
281 bare string, in which case the term names will be used as the basis
282 for term matching (see equals()).
284 NOTE TO IMPLEMENTORS: this method is defined as the inverse of
285 is_parent(). Do not implement it directly, but do implement
286 is_parent().
288 =cut
290 sub is_descendent {
291 my $self = shift;
292 my ($term,$relationship) = @_;
293 $self->throw("$term is not a Bio::Das::FeatureTypeI")
294 unless $term->isa('Bio::Das::FeatureTypeI');
295 $term->is_parent($self,$relationship);
298 =head2 is_parent
300 Title : is_parent
301 Usage : $boolean = $term1->is_parent($term2 [,$relationship])
302 Function: return true of $term2 is a parent of $term1
303 Returns : boolean
304 Args : second term
305 Status : Public
307 This method returns true if $term2 is a parent of $term1. The
308 operation traverses the tree. The traversal can be limited to the
309 relationship type ("isa" or "partof") if desired. $term2 can be a
310 bare string, in which case the term names will be used as the basis
311 for term matching (see equals()).
313 NOTE TO IMPLEMENTORS: Implementing this method will also implement
314 is_descendent().
316 =cut
318 sub is_parent { shift->throw_not_implemented }
320 =head2 match
322 Title : match
323 Usage : $boolean = $term1->match($term2)
324 Function: return true if $term1 equals $term2 or if $term2 is an "isa" descendent
325 Returns : boolean
326 Args : second term
327 Status : Public
329 This method combines equals() and is_descendent() in such a way that
330 the two terms will match if they are the same or if the second term is
331 an instance of the first one. This is also the basis of the operator
332 overloading of eq.
334 NOTE TO IMPLEMENTORS: This method is defined in terms of other methods
335 and does not need to be implemented.
337 =cut
339 sub match {
340 my $self = shift;
341 my $term2 = shift;
342 return 1 if $self->equals($term2);
343 return $self->is_descendent($term2,'isa');
346 =head2 new
348 Title : new
349 Usage : $term = Bio::Das::FeatureTypeI->new(@args)
350 Function: create a new term
351 Returns : new term
352 Args : see below
353 Status : Public
355 This method creates a new Bio::Das::FeatureTypeI. Arguments:
357 Argument Description
358 -------- ------------
360 -name Name of this term
362 -accession Accession number for the term
364 -definition Definition of the term
366 =cut
368 sub new { shift->throw_not_implemented }
370 =head2 add_child
372 Title : add_child
373 Usage : $boolean = $term->add_child($term2,$relationship)
374 Function: add a child to a term
375 Returns : a boolean indicating success
376 Args : new child
377 Throws : a "cycle detected" exception
378 Status : Public
380 This method adds a new child to the indicated node. It may detect a
381 cycle in the DAG and throw a "cycle detected" exception.
383 =cut
385 sub add_child { shift->throw_not_implemented }
388 =head2 delete_child
390 Title : delete_child
391 Usage : $boolean = $term->delete_child($term2);
392 Function: delete a child of the term
393 Returns : a boolean indicating success
394 Args : child to be deleted
395 Throws : a "not a child" exception
396 Status : Public
398 This method deletes a new child from the indicated node. It will
399 throw an exception if the indicated child is not a direct descendent.
401 =cut
403 sub delete_child { shift->throw_not_implemented }