lib/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 hierarchy 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://github.com/bioperl/bioperl-live/issues
 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
 132 use strict;
 133
 134 use constant DEFAULT => "-";
 135 use constant TRUE    => 1;
 136 use constant FALSE   => 0;
 137
 138 use base qw(Bio::Root::Root);
 139
 140 =head2 new
 141
 142  Title   : new
 143  Usage   : $EC1 = Bio::Tools::ECnumber->new( -ec_string => "4.3.2.1" );
 144            or
 145            $EC2 = Bio::Tools::ECnumber->new( -ec_string => "4.3.2.2",
 146                                              -comment   => "Is EC 4.3.2.2" );
 147            or
 148            $EC3 = Bio::Tools::ECnumber->new(); # EC3 is now "-.-.-.-"
 149  Function: Creates a new ECnumber object.
 150            Parses a EC number from "x.x.x.x", "EC x.x.x.x",
 151            "ECx.x.x.x", or "EC:x.x.x.x";
 152            x being either a positive integer or a "-".
 153  Returns : A new ECnumber object.
 154  Args    : A string representing a EC number, e.g. "4.3.2.1"
 155            or "EC 4.3.2.1" or "1.-.-.-".
 156
 157 =cut
 158
 159 sub new {
 160     my( $class, @args ) = @_;
 161
 162     my $self = $class->SUPER::new( @args );
 163
 164     my ( $EC_string, $comment )
 165     = $self->_rearrange( [ qw( EC_STRING COMMENT ) ], @args );
 166
 167     $self->init();
 168
 169     $EC_string && $self->EC_string( $EC_string );
 170     $comment   && $self->comment( $comment );
 171
 172     return $self;
 173
 174 } # new
 175
 176
 177
 178 =head2 init
 179
 180  Title   : init()
 181  Usage   : $EC1->init(); # EC1 is now "-.-.-.-"
 182  Function: Initializes this ECnumber to default values.
 183  Returns :
 184  Args    :
 185
 186 =cut
 187
 188 sub init {
 189     my( $self ) = @_;
 190
 191     $self->enzyme_class( DEFAULT );
 192     $self->sub_class( DEFAULT );
 193     $self->sub_sub_class( DEFAULT );
 194     $self->serial_number( DEFAULT );
 195     $self->comment( "" );
 196
 197 } # init
 198
 199
 200
 201 =head2 copy
 202
 203  Title   : copy()
 204  Usage   : $EC2 = $EC1->copy();
 205  Function: Creates a new ECnumber object which is an exact copy
 206            of this ECnumber.
 207  Returns : A copy of this ECnumber.
 208  Args    :
 209
 210 =cut
 211
 212 sub copy {
 213     my( $self ) = @_;
 214
 215     my $new_ec = $self->new();
 216     $new_ec->enzyme_class(  $self->enzyme_class() );
 217     $new_ec->sub_class(     $self->sub_class() );
 218     $new_ec->sub_sub_class( $self->sub_sub_class() );
 219     $new_ec->serial_number( $self->serial_number() );
 220     $new_ec->comment(       $self->comment() );
 221     return $new_ec;
 222
 223 } # copy
 224
 225
 226
 227 =head2 EC_string
 228
 229  Title   : EC_string
 230  Usage   : $EC3->EC_string( "1.1.1.-" );
 231            or
 232            print $EC3->EC_string();
 233  Function: Set/get for string representations of EC numbers.
 234            Parses a EC number from "x.x.x.x", "EC x.x.x.x",
 235            "ECx.x.x.x", or "EC:x.x.x.x";
 236            x being either a positive integer or a "-".
 237  Returns : A string representations of a EC number.
 238  Args    : A string representations of a EC number.
 239
 240 =cut
 241
 242 sub EC_string {
 243     my ( $self, $value ) = @_;
 244
 245     if ( defined $value) {
 246         $value =~ s/\s+//g; # Removes white space.
 247         $value =~ s/^EC//i; # Removes "EC".
 248         $value =~ s/^://;   # Removes ":".
 249
 250         if ( $value =~ /^([\d-]*)\.([\d-]*)\.([\d-]*)\.([\d-]*)$/ ) {
 251             $self->enzyme_class( $1 );
 252             $self->sub_class( $2 );
 253             $self->sub_sub_class( $3 );
 254             $self->serial_number( $4 );
 255         }
 256         else {
 257             $self->throw( "Illegal format error [$value]" );
 258         }
 259     }
 260
 261     return $self->to_string();
 262
 263 } # EC_string
 264
 265
 266
 267 =head2 to_string
 268
 269  Title   : to_string()
 270  Usage   : print $EC3->to_string();
 271  Function: To string method for EC numbers
 272            (equals the "get" functionality of "EC_string").
 273  Returns : A string representations of a EC number.
 274  Args    :
 275
 276 =cut
 277
 278 sub to_string {
 279     my ( $self ) = @_;
 280
 281     my $s  = $self->enzyme_class() . ".";
 282     $s    .= $self->sub_class() . ".";
 283     $s    .= $self->sub_sub_class() . ".";
 284     $s    .= $self->serial_number();
 285     return $s;
 286
 287 } # to_string
 288
 289
 290
 291 =head2 is_equal
 292
 293  Title   : is_equal
 294  Usage   : if ( $EC3->is_equal( $EC2 ) )
 295            or
 296            if ( $EC3->is_equal( "1.1.1.-" ) )
 297  Function: Checks whether this ECnumber is equal to the argument
 298            EC number (please note: "1.1.1.1" != "1.1.1.-").
 299  Returns : True (1) or false (0).
 300  Args    : A ECnumber object or a string representation of a EC number.
 301
 302 =cut
 303
 304 sub is_equal {
 305     my ( $self, $value ) = @_;
 306
 307     if ( $self->_is_not_reference( $value ) ) {
 308         $value = $self->new( -ec_string => $value );
 309     }
 310     else {
 311         $self->_is_ECnumber_object( $value );
 312     }
 313
 314     unless ( $self->enzyme_class() eq $value->enzyme_class() ) {
 315         return FALSE;
 316     }
 317     unless ( $self->sub_class() eq $value->sub_class() ) {
 318         return FALSE;
 319     }
 320     unless ( $self->sub_sub_class() eq $value->sub_sub_class() ) {
 321         return FALSE;
 322     }
 323     unless ( $self->serial_number() eq $value->serial_number() ) {
 324         return FALSE;
 325     }
 326     return TRUE;
 327
 328 } # is_equal
 329
 330
 331
 332 =head2 is_member
 333
 334  Title   : is_member
 335  Usage   : if ( $EC1->is_member( $EC5 ) )
 336            or
 337            if ( $EC1->is_member( "4.3.-.-" ) )
 338  Function: Checks whether this ECnumber is a member of the (incomplete)
 339            argument EC number (e.g. "1.1.1.1" is a member of "1.1.1.-"
 340            but not of "1.1.1.2").
 341  Returns : True (1) or false (0).
 342  Args    : A ECnumber object or a string representation of a EC number.
 343
 344 =cut
 345
 346 sub is_member {
 347     my ( $self, $value ) = @_;
 348
 349     if ( $self->_is_not_reference( $value ) ) {
 350         $value = $self->new( -ec_string => $value );
 351     }
 352     else {
 353         $self->_is_ECnumber_object( $value );
 354     }
 355     $self->_check_for_illegal_defaults();
 356     $value->_check_for_illegal_defaults();
 357
 358     unless ( $value->enzyme_class() eq DEFAULT
 359     ||       $self->enzyme_class() eq $value->enzyme_class() ) {
 360         return FALSE;
 361     }
 362     unless (  $value->sub_class() eq DEFAULT
 363     ||        $self->sub_class() eq $value->sub_class() ) {
 364         return FALSE;
 365     }
 366     unless ( $value->sub_sub_class() eq DEFAULT
 367     ||       $self->sub_sub_class() eq $value->sub_sub_class() ) {
 368         return FALSE;
 369     }
 370     unless ( $value->serial_number() eq DEFAULT
 371     ||       $self->serial_number() eq $value->serial_number() ) {
 372         return FALSE;
 373     }
 374     return TRUE;
 375
 376 } # is_member
 377
 378
 379
 380 =head2 enzyme_class
 381
 382  Title   : enzyme_class
 383  Usage   : $EC1->enzyme_class( 1 );
 384            or
 385            print $EC1->enzyme_class();
 386  Function: Set/get for the enzyme class number of ECnumbers.
 387  Returns : The enzyme class number of this ECnumber.
 388  Args    : A positive integer or "-".
 389
 390 =cut
 391
 392 sub enzyme_class {
 393     my ( $self, $value ) = @_;
 394
 395     if ( defined $value) {
 396         $self->{ "_enzyme_class" } = $self->_check_number( $value );
 397     }
 398
 399     return $self->{ "_enzyme_class" };
 400
 401 } # enzyme_class
 402
 403
 404
 405 =head2 sub_class
 406
 407  Title   : sub_class
 408  Usage   : $EC1->sub_class( 4 );
 409            or
 410            print $EC1->sub_class();
 411  Function: Set/get for the enzyme sub class number of ECnumbers.
 412  Returns : The enzyme sub class number of this ECnumber.
 413  Args    : A positive integer or "-".
 414
 415 =cut
 416
 417 sub sub_class {
 418     my ( $self, $value ) = @_;
 419
 420     if ( defined $value) {
 421         $self->{ "_sub_class" } = $self->_check_number( $value );
 422     }
 423
 424     return $self->{ "_sub_class" };
 425
 426 } # sub_class
 427
 428
 429
 430 =head2 sub_sub_class
 431
 432  Title   : sub_sub_class
 433  Usage   : $EC1->sub_sub_class( 12 );
 434            or
 435            print $EC1->sub_sub_class();
 436  Function: Set/get for the enzyme sub sub class number of ECnumbers.
 437  Returns : The enzyme sub sub class number of this ECnumber.
 438  Args    : A positive integer or "-".
 439
 440 =cut
 441
 442 sub sub_sub_class {
 443     my ( $self, $value ) = @_;
 444
 445     if ( defined $value) {
 446         $self->{ "_sub_sub_class" } = $self->_check_number( $value );
 447     }
 448
 449     return $self->{ "_sub_sub_class" };
 450
 451 } # sub_sub_class
 452
 453
 454
 455 =head2 serial_number
 456
 457  Title   : serial_number
 458  Usage   : $EC1->serial_number( 482 );
 459            or
 460            print $EC1->serial_number();
 461  Function: Set/get for the serial number of ECnumbers.
 462  Returns : The serial number of this ECnumber.
 463  Args    : A positive integer or "-".
 464
 465 =cut
 466
 467 sub serial_number {
 468     my ( $self, $value ) = @_;
 469
 470     if ( defined $value) {
 471         $self->{ "_serial_number" } = $self->_check_number( $value );
 472     }
 473
 474     return $self->{ "_serial_number" };
 475
 476 } # serial_number
 477
 478
 479
 480 =head2 comment
 481
 482  Title   : comment
 483  Usage   : $EC1->comment( "deprecated" );
 484            or
 485            print $EC1->comment();
 486  Function: Set/get for a arbitrary comment.
 487  Returns : A comment [scalar].
 488  Args    : A comment [scalar].
 489
 490 =cut
 491
 492 sub comment {
 493     my ( $self, $value ) = @_;
 494
 495     if ( defined $value) {
 496         $self->{ "_comment" } = $value;
 497     }
 498
 499     return $self->{ "_comment" };
 500
 501 } # comment
 502
 503
 504
 505 # Title   : _check_number
 506 # Function: Checks and standardizes the individual numbers of a EC number
 507 #           (removes leading zeros, removes white spaces).
 508 # Returns : A standardized number.
 509 # Args    : A string representing a number in a EC number.
 510 sub _check_number {
 511     my ( $self, $value ) = @_;
 512
 513     my $original_value = $value;
 514     $value =~ s/\s+//g;   # Removes white space.
 515     if ( $value eq "" ) {
 516         $value = DEFAULT;
 517     }
 518     $value =~ s/^0+//;    # Removes leading zeros.
 519     if ( $value eq "" ) { # If it was "0" (or "00"), it would be "" now.
 520         $value = "0";
 521     }
 522     elsif ( $value ne DEFAULT
 523     &&      $value =~ /\D/ ) {
 524         $self->throw( "Illegal format error [$original_value]" );
 525     }
 526     return $value;
 527
 528 } # _check_number
 529
 530
 531
 532 # Title   : _check_for_illegal_defaults()
 533 # Function: Checks for situations like "1.-.1.1", which
 534 #           are illegal in membership tests.
 535 # Returns :
 536 # Args    :
 537 sub _check_for_illegal_defaults {
 538     my ( $self ) = @_;
 539
 540     if ( ( $self->sub_sub_class() eq DEFAULT
 541     &&     $self->serial_number() ne DEFAULT ) ||
 542          ( $self->sub_class()     eq DEFAULT
 543     &&     $self->sub_sub_class() ne DEFAULT ) ||
 544          ( $self->enzyme_class()  eq DEFAULT
 545     &&     $self->sub_class()     ne DEFAULT ) ) {
 546         $self->throw( "Illegal format error for comparison ["
 547         . $self->to_string() . "]" );
 548     }
 549
 550 } # _check_for_illegal_defaults
 551
 552
 553
 554 # Title   : _is_not_reference
 555 # Function: Checks whether the argument is not a reference.
 556 # Returns : True or false.
 557 # Args    : A scalar.
 558 sub _is_not_reference {
 559     my ( $self, $value ) = @_;
 560
 561     return ( ! ref( $value ) );
 562
 563 } # _is_not_reference
 564
 565
 566
 567 # Title   : _is_ECnumber_object
 568 # Function: Checks whether the arument is a ECnumber.
 569 # Returns :
 570 # Args    : A reference.
 571 sub _is_ECnumber_object {
 572     my ( $self, $value ) = @_;
 573
 574     unless( $value->isa( "Bio::Tools::ECnumber" ) ) {
 575         $self->throw( "Found [". ref( $value )
 576         ."] where [Bio::Tools::ECnumber] expected" );
 577     }
 578
 579 } # _is_ECnumber_object
 580
 581
 582
 583 1;