| 1 | # | ||||||||||
| 2 | # BioPerl module for Bio::Das::FeatureTypeI | ||||||||||
| 3 | # | ||||||||||
| 4 | # Please direct questions and support issues to <bioperl-l@bioperl.org> | ||||||||||
| 5 | # | ||||||||||
| 6 | # Cared for by Lincoln Stein <lstein@cshl.org> | ||||||||||
| 7 | # | ||||||||||
| 8 | # Copyright Lincoln Stein | ||||||||||
| 9 | # | ||||||||||
| 10 | # You may distribute this module under the same terms as perl itself | ||||||||||
| 11 | |||||||||||
| 12 | # POD documentation - main docs before the code | ||||||||||
| 13 | |||||||||||
| 14 | =head1 NAME | ||||||||||
| 15 | |||||||||||
| 16 | Bio::Das::FeatureTypeI - Simple interface to Sequence Ontology feature types | ||||||||||
| 17 | |||||||||||
| 18 | =head1 SYNOPSIS | ||||||||||
| 19 | |||||||||||
| 20 | # Get a Bio::Das::FeatureTypeI object from somewhere | ||||||||||
| 21 | $term = $db->fetch.... | ||||||||||
| 22 | |||||||||||
| 23 | # Get the name of the term | ||||||||||
| 24 | $definition = $term->name; | ||||||||||
| 25 | |||||||||||
| 26 | # Get the accession of the term | ||||||||||
| 27 | $accession = $term->accession; | ||||||||||
| 28 | |||||||||||
| 29 | # Get the definition of the term | ||||||||||
| 30 | $definition = $term->definition; | ||||||||||
| 31 | |||||||||||
| 32 | # Get the parents of the term, optionally filtered by relationship | ||||||||||
| 33 | @parents = $term->parents($relationship); | ||||||||||
| 34 | |||||||||||
| 35 | # Get the children of the term, optionally filtered by relationship | ||||||||||
| 36 | @children = $term->children($relationship); | ||||||||||
| 37 | |||||||||||
| 38 | # Given a parent and child, returns their relationship, or undef if | ||||||||||
| 39 | # not directly related | ||||||||||
| 40 | $relationship = $parent->relationship($child); | ||||||||||
| 41 | |||||||||||
| 42 | # Return true if two terms are identical | ||||||||||
| 43 | $match = $term1->equals($term2); | ||||||||||
| 44 | |||||||||||
| 45 | # Return true if $term2 is a descendent of $term1, optionally | ||||||||||
| 46 | # filtering by relationship ("isa" assumed) | ||||||||||
| 47 | $match = $term1->is_descendent($term2,$relationship); | ||||||||||
| 48 | |||||||||||
| 49 | # Return true if $term2 is a parent of $term1, optionally | ||||||||||
| 50 | # filtering by relationship ("isa" assumed) | ||||||||||
| 51 | $match = $term1->is_parent($term2,$relationship); | ||||||||||
| 52 | |||||||||||
| 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); | ||||||||||
| 56 | |||||||||||
| 57 | # Create a new term de novo | ||||||||||
| 58 | $term = Bio::Das::FeatureTypeI->new(-name => $name, | ||||||||||
| 59 | -accession => $accession, | ||||||||||
| 60 | -definition => $definition); | ||||||||||
| 61 | |||||||||||
| 62 | # Add a child to a term | ||||||||||
| 63 | $term1->add_child($term2,$relationship); | ||||||||||
| 64 | |||||||||||
| 65 | # Delete a child from a term | ||||||||||
| 66 | $term1->delete_child($term2); | ||||||||||
| 67 | |||||||||||
| 68 | =head1 DESCRIPTION | ||||||||||
| 69 | |||||||||||
| 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". | ||||||||||
| 76 | |||||||||||
| 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. | ||||||||||
| 81 | |||||||||||
| 82 | =head1 FEEDBACK | ||||||||||
| 83 | |||||||||||
| 84 | =head2 Mailing Lists | ||||||||||
| 85 | |||||||||||
| 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. | ||||||||||
| 90 | |||||||||||
| 91 | bioperl-l@bio.perl.org | ||||||||||
| 92 | |||||||||||
| 93 | =head2 Support | ||||||||||
| 94 | |||||||||||
| 95 | Please direct usage questions or support issues to the mailing list: | ||||||||||
| 96 | |||||||||||
| 97 | I<bioperl-l@bioperl.org> | ||||||||||
| 98 | |||||||||||
| 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. | ||||||||||
| 103 | |||||||||||
| 104 | =head2 Reporting Bugs | ||||||||||
| 105 | |||||||||||
| 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: | ||||||||||
| 109 | |||||||||||
| 110 | https://github.com/bioperl/bioperl-live/issues | ||||||||||
| 111 | |||||||||||
| 112 | =head1 AUTHOR - Lincoln Stein | ||||||||||
| 113 | |||||||||||
| 114 | Email lstein@cshl.org | ||||||||||
| 115 | |||||||||||
| 116 | =head1 APPENDIX | ||||||||||
| 117 | |||||||||||
| 118 | The rest of the documentation details each of the object | ||||||||||
| 119 | methods. Internal methods are usually preceded with a _ | ||||||||||
| 120 | |||||||||||
| 121 | =cut | ||||||||||
| 122 | |||||||||||
| 123 | #' | ||||||||||
| 124 | # Let the code begin... | ||||||||||
| 125 | |||||||||||
| 126 | package Bio::Das::FeatureTypeI; | ||||||||||
| 127 | 1 | $Bio::Das::FeatureTypeI::VERSION = '1.7.8'; | |||||||||
| 128 | 1 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 129 | |||||||||||
| 130 | 1 | ▶ | use overload '""' => 'name', | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 131 | eq => 'match', | ||||||||||
| 132 | 1 | fallback => 1; | |||||||||
| 133 | |||||||||||
| 134 | # Object preamble - inherits from Bio::Root::RootI; | ||||||||||
| 135 | |||||||||||
| 136 | =pod | ||||||||||
| 137 | |||||||||||
| 138 | this is somehow FUBAR, implementation classes cannot successfully inherit from Bio::Das::FeatureTypeI | ||||||||||
| 139 | |||||||||||
| 140 | =cut | ||||||||||
| 141 | |||||||||||
| 142 | 1 | ▶ | use base qw(Bio::Root::RootI); | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 143 | |||||||||||
| 144 | =head2 name | ||||||||||
| 145 | |||||||||||
| 146 | Title : name | ||||||||||
| 147 | Usage : $string = $term->name | ||||||||||
| 148 | Function: return the term for the type | ||||||||||
| 149 | Returns : a string | ||||||||||
| 150 | Args : none | ||||||||||
| 151 | Status : Public | ||||||||||
| 152 | |||||||||||
| 153 | =cut | ||||||||||
| 154 | |||||||||||
| 155 | 0 | ▶ | sub name { shift->throw_not_implemented } | ||||||||
|
Subroutine
name: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 156 | |||||||||||
| 157 | =head2 accession | ||||||||||
| 158 | |||||||||||
| 159 | Title : accession | ||||||||||
| 160 | Usage : $string = $term->accession | ||||||||||
| 161 | Function: return the accession number for the term | ||||||||||
| 162 | Returns : a string | ||||||||||
| 163 | Args : none | ||||||||||
| 164 | Status : Public | ||||||||||
| 165 | |||||||||||
| 166 | =cut | ||||||||||
| 167 | |||||||||||
| 168 | 0 | ▶ | sub accession { shift->throw_not_implemented } | ||||||||
|
Subroutine
accession: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 169 | |||||||||||
| 170 | =head2 definition | ||||||||||
| 171 | |||||||||||
| 172 | Title : definition | ||||||||||
| 173 | Usage : $string = $term->definition | ||||||||||
| 174 | Function: return the human-readable definition for the term | ||||||||||
| 175 | Returns : a string | ||||||||||
| 176 | Args : none | ||||||||||
| 177 | Status : Public | ||||||||||
| 178 | |||||||||||
| 179 | =cut | ||||||||||
| 180 | |||||||||||
| 181 | 0 | ▶ | sub definition { shift->throw_not_implemented } | ||||||||
|
Subroutine
definition: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 182 | |||||||||||
| 183 | =head2 parents | ||||||||||
| 184 | |||||||||||
| 185 | Title : parents | ||||||||||
| 186 | Usage : @terms = $term->parents($relationship) | ||||||||||
| 187 | Function: return parent terms | ||||||||||
| 188 | Returns : list of Bio::Das::FeatureTypeI | ||||||||||
| 189 | Args : none | ||||||||||
| 190 | Status : Public | ||||||||||
| 191 | |||||||||||
| 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. | ||||||||||
| 195 | |||||||||||
| 196 | The relationship is one of "isa" or "partof". | ||||||||||
| 197 | |||||||||||
| 198 | =cut | ||||||||||
| 199 | |||||||||||
| 200 | 0 | ▶ | sub parents { shift->throw_not_implemented; } | ||||||||
|
Subroutine
parents: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 201 | |||||||||||
| 202 | =head2 children | ||||||||||
| 203 | |||||||||||
| 204 | Title : children | ||||||||||
| 205 | Usage : @terms = $term->children($relationship) | ||||||||||
| 206 | Function: return children terms | ||||||||||
| 207 | Returns : list of Bio::Das::FeatureTypeI | ||||||||||
| 208 | Args : none | ||||||||||
| 209 | Status : Public | ||||||||||
| 210 | |||||||||||
| 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. | ||||||||||
| 214 | |||||||||||
| 215 | The relationship is one of "isa" or "partof". | ||||||||||
| 216 | |||||||||||
| 217 | =cut | ||||||||||
| 218 | |||||||||||
| 219 | 0 | ▶ | sub children { shift->throw_not_implemented; } | ||||||||
|
Subroutine
children: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 220 | |||||||||||
| 221 | =head2 relationship | ||||||||||
| 222 | |||||||||||
| 223 | Title : relationship | ||||||||||
| 224 | Usage : $relationship = $parent->relationship($child) | ||||||||||
| 225 | Function: return the relationship between a parent and a child | ||||||||||
| 226 | Returns : one of "isa" or "partof" | ||||||||||
| 227 | Args : none | ||||||||||
| 228 | Status : Public | ||||||||||
| 229 | |||||||||||
| 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 | ||||||||||
| 233 | *not* recognized). | ||||||||||
| 234 | |||||||||||
| 235 | =cut | ||||||||||
| 236 | |||||||||||
| 237 | 0 | ▶ | sub relationship { shift->throw_not_implemented } | ||||||||
|
Subroutine
relationship: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 238 | |||||||||||
| 239 | =head2 equals | ||||||||||
| 240 | |||||||||||
| 241 | Title : equals | ||||||||||
| 242 | Usage : $boolean = $term1->equals($term2) | ||||||||||
| 243 | Function: return true if $term1 and $term2 are the same | ||||||||||
| 244 | Returns : boolean | ||||||||||
| 245 | Args : second term | ||||||||||
| 246 | Status : Public | ||||||||||
| 247 | |||||||||||
| 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) | ||||||||||
| 252 | the name of term1. | ||||||||||
| 253 | |||||||||||
| 254 | NOTE TO IMPLEMENTORS: This method is defined in terms of other | ||||||||||
| 255 | methods, so does not need to be implemented. | ||||||||||
| 256 | |||||||||||
| 257 | =cut | ||||||||||
| 258 | |||||||||||
| 259 | #' | ||||||||||
| 260 | 0 | ▶ | sub equals { | ||||||||
|
Subroutine
equals: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 261 | 0 | my $self = shift; | |||||||||
| 262 | 0 | my $term2 = shift; | |||||||||
| 263 | 0 | ▶ | if ($term2->isa('Bio::Das::FeatureTypeI')) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 264 | 0 | return $self->accession eq $term2->accession; | |||||||||
| 265 | } else { | ||||||||||
| 266 | 0 | return lc $self->name eq lc $term2; | |||||||||
| 267 | } | ||||||||||
| 268 | } | ||||||||||
| 269 | |||||||||||
| 270 | =head2 is_descendent | ||||||||||
| 271 | |||||||||||
| 272 | Title : is_descendent | ||||||||||
| 273 | Usage : $boolean = $term1->is_descendent($term2 [,$relationship]) | ||||||||||
| 274 | Function: return true of $term2 is a descendent of $term1 | ||||||||||
| 275 | Returns : boolean | ||||||||||
| 276 | Args : second term | ||||||||||
| 277 | Status : Public | ||||||||||
| 278 | |||||||||||
| 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()). | ||||||||||
| 284 | |||||||||||
| 285 | NOTE TO IMPLEMENTORS: this method is defined as the inverse of | ||||||||||
| 286 | is_parent(). Do not implement it directly, but do implement | ||||||||||
| 287 | is_parent(). | ||||||||||
| 288 | |||||||||||
| 289 | =cut | ||||||||||
| 290 | |||||||||||
| 291 | 0 | ▶ | sub is_descendent { | ||||||||
|
Subroutine
is_descendent: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 292 | 0 | my $self = shift; | |||||||||
| 293 | 0 | my ($term,$relationship) = @_; | |||||||||
| 294 | 0 | ▶ | $self->throw("$term is not a Bio::Das::FeatureTypeI") | ||||||||
|
Branch: 1 branch
| |||||||||||
| 295 | unless $term->isa('Bio::Das::FeatureTypeI'); | ||||||||||
| 296 | 0 | $term->is_parent($self,$relationship); | |||||||||
| 297 | } | ||||||||||
| 298 | |||||||||||
| 299 | =head2 is_parent | ||||||||||
| 300 | |||||||||||
| 301 | Title : is_parent | ||||||||||
| 302 | Usage : $boolean = $term1->is_parent($term2 [,$relationship]) | ||||||||||
| 303 | Function: return true of $term2 is a parent of $term1 | ||||||||||
| 304 | Returns : boolean | ||||||||||
| 305 | Args : second term | ||||||||||
| 306 | Status : Public | ||||||||||
| 307 | |||||||||||
| 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()). | ||||||||||
| 313 | |||||||||||
| 314 | NOTE TO IMPLEMENTORS: Implementing this method will also implement | ||||||||||
| 315 | is_descendent(). | ||||||||||
| 316 | |||||||||||
| 317 | =cut | ||||||||||
| 318 | |||||||||||
| 319 | 0 | ▶ | sub is_parent { shift->throw_not_implemented } | ||||||||
|
Subroutine
is_parent: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 320 | |||||||||||
| 321 | =head2 match | ||||||||||
| 322 | |||||||||||
| 323 | Title : match | ||||||||||
| 324 | Usage : $boolean = $term1->match($term2) | ||||||||||
| 325 | Function: return true if $term1 equals $term2 or if $term2 is an "isa" descendent | ||||||||||
| 326 | Returns : boolean | ||||||||||
| 327 | Args : second term | ||||||||||
| 328 | Status : Public | ||||||||||
| 329 | |||||||||||
| 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 | ||||||||||
| 333 | overloading of eq. | ||||||||||
| 334 | |||||||||||
| 335 | NOTE TO IMPLEMENTORS: This method is defined in terms of other methods | ||||||||||
| 336 | and does not need to be implemented. | ||||||||||
| 337 | |||||||||||
| 338 | =cut | ||||||||||
| 339 | |||||||||||
| 340 | 0 | ▶ | sub match { | ||||||||
|
Subroutine
match: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||
| 341 | 0 | my $self = shift; | |||||||||
| 342 | 0 | my $term2 = shift; | |||||||||
| 343 | 0 | ▶ | return 1 if $self->equals($term2); | ||||||||
|
Branch: 1 branch
| |||||||||||
| 344 | 0 | return $self->is_descendent($term2,'isa'); | |||||||||
| 345 | } | ||||||||||
| 346 | |||||||||||
| 347 | =head2 new | ||||||||||
| 348 | |||||||||||
| 349 | Title : new | ||||||||||
| 350 | Usage : $term = Bio::Das::FeatureTypeI->new(@args) | ||||||||||
| 351 | Function: create a new term | ||||||||||
| 352 | Returns : new term | ||||||||||
| 353 | Args : see below | ||||||||||
| 354 | Status : Public | ||||||||||
| 355 | |||||||||||
| 356 | This method creates a new Bio::Das::FeatureTypeI. Arguments: | ||||||||||
| 357 | |||||||||||
| 358 | Argument Description | ||||||||||
| 359 | -------- ------------ | ||||||||||
| 360 | |||||||||||
| 361 | -name Name of this term | ||||||||||
| 362 | |||||||||||
| 363 | -accession Accession number for the term | ||||||||||
| 364 | |||||||||||
| 365 | -definition Definition of the term | ||||||||||
| 366 | |||||||||||
| 367 | =cut | ||||||||||
| 368 | |||||||||||
| 369 | 0 | ▶ | sub new { shift->throw_not_implemented } | ||||||||
|
Subroutine
new: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 370 | |||||||||||
| 371 | =head2 add_child | ||||||||||
| 372 | |||||||||||
| 373 | Title : add_child | ||||||||||
| 374 | Usage : $boolean = $term->add_child($term2,$relationship) | ||||||||||
| 375 | Function: add a child to a term | ||||||||||
| 376 | Returns : a boolean indicating success | ||||||||||
| 377 | Args : new child | ||||||||||
| 378 | Throws : a "cycle detected" exception | ||||||||||
| 379 | Status : Public | ||||||||||
| 380 | |||||||||||
| 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. | ||||||||||
| 383 | |||||||||||
| 384 | =cut | ||||||||||
| 385 | |||||||||||
| 386 | 0 | ▶ | sub add_child { shift->throw_not_implemented } | ||||||||
|
Subroutine
add_child: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 387 | |||||||||||
| 388 | |||||||||||
| 389 | =head2 delete_child | ||||||||||
| 390 | |||||||||||
| 391 | Title : delete_child | ||||||||||
| 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 | ||||||||||
| 397 | Status : Public | ||||||||||
| 398 | |||||||||||
| 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. | ||||||||||
| 401 | |||||||||||
| 402 | =cut | ||||||||||
| 403 | |||||||||||
| 404 | 0 | ▶ | sub delete_child { shift->throw_not_implemented } | ||||||||
|
Subroutine
delete_child: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||
| 405 | |||||||||||
| 406 | 1 | 1; | |||||||||