Bio/Tools/ECnumber.pm

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