Bio/Das/FeatureTypeI.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Das::FeatureTypeI
   4 #
   5 # Cared for by Lincoln Stein <lstein@cshl.org>
   6 #
   7 # Copyright Lincoln Stein
   8 #
   9 # You may distribute this module under the same terms as perl itself
  10
  11 # POD documentation - main docs before the code
  12
  13 =head1 NAME
  14
  15 Bio::Das::FeatureTypeI - Simple interface to Sequence Ontology feature types
  16
  17 =head1 SYNOPSIS
  18
  19   # Get a Bio::Das::FeatureTypeI object from somewhere
  20   $term = $db->fetch....
  21
  22   # Get the name of the term
  23   $definition = $term->name;
  24
  25   # Get the accession of the term
  26   $accession = $term->accession;
  27
  28   # Get the definition of the term
  29   $definition = $term->definition;
  30
  31   # Get the parents of the term, optionally filtered by relationship
  32   @parents = $term->parents($relationship);
  33
  34   # Get the children of the term, optionally filtered by relationship
  35   @children = $term->children($relationship);
  36
  37   # Given a parent and child, returns their relationship, or undef if
  38   # not directly related
  39   $relationship = $parent->relationship($child);
  40
  41   # Return true if two terms are identical
  42   $match = $term1->equals($term2);
  43
  44   # Return true if $term2 is a descendent of $term1, optionally
  45   # filtering by relationship ("isa" assumed)
  46   $match = $term1->is_descendent($term2,$relationship);
  47
  48   # Return true if $term2 is a parent of $term1, optionally
  49   # filtering by relationship ("isa" assumed)
  50   $match = $term1->is_parent($term2,$relationship);
  51
  52   # Return true if $term2 is equal to $term1 or if $term2 descends
  53   # from term 1 via the "isa" relationship
  54   $match = $term1->match($term2);
  55
  56   # Create a new term de novo
  57   $term = Bio::Das::FeatureTypeI->new(-name       => $name,
  58                                       -accession  => $accession,
  59                                       -definition => $definition);
  60
  61   # Add a child to a term
  62   $term1->add_child($term2,$relationship);
  63
  64   # Delete a child from a term
  65   $term1->delete_child($term2);
  66
  67 =head1 DESCRIPTION
  68
  69 Bio::Das::FeatureTypeI is an interface to the Gene Ontology
  70 Consortium's Sequence Ontology (SO).  The SO, like other ontologies,
  71 is a directed acyclic graph in which a child node may have multiple
  72 parents.  The relationship between parent and child is one of a list
  73 of relationships.  The SO currently recognizes two relationships "isa"
  74 and "partof".
  75
  76 The intent of this interface is to interoperate with older software
  77 that uses bare strings to represent feature types.  For this reason,
  78 the interface overloads the stringify ("") and string equals (eq)
  79 operations.
  80
  81 =head1 FEEDBACK
  82
  83 =head2 Mailing Lists
  84
  85 User feedback is an integral part of the evolution of this
  86 and other Bioperl modules. Send your comments and suggestions preferably
  87  to one of the Bioperl mailing lists.
  88 Your participation is much appreciated.
  89
  90   bioperl-l@bio.perl.org
  91
  92 =head2 Reporting Bugs
  93
  94 Report bugs to the Bioperl bug tracking system to help us keep track
  95 the bugs and their resolution.  Bug reports can be submitted via the
  96 web:
  97
  98   http://bugzilla.open-bio.org/
  99
 100 =head1 AUTHOR - Lincoln Stein
 101
 102 Email lstein@cshl.org
 103
 104 =head1 APPENDIX
 105
 106 The rest of the documentation details each of the object
 107 methods. Internal methods are usually preceded with a _
 108
 109 =cut
 110
 111 #'
 112 # Let the code begin...
 113
 114 package Bio::Das::FeatureTypeI;
 115 use strict;
 116
 117 use overload '""'     => 'name',
 118              eq       => 'match',
 119              fallback => 1;
 120
 121 # Object preamble - inherits from Bio::Root::RootI;
 122
 123 =pod
 124
 125 this is somehow FUBAR, implementation classes cannot successfully inherit from Bio::Das::FeatureTypeI
 126
 127 =cut
 128
 129 use base qw(Bio::Root::RootI);
 130
 131 =head2 name
 132
 133  Title   : name
 134  Usage   : $string = $term->name
 135  Function: return the term for the type
 136  Returns : a string
 137  Args    : none
 138  Status  : Public
 139
 140 =cut
 141
 142 sub name { shift->throw_not_implemented }
 143
 144 =head2 accession
 145
 146  Title   : accession
 147  Usage   : $string = $term->accession
 148  Function: return the accession number for the term
 149  Returns : a string
 150  Args    : none
 151  Status  : Public
 152
 153 =cut
 154
 155 sub accession  { shift->throw_not_implemented }
 156
 157 =head2 definition
 158
 159  Title   : definition
 160  Usage   : $string = $term->definition
 161  Function: return the human-readable definition for the term
 162  Returns : a string
 163  Args    : none
 164  Status  : Public
 165
 166 =cut
 167
 168 sub definition  { shift->throw_not_implemented  }
 169
 170 =head2 parents
 171
 172  Title   : parents
 173  Usage   : @terms = $term->parents($relationship)
 174  Function: return parent terms
 175  Returns : list of Bio::Das::FeatureTypeI
 176  Args    : none
 177  Status  : Public
 178
 179 Returns the parents for the current term, empty if there are none.  An
 180 optional relationship argument will return those parents
 181 that are related via the specified relationship type.
 182
 183 The relationship is one of "isa" or "partof".
 184
 185 =cut
 186
 187 sub parents { shift->throw_not_implemented; }
 188
 189 =head2 children
 190
 191  Title   : children
 192  Usage   : @terms = $term->children($relationship)
 193  Function: return children terms
 194  Returns : list of Bio::Das::FeatureTypeI
 195  Args    : none
 196  Status  : Public
 197
 198 Returns the children for the current term, empty if there are none.  An
 199 optional relationship argument will return those children
 200 that are related via the specified relationship type.
 201
 202 The relationship is one of "isa" or "partof".
 203
 204 =cut
 205
 206 sub children { shift->throw_not_implemented; }
 207
 208 =head2 relationship
 209
 210  Title   : relationship
 211  Usage   : $relationship = $parent->relationship($child)
 212  Function: return the relationship between a parent and a child
 213  Returns : one of "isa" or "partof"
 214  Args    : none
 215  Status  : Public
 216
 217 This method returns the relationship between a parent and one of its
 218 immediate descendents.  It can return "isa", "partof", or undef if
 219 there is not a direct parent/child relationship (kissing cousins are
 220 *not* recognized).
 221
 222 =cut
 223
 224 sub relationship { shift->throw_not_implemented }
 225
 226 =head2 equals
 227
 228  Title   : equals
 229  Usage   : $boolean = $term1->equals($term2)
 230  Function: return true if $term1 and $term2 are the same
 231  Returns : boolean
 232  Args    : second term
 233  Status  : Public
 234
 235 The two terms must be identical.  In practice, this means that if
 236 term2 is a Bio::Das::FeatureI object, then its accession number must
 237 match the first term's accession number.  Otherwise, if term2 is a
 238 bare string, then it must equal (in a case insensitive manner)
 239 the name of term1.
 240
 241 NOTE TO IMPLEMENTORS: This method is defined in terms of other
 242 methods, so does not need to be implemented.
 243
 244 =cut
 245
 246 #'
 247 sub equals {
 248   my $self = shift;
 249   my $term2 = shift;
 250   if ($term2->isa('Bio::Das::FeatureTypeI')) {
 251     return $self->accession eq $term2->accession;
 252   } else {
 253     return lc $self->name eq lc $term2;
 254   }
 255 }
 256
 257 =head2 is_descendent
 258
 259  Title   : is_descendent
 260  Usage   : $boolean = $term1->is_descendent($term2 [,$relationship])
 261  Function: return true of $term2 is a descendent of $term1
 262  Returns : boolean
 263  Args    : second term
 264  Status  : Public
 265
 266 This method returns true if $term2 descends from $term1.  The
 267 operation traverses the tree.  The traversal can be limited to the
 268 relationship type ("isa" or "partof") if desired.  $term2 can be a
 269 bare string, in which case the term names will be used as the basis
 270 for term matching (see equals()).
 271
 272 NOTE TO IMPLEMENTORS: this method is defined as the inverse of
 273 is_parent().  Do not implement it directly, but do implement
 274 is_parent().
 275
 276 =cut
 277
 278 sub is_descendent {
 279   my $self = shift;
 280   my ($term,$relationship) = @_;
 281   $self->throw("$term is not a Bio::Das::FeatureTypeI")
 282     unless $term->isa('Bio::Das::FeatureTypeI');
 283   $term->is_parent($self,$relationship);
 284 }
 285
 286 =head2 is_parent
 287
 288  Title   : is_parent
 289  Usage   : $boolean = $term1->is_parent($term2 [,$relationship])
 290  Function: return true of $term2 is a parent of $term1
 291  Returns : boolean
 292  Args    : second term
 293  Status  : Public
 294
 295 This method returns true if $term2 is a parent of $term1.  The
 296 operation traverses the tree.  The traversal can be limited to the
 297 relationship type ("isa" or "partof") if desired.  $term2 can be a
 298 bare string, in which case the term names will be used as the basis
 299 for term matching (see equals()).
 300
 301 NOTE TO IMPLEMENTORS: Implementing this method will also implement
 302 is_descendent().
 303
 304 =cut
 305
 306 sub is_parent { shift->throw_not_implemented }
 307
 308 =head2 match
 309
 310  Title   : match
 311  Usage   : $boolean = $term1->match($term2)
 312  Function: return true if $term1 equals $term2 or if $term2 is an "isa" descendent
 313  Returns : boolean
 314  Args    : second term
 315  Status  : Public
 316
 317 This method combines equals() and is_descendent() in such a way that
 318 the two terms will match if they are the same or if the second term is
 319 an instance of the first one.  This is also the basis of the operator
 320 overloading of eq.
 321
 322 NOTE TO IMPLEMENTORS: This method is defined in terms of other methods
 323 and does not need to be implemented.
 324
 325 =cut
 326
 327 sub match {
 328   my $self  = shift;
 329   my $term2 = shift;
 330   return 1 if $self->equals($term2);
 331   return $self->is_descendent($term2,'isa');
 332 }
 333
 334 =head2 new
 335
 336  Title   : new
 337  Usage   : $term = Bio::Das::FeatureTypeI->new(@args)
 338  Function: create a new term
 339  Returns : new term
 340  Args    : see below
 341  Status  : Public
 342
 343 This method creates a new Bio::Das::FeatureTypeI.  Arguments:
 344
 345   Argument    Description
 346   --------   ------------
 347
 348   -name       Name of this term
 349
 350   -accession  Accession number for the term
 351
 352   -definition Definition of the term
 353
 354 =cut
 355
 356 sub new { shift->throw_not_implemented }
 357
 358 =head2 add_child
 359
 360  Title   : add_child
 361  Usage   : $boolean = $term->add_child($term2,$relationship)
 362  Function: add a child to a term
 363  Returns : a boolean indicating success
 364  Args    : new child
 365  Throws  : a "cycle detected" exception
 366  Status  : Public
 367
 368 This method adds a new child to the indicated node.  It may detect a
 369 cycle in the DAG and throw a "cycle detected" exception.
 370
 371 =cut
 372
 373 sub add_child { shift->throw_not_implemented }
 374
 375
 376 =head2 delete_child
 377
 378  Title   : delete_child
 379  Usage   : $boolean = $term->delete_child($term2);
 380  Function: delete a child of the term
 381  Returns : a boolean indicating success
 382  Args    : child to be deleted
 383  Throws  : a "not a child" exception
 384  Status  : Public
 385
 386 This method deletes a new child from the indicated node.  It will
 387 throw an exception if the indicated child is not a direct descendent.
 388
 389 =cut
 390
 391 sub delete_child { shift->throw_not_implemented }
 392
 393 1;