Bio/Tools/ECnumber.pm

   1 # $Id$
   2 #
   3 # BioPerl module for Bio::Tools::ECnumber
   4 #
   5 # Cared for by Christian M. Zmasek <czmasek@gnf.org> or <cmzmasek@yahoo.com>
   6 #
   7 # (c) Christian M. Zmasek, czmasek@gnf.org, 2002.
   8 # (c) GNF, Genomics Institute of the Novartis Research Foundation, 2002.
   9 #
  10 # You may distribute this module under the same terms as perl itself.
  11 # Refer to the Perl Artistic License (see the license accompanying this
  12 # software package, or see http://www.perl.com/language/misc/Artistic.html)
  13 # for the terms under which you may use, modify, and redistribute this module.
  14 #
  15 # THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
  16 # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  17 # MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  18 #
  19
  20 # POD documentation - main docs before the code
  21
  22
  23 =head1 NAME
  24
  25 Bio::Tools::ECnumber - representation of EC numbers (Enzyme Classification)
  26
  27 =head1 SYNOPSIS
  28
  29   use Bio::Tools::ECnumber;
  30
  31   # Creation of ECnumber objects
  32   my $EC1 = Bio::Tools::ECnumber->new( -ec_string => "4.3.2.1" );
  33   my $EC2 = Bio::Tools::ECnumber->new( -ec_string => "EC 1.1.1.1" );
  34   my $EC3 = Bio::Tools::ECnumber->new();
  35
  36   # Copying
  37   my $EC4 = $EC1->copy();
  38
  39   # Modification/canonicalization of ECnumber objects
  40   print $EC3->EC_string( "1.01.01.001" ); # Prints "1.1.1.1".
  41
  42   # Stringify
  43   print $EC3->EC_string();
  44   # or
  45   print $EC3->to_string();
  46
  47   # Test for equality
  48   # -- Against ECnumber object:
  49   if ( $EC3->is_equal( $EC2 ) ) { # Prints "equal".
  50       print "equal";
  51   }
  52   # -- Against string representation of EC number:
  53   if ( ! $EC3->is_equal( "1.1.1.-" ) ) { # Prints "not equal".
  54       print "not equal";
  55   }
  56
  57   # Test for membership
  58   my $EC5 = Bio::Tools::ECnumber->new( -ec_string => "4.3.2.-" );
  59   # -- Against ECnumber object.
  60   if ( $EC1->is_member( $EC5 ) ) { # Prints "member".
  61       print "member";
  62   }
  63   # -- Against string representation of EC number.
  64   if ( ! $EC1->is_member( "4.3.1.-" ) ) { # Prints "not member".
  65       print "not member";
  66   }
  67
  68 =head1 DESCRIPTION
  69
  70 L<Bio::Tools::ECnumber> is a representation of EC numbers,
  71 the numerical heirarchy for Enzyme Classification.
  72
  73 See L<http://www.chem.qmul.ac.uk/iubmb/enzyme/> for more details.
  74
  75 =head1 FEEDBACK
  76
  77 =head2 Mailing Lists
  78
  79 User feedback is an integral part of the evolution of this and other
  80 Bioperl modules. Send your comments and suggestions preferably to one
  81 of the Bioperl mailing lists.  Your participation is much appreciated.
  82
  83   bioperl-l@bioperl.org                  - General discussion
  84   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  85
  86 =head2 Reporting Bugs
  87
  88 Report bugs to the Bioperl bug tracking system to help us keep track
  89 the bugs and their resolution.  Bug reports can be submitted via the
  90 web:
  91
  92   http://bugzilla.open-bio.org/
  93
  94 =head1 AUTHOR
  95
  96 Christian M. Zmasek
  97
  98 Email: czmasek@gnf.org  or  cmzmasek@yahoo.com
  99
 100 WWW:   http://www.genetics.wustl.edu/eddy/people/zmasek/
 101
 102 Address:
 103
 104   Genomics Institute of the Novartis Research Foundation
 105   10675 John Jay Hopkins Drive
 106   San Diego, CA 92121
 107
 108 =head1 APPENDIX
 109
 110 The rest of the documentation details each of the object
 111 methods. Internal methods are usually preceded with a _
 112
 113 =cut
 114
 115
 116 # Let the code begin...
 117
 118 package Bio::Tools::ECnumber;
 119 use strict;
 120
 121 use constant DEFAULT => "-";
 122 use constant TRUE    => 1;
 123 use constant FALSE   => 0;
 124
 125 use base qw(Bio::Root::Root);
 126
 127 =head2 new
 128
 129  Title   : new
 130  Usage   : $EC1 = Bio::Tools::ECnumber->new( -ec_string => "4.3.2.1" );
 131            or
 132            $EC2 = Bio::Tools::ECnumber->new( -ec_string => "4.3.2.2",
 133                                              -comment   => "Is EC 4.3.2.2" );
 134            or
 135            $EC3 = Bio::Tools::ECnumber->new(); # EC3 is now "-.-.-.-"
 136  Function: Creates a new ECnumber object.
 137            Parses a EC number from "x.x.x.x", "EC x.x.x.x",
 138            "ECx.x.x.x", or "EC:x.x.x.x";
 139            x being either a positive integer or a "-".
 140  Returns : A new ECnumber object.
 141  Args    : A string representing a EC number, e.g. "4.3.2.1"
 142            or "EC 4.3.2.1" or "1.-.-.-".
 143
 144 =cut
 145
 146 sub new {
 147     my( $class, @args ) = @_;
 148
 149     my $self = $class->SUPER::new( @args );
 150
 151     my ( $EC_string, $comment )
 152     = $self->_rearrange( [ qw( EC_STRING COMMENT ) ], @args );
 153
 154     $self->init();
 155
 156     $EC_string && $self->EC_string( $EC_string );
 157     $comment   && $self->comment( $comment );
 158
 159     return $self;
 160
 161 } # new
 162
 163
 164
 165 =head2 init
 166
 167  Title   : init()
 168  Usage   : $EC1->init(); # EC1 is now "-.-.-.-"
 169  Function: Initializes this ECnumber to default values.
 170  Returns :
 171  Args    :
 172
 173 =cut
 174
 175 sub init {
 176     my( $self ) = @_;
 177
 178     $self->enzyme_class( DEFAULT );
 179     $self->sub_class( DEFAULT );
 180     $self->sub_sub_class( DEFAULT );
 181     $self->serial_number( DEFAULT );
 182     $self->comment( "" );
 183
 184 } # init
 185
 186
 187
 188 =head2 copy
 189
 190  Title   : copy()
 191  Usage   : $EC2 = $EC1->copy();
 192  Function: Creates a new ECnumber object which is an exact copy
 193            of this ECnumber.
 194  Returns : A copy of this ECnumber.
 195  Args    :
 196
 197 =cut
 198
 199 sub copy {
 200     my( $self ) = @_;
 201
 202     my $new_ec = $self->new();
 203     $new_ec->enzyme_class(  $self->enzyme_class() );
 204     $new_ec->sub_class(     $self->sub_class() );
 205     $new_ec->sub_sub_class( $self->sub_sub_class() );
 206     $new_ec->serial_number( $self->serial_number() );
 207     $new_ec->comment(       $self->comment() );
 208     return $new_ec;
 209
 210 } # copy
 211
 212
 213
 214 =head2 EC_string
 215
 216  Title   : EC_string
 217  Usage   : $EC3->EC_string( "1.1.1.-" );
 218            or
 219            print $EC3->EC_string();
 220  Function: Set/get for string representations of EC numbers.
 221            Parses a EC number from "x.x.x.x", "EC x.x.x.x",
 222            "ECx.x.x.x", or "EC:x.x.x.x";
 223            x being either a positive integer or a "-".
 224  Returns : A string representations of a EC number.
 225  Args    : A string representations of a EC number.
 226
 227 =cut
 228
 229 sub EC_string {
 230     my ( $self, $value ) = @_;
 231
 232     if ( defined $value) {
 233         $value =~ s/\s+//g; # Removes white space.
 234         $value =~ s/^EC//i; # Removes "EC".
 235         $value =~ s/^://;   # Removes ":".
 236
 237         if ( $value =~ /^([\d-]*)\.([\d-]*)\.([\d-]*)\.([\d-]*)$/ ) {
 238             $self->enzyme_class( $1 );
 239             $self->sub_class( $2 );
 240             $self->sub_sub_class( $3 );
 241             $self->serial_number( $4 );
 242         }
 243         else {
 244             $self->throw( "Illegal format error [$value]" );
 245         }
 246     }
 247
 248     return $self->to_string();
 249
 250 } # EC_string
 251
 252
 253
 254 =head2 to_string
 255
 256  Title   : to_string()
 257  Usage   : print $EC3->to_string();
 258  Function: To string method for EC numbers
 259            (equals the "get" functionality of "EC_string").
 260  Returns : A string representations of a EC number.
 261  Args    :
 262
 263 =cut
 264
 265 sub to_string {
 266     my ( $self ) = @_;
 267
 268     my $s  = $self->enzyme_class() . ".";
 269     $s    .= $self->sub_class() . ".";
 270     $s    .= $self->sub_sub_class() . ".";
 271     $s    .= $self->serial_number();
 272     return $s;
 273
 274 } # to_string
 275
 276
 277
 278 =head2 is_equal
 279
 280  Title   : is_equal
 281  Usage   : if ( $EC3->is_equal( $EC2 ) )
 282            or
 283            if ( $EC3->is_equal( "1.1.1.-" ) )
 284  Function: Checks whether this ECnumber is equal to the argument
 285            EC number (please note: "1.1.1.1" != "1.1.1.-").
 286  Returns : True (1) or false (0).
 287  Args    : A ECnumber object or a string representation of a EC number.
 288
 289 =cut
 290
 291 sub is_equal {
 292     my ( $self, $value ) = @_;
 293
 294     if ( $self->_is_not_reference( $value ) ) {
 295         $value = $self->new( -ec_string => $value );
 296     }
 297     else {
 298         $self->_is_ECnumber_object( $value );
 299     }
 300
 301     unless ( $self->enzyme_class() eq $value->enzyme_class() ) {
 302         return FALSE;
 303     }
 304     unless ( $self->sub_class() eq $value->sub_class() ) {
 305         return FALSE;
 306     }
 307     unless ( $self->sub_sub_class() eq $value->sub_sub_class() ) {
 308         return FALSE;
 309     }
 310     unless ( $self->serial_number() eq $value->serial_number() ) {
 311         return FALSE;
 312     }
 313     return TRUE;
 314
 315 } # is_equal
 316
 317
 318
 319 =head2 is_member
 320
 321  Title   : is_member
 322  Usage   : if ( $EC1->is_member( $EC5 ) )
 323            or
 324            if ( $EC1->is_member( "4.3.-.-" ) )
 325  Function: Checks whether this ECnumber is a member of the (incomplete)
 326            argument EC number (e.g. "1.1.1.1" is a member of "1.1.1.-"
 327            but not of "1.1.1.2").
 328  Returns : True (1) or false (0).
 329  Args    : A ECnumber object or a string representation of a EC number.
 330
 331 =cut
 332
 333 sub is_member {
 334     my ( $self, $value ) = @_;
 335
 336     if ( $self->_is_not_reference( $value ) ) {
 337         $value = $self->new( -ec_string => $value );
 338     }
 339     else {
 340         $self->_is_ECnumber_object( $value );
 341     }
 342     $self->_check_for_illegal_defaults();
 343     $value->_check_for_illegal_defaults();
 344
 345     unless ( $value->enzyme_class() eq DEFAULT
 346     ||       $self->enzyme_class() eq $value->enzyme_class() ) {
 347         return FALSE;
 348     }
 349     unless (  $value->sub_class() eq DEFAULT
 350     ||        $self->sub_class() eq $value->sub_class() ) {
 351         return FALSE;
 352     }
 353     unless ( $value->sub_sub_class() eq DEFAULT
 354     ||       $self->sub_sub_class() eq $value->sub_sub_class() ) {
 355         return FALSE;
 356     }
 357     unless ( $value->serial_number() eq DEFAULT
 358     ||       $self->serial_number() eq $value->serial_number() ) {
 359         return FALSE;
 360     }
 361     return TRUE;
 362
 363 } # is_member
 364
 365
 366
 367 =head2 enzyme_class
 368
 369  Title   : enzyme_class
 370  Usage   : $EC1->enzyme_class( 1 );
 371            or
 372            print $EC1->enzyme_class();
 373  Function: Set/get for the enzyme class number of ECnumbers.
 374  Returns : The enzyme class number of this ECnumber.
 375  Args    : A positive integer or "-".
 376
 377 =cut
 378
 379 sub enzyme_class {
 380     my ( $self, $value ) = @_;
 381
 382     if ( defined $value) {
 383         $self->{ "_enzyme_class" } = $self->_check_number( $value );
 384     }
 385
 386     return $self->{ "_enzyme_class" };
 387
 388 } # enzyme_class
 389
 390
 391
 392 =head2 sub_class
 393
 394  Title   : sub_class
 395  Usage   : $EC1->sub_class( 4 );
 396            or
 397            print $EC1->sub_class();
 398  Function: Set/get for the enzyme sub class number of ECnumbers.
 399  Returns : The enzyme sub class number of this ECnumber.
 400  Args    : A positive integer or "-".
 401
 402 =cut
 403
 404 sub sub_class {
 405     my ( $self, $value ) = @_;
 406
 407     if ( defined $value) {
 408         $self->{ "_sub_class" } = $self->_check_number( $value );
 409     }
 410
 411     return $self->{ "_sub_class" };
 412
 413 } # sub_class
 414
 415
 416
 417 =head2 sub_sub_class
 418
 419  Title   : sub_sub_class
 420  Usage   : $EC1->sub_sub_class( 12 );
 421            or
 422            print $EC1->sub_sub_class();
 423  Function: Set/get for the enzyme sub sub class number of ECnumbers.
 424  Returns : The enzyme sub sub class number of this ECnumber.
 425  Args    : A positive integer or "-".
 426
 427 =cut
 428
 429 sub sub_sub_class {
 430     my ( $self, $value ) = @_;
 431
 432     if ( defined $value) {
 433         $self->{ "_sub_sub_class" } = $self->_check_number( $value );
 434     }
 435
 436     return $self->{ "_sub_sub_class" };
 437
 438 } # sub_sub_class
 439
 440
 441
 442 =head2 serial_number
 443
 444  Title   : serial_number
 445  Usage   : $EC1->serial_number( 482 );
 446            or
 447            print $EC1->serial_number();
 448  Function: Set/get for the serial number of ECnumbers.
 449  Returns : The serial number of this ECnumber.
 450  Args    : A positive integer or "-".
 451
 452 =cut
 453
 454 sub serial_number {
 455     my ( $self, $value ) = @_;
 456
 457     if ( defined $value) {
 458         $self->{ "_serial_number" } = $self->_check_number( $value );
 459     }
 460
 461     return $self->{ "_serial_number" };
 462
 463 } # serial_number
 464
 465
 466
 467 =head2 comment
 468
 469  Title   : comment
 470  Usage   : $EC1->comment( "deprecated" );
 471            or
 472            print $EC1->comment();
 473  Function: Set/get for a arbitrary comment.
 474  Returns : A comment [scalar].
 475  Args    : A comment [scalar].
 476
 477 =cut
 478
 479 sub comment {
 480     my ( $self, $value ) = @_;
 481
 482     if ( defined $value) {
 483         $self->{ "_comment" } = $value;
 484     }
 485
 486     return $self->{ "_comment" };
 487
 488 } # comment
 489
 490
 491
 492 # Title   : _check_number
 493 # Function: Checks and standardizes the individual numbers of a EC number
 494 #           (removes leading zeros, removes white spaces).
 495 # Returns : A standardized number.
 496 # Args    : A string representing a number in a EC number.
 497 sub _check_number {
 498     my ( $self, $value ) = @_;
 499
 500     my $original_value = $value;
 501     $value =~ s/\s+//g;   # Removes white space.
 502     if ( $value eq "" ) {
 503         $value = DEFAULT;
 504     }
 505     $value =~ s/^0+//;    # Removes leading zeros.
 506     if ( $value eq "" ) { # If it was "0" (or "00"), it would be "" now.
 507         $value = "0";
 508     }
 509     elsif ( $value ne DEFAULT
 510     &&      $value =~ /\D/ ) {
 511         $self->throw( "Illegal format error [$original_value]" );
 512     }
 513     return $value;
 514
 515 } # _check_number
 516
 517
 518
 519 # Title   : _check_for_illegal_defaults()
 520 # Function: Checks for situations like "1.-.1.1", which
 521 #           are illegal in membership tests.
 522 # Returns :
 523 # Args    :
 524 sub _check_for_illegal_defaults {
 525     my ( $self ) = @_;
 526
 527     if ( ( $self->sub_sub_class() eq DEFAULT
 528     &&     $self->serial_number() ne DEFAULT ) ||
 529          ( $self->sub_class()     eq DEFAULT
 530     &&     $self->sub_sub_class() ne DEFAULT ) ||
 531          ( $self->enzyme_class()  eq DEFAULT
 532     &&     $self->sub_class()     ne DEFAULT ) ) {
 533         $self->throw( "Illegal format error for comparison ["
 534         . $self->to_string() . "]" );
 535     }
 536
 537 } # _check_for_illegal_defaults
 538
 539
 540
 541 # Title   : _is_not_reference
 542 # Function: Checks whether the argument is not a reference.
 543 # Returns : True or false.
 544 # Args    : A scalar.
 545 sub _is_not_reference {
 546     my ( $self, $value ) = @_;
 547
 548     return ( ! ref( $value ) );
 549
 550 } # _is_not_reference
 551
 552
 553
 554 # Title   : _is_ECnumber_object
 555 # Function: Checks whether the arument is a ECnumber.
 556 # Returns :
 557 # Args    : A reference.
 558 sub _is_ECnumber_object {
 559     my ( $self, $value ) = @_;
 560
 561     unless( $value->isa( "Bio::Tools::ECnumber" ) ) {
 562         $self->throw( "Found [". ref( $value )
 563         ."] where [Bio::Tools::ECnumber] expected" );
 564     }
 565
 566 } # _is_ECnumber_object
 567
 568
 569
 570 1;