branch-1-6/Bio/Das/FeatureTypeI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Das::FeatureTypeI
   4 #
   5 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   6 #
   7 # Cared for by Lincoln Stein <lstein@cshl.org>
   8 #
   9 # Copyright Lincoln Stein
  10 #
  11 # You may distribute this module under the same terms as perl itself
  12
  13 # POD documentation - main docs before the code
  14
  15 =head1 NAME
  16
  17 Bio::Das::FeatureTypeI - Simple interface to Sequence Ontology feature types
  18
  19 =head1 SYNOPSIS
  20
  21   # Get a Bio::Das::FeatureTypeI object from somewhere
  22   $term = $db->fetch....
  23
  24   # Get the name of the term
  25   $definition = $term->name;
  26
  27   # Get the accession of the term
  28   $accession = $term->accession;
  29
  30   # Get the definition of the term
  31   $definition = $term->definition;
  32
  33   # Get the parents of the term, optionally filtered by relationship
  34   @parents = $term->parents($relationship);
  35
  36   # Get the children of the term, optionally filtered by relationship
  37   @children = $term->children($relationship);
  38
  39   # Given a parent and child, returns their relationship, or undef if
  40   # not directly related
  41   $relationship = $parent->relationship($child);
  42
  43   # Return true if two terms are identical
  44   $match = $term1->equals($term2);
  45
  46   # Return true if $term2 is a descendent of $term1, optionally
  47   # filtering by relationship ("isa" assumed)
  48   $match = $term1->is_descendent($term2,$relationship);
  49
  50   # Return true if $term2 is a parent of $term1, optionally
  51   # filtering by relationship ("isa" assumed)
  52   $match = $term1->is_parent($term2,$relationship);
  53
  54   # Return true if $term2 is equal to $term1 or if $term2 descends
  55   # from term 1 via the "isa" relationship
  56   $match = $term1->match($term2);
  57
  58   # Create a new term de novo
  59   $term = Bio::Das::FeatureTypeI->new(-name       => $name,
  60                                       -accession  => $accession,
  61                                       -definition => $definition);
  62
  63   # Add a child to a term
  64   $term1->add_child($term2,$relationship);
  65
  66   # Delete a child from a term
  67   $term1->delete_child($term2);
  68
  69 =head1 DESCRIPTION
  70
  71 Bio::Das::FeatureTypeI is an interface to the Gene Ontology
  72 Consortium's Sequence Ontology (SO).  The SO, like other ontologies,
  73 is a directed acyclic graph in which a child node may have multiple
  74 parents.  The relationship between parent and child is one of a list
  75 of relationships.  The SO currently recognizes two relationships "isa"
  76 and "partof".
  77
  78 The intent of this interface is to interoperate with older software
  79 that uses bare strings to represent feature types.  For this reason,
  80 the interface overloads the stringify ("") and string equals (eq)
  81 operations.
  82
  83 =head1 FEEDBACK
  84
  85 =head2 Mailing Lists
  86
  87 User feedback is an integral part of the evolution of this
  88 and other Bioperl modules. Send your comments and suggestions preferably
  89  to one of the Bioperl mailing lists.
  90 Your participation is much appreciated.
  91
  92   bioperl-l@bio.perl.org
  93
  94 =head2 Support
  95
  96 Please direct usage questions or support issues to the mailing list:
  97
  98 I<bioperl-l@bioperl.org>
  99
 100 rather than to the module maintainer directly. Many experienced and
 101 reponsive experts will be able look at the problem and quickly
 102 address it. Please include a thorough description of the problem
 103 with code and data examples if at all possible.
 104
 105 =head2 Reporting Bugs
 106
 107 Report bugs to the Bioperl bug tracking system to help us keep track
 108 the bugs and their resolution.  Bug reports can be submitted via the
 109 web:
 110
 111   http://bugzilla.open-bio.org/
 112
 113 =head1 AUTHOR - Lincoln Stein
 114
 115 Email lstein@cshl.org
 116
 117 =head1 APPENDIX
 118
 119 The rest of the documentation details each of the object
 120 methods. Internal methods are usually preceded with a _
 121
 122 =cut
 123
 124 #'
 125 # Let the code begin...
 126
 127 package Bio::Das::FeatureTypeI;
 128 use strict;
 129
 130 use overload '""'     => 'name',
 131              eq       => 'match',
 132              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 use base qw(Bio::Root::RootI);
 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 sub name { shift->throw_not_implemented }
 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 sub accession  { shift->throw_not_implemented }
 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 sub definition  { shift->throw_not_implemented  }
 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 sub parents { shift->throw_not_implemented; }
 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 sub children { shift->throw_not_implemented; }
 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 sub relationship { shift->throw_not_implemented }
 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 sub equals {
 261   my $self = shift;
 262   my $term2 = shift;
 263   if ($term2->isa('Bio::Das::FeatureTypeI')) {
 264     return $self->accession eq $term2->accession;
 265   } else {
 266     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 sub is_descendent {
 292   my $self = shift;
 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);
 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 sub is_parent { shift->throw_not_implemented }
 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 sub match {
 341   my $self  = shift;
 342   my $term2 = shift;
 343   return 1 if $self->equals($term2);
 344   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 sub new { shift->throw_not_implemented }
 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 sub add_child { shift->throw_not_implemented }
 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 sub delete_child { shift->throw_not_implemented }
 405
 406 1;