Bio/Das/FeatureTypeI.pm

   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://redmine.open-bio.org/projects/bioperl/
 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 use strict;
 128
 129 use overload '""'     => 'name',
 130              eq       => 'match',
 131              fallback => 1;
 132
 133 # Object preamble - inherits from Bio::Root::RootI;
 134
 135 =pod
 136
 137 this is somehow FUBAR, implementation classes cannot successfully inherit from Bio::Das::FeatureTypeI
 138
 139 =cut
 140
 141 use base qw(Bio::Root::RootI);
 142
 143 =head2 name
 144
 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
 151
 152 =cut
 153
 154 sub name { shift->throw_not_implemented }
 155
 156 =head2 accession
 157
 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
 164
 165 =cut
 166
 167 sub accession  { shift->throw_not_implemented }
 168
 169 =head2 definition
 170
 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
 177
 178 =cut
 179
 180 sub definition  { shift->throw_not_implemented  }
 181
 182 =head2 parents
 183
 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
 190
 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.
 194
 195 The relationship is one of "isa" or "partof".
 196
 197 =cut
 198
 199 sub parents { shift->throw_not_implemented; }
 200
 201 =head2 children
 202
 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
 209
 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.
 213
 214 The relationship is one of "isa" or "partof".
 215
 216 =cut
 217
 218 sub children { shift->throw_not_implemented; }
 219
 220 =head2 relationship
 221
 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
 228
 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).
 233
 234 =cut
 235
 236 sub relationship { shift->throw_not_implemented }
 237
 238 =head2 equals
 239
 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
 246
 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.
 252
 253 NOTE TO IMPLEMENTORS: This method is defined in terms of other
 254 methods, so does not need to be implemented.
 255
 256 =cut
 257
 258 #'
 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;
 266   }
 267 }
 268
 269 =head2 is_descendent
 270
 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
 277
 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()).
 283
 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().
 287
 288 =cut
 289
 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);
 296 }
 297
 298 =head2 is_parent
 299
 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
 306
 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()).
 312
 313 NOTE TO IMPLEMENTORS: Implementing this method will also implement
 314 is_descendent().
 315
 316 =cut
 317
 318 sub is_parent { shift->throw_not_implemented }
 319
 320 =head2 match
 321
 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
 328
 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.
 333
 334 NOTE TO IMPLEMENTORS: This method is defined in terms of other methods
 335 and does not need to be implemented.
 336
 337 =cut
 338
 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');
 344 }
 345
 346 =head2 new
 347
 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
 354
 355 This method creates a new Bio::Das::FeatureTypeI.  Arguments:
 356
 357   Argument    Description
 358   --------   ------------
 359
 360   -name       Name of this term
 361
 362   -accession  Accession number for the term
 363
 364   -definition Definition of the term
 365
 366 =cut
 367
 368 sub new { shift->throw_not_implemented }
 369
 370 =head2 add_child
 371
 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
 379
 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.
 382
 383 =cut
 384
 385 sub add_child { shift->throw_not_implemented }
 386
 387
 388 =head2 delete_child
 389
 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
 397
 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.
 400
 401 =cut
 402
 403 sub delete_child { shift->throw_not_implemented }
 404
 405 1;