Bio/Structure/Atom.pm

   1 #
   2 # bioperl module for Bio::Structure::Atom
   3 #
   4 # Please direct questions and support issues to <bioperl-l@bioperl.org>
   5 #
   6 # Cared for by Kris Boulez <kris.boulez@algonomics.com>
   7 #
   8 # Copyright Kris Boulez
   9 #
  10 # You may distribute this module under the same terms as perl itself
  11
  12 # POD documentation - main docs before the code
  13
  14 =head1 NAME
  15
  16 Bio::Structure::Atom - Bioperl structure Object, describes an Atom
  17
  18 =head1 SYNOPSIS
  19
  20   #add synopsis here
  21
  22 =head1 DESCRIPTION
  23
  24 This object stores a Bio::Structure::Atom
  25
  26 =head1 FEEDBACK
  27
  28 =head2 Mailing Lists
  29
  30 User feedback is an integral part of the evolution of this and other
  31 Bioperl modules. Send your comments and suggestions preferably to one
  32 of the Bioperl mailing lists.  Your participation is much appreciated.
  33
  34   bioperl-l@bioperl.org                  - General discussion
  35   http://bioperl.org/wiki/Mailing_lists  - About the mailing lists
  36
  37 =head2 Support
  38
  39 Please direct usage questions or support issues to the mailing list:
  40
  41 I<bioperl-l@bioperl.org>
  42
  43 rather than to the module maintainer directly. Many experienced and
  44 reponsive experts will be able look at the problem and quickly
  45 address it. Please include a thorough description of the problem
  46 with code and data examples if at all possible.
  47
  48 =head2 Reporting Bugs
  49
  50 Report bugs to the Bioperl bug tracking system to help us keep track
  51 the bugs and their resolution.  Bug reports can be submitted via the web:
  52
  53   https://github.com/bioperl/bioperl-live/issues
  54
  55 =head1 AUTHOR - Kris Boulez
  56
  57 Email kris.boulez@algonomics.com
  58
  59 =head1 APPENDIX
  60
  61 The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _
  62
  63 =cut
  64
  65
  66 # Let the code begin...
  67
  68 package Bio::Structure::Atom;
  69 use strict;
  70
  71 use Bio::Structure::Residue;
  72 use base qw(Bio::Root::Root);
  73
  74
  75 =head2 new()
  76
  77  Title   : new()
  78  Usage   : $struc = Bio::Structure::Atom->new(
  79                                            -id  => 'human_id',
  80                                            );
  81
  82  Function: Returns a new Bio::Structure::Atom object from basic
  83         constructors. Probably most called from Bio::Structure::IO.
  84  Returns : a new Bio::Structure::Atom object
  85
  86 =cut
  87
  88
  89 sub new {
  90     my ($class, @args) = @_;
  91     my $self = $class->SUPER::new(@args);
  92
  93     my($id, $x, $y, $z) =
  94         $self->_rearrange([qw(
  95                               ID
  96                               X
  97                               Y
  98                               Z
  99                               )],
 100                           @args);
 101
 102     $id         && $self->id($id);
 103     $x          && $self->x($x);
 104     $y          && $self->y($y);
 105     $z          && $self->z($z);
 106
 107     return $self;
 108 }
 109
 110
 111
 112 =head2 x()
 113
 114  Title   : x
 115  Usage   : $x = $atom->x($x);
 116  Function: Set/gets the X coordinate for an Atom
 117  Returns : The value for the X coordinate of the Atom (This is just a number,
 118         it is expected to be in Angstrom, but no garantees)
 119  Args    : The X coordinate as a number
 120
 121 =cut
 122
 123 sub x {
 124         my ($self,$value) = @_;
 125         if( defined $value) {
 126                 # do we want to check if $value contains really a number ?
 127                 $self->{'x'} = $value;
 128         }
 129         return $self->{'x'};
 130 }
 131
 132
 133 =head2 y()
 134
 135  Title   : y
 136  Usage   : $y = $atom->y($y);
 137  Function: Set/gets the Y coordinate for an Atom
 138  Returns : The value for the Y coordinate of the Atom (This is just a number,
 139         it is eypected to be in Angstrom, but no garantees)
 140  Args    : The Y coordinate as a number
 141
 142 =cut
 143
 144 sub y {
 145         my ($self,$value) = @_;
 146         if( defined $value) {
 147                 # do we want to check if $value contains really a number ?
 148                 $self->{'y'} = $value;
 149         }
 150         return $self->{'y'};
 151 }
 152
 153
 154 =head2 z()
 155
 156  Title   : z
 157  Usage   : $z = $atom->z($z);
 158  Function: Set/gets the Z coordinate for an Atom
 159  Returns : The value for the Z coordinate of the Atom (This is just a number,
 160         it is ezpected to be in Angstrom, but no garantees)
 161  Args    : The Z coordinate as a number
 162
 163 =cut
 164
 165 sub z {
 166         my ($self,$value) = @_;
 167         if( defined $value) {
 168                 # do we want to check if $value contains really a number ?
 169                 $self->{'z'} = $value;
 170         }
 171         return $self->{'z'};
 172 }
 173
 174
 175 =head2 xyz()
 176
 177  Title   : xyz
 178  Usage   : ($x,$y,$z) = $atom->xyz;
 179  Function: Gets the XYZ coordinates for an Atom
 180  Returns : A list with the value for the XYZ coordinate of the Atom
 181  Args    :
 182
 183 =cut
 184
 185 sub xyz {
 186         my ($self) = @_;
 187
 188         return ($self->x, $self->y, $self->z);
 189 }
 190
 191
 192 =head2 residue()
 193
 194  Title   : residue
 195  Usage   :
 196  Function:  No code here, all parent/child stuff via Entry
 197  Returns :
 198  Args    :
 199
 200 =cut
 201
 202 sub residue {
 203         my($self, $value) = @_;
 204
 205         $self->throw("all parent/child stuff via Entry\n");
 206 }
 207
 208
 209 =head2 icode()
 210
 211  Title   : icode
 212  Usage   : $icode = $atom->icode($icode)
 213  Function: Sets/gets the icode
 214  Returns : Returns the icode for this atom
 215  Args    : reference to an Atom
 216
 217 =cut
 218
 219 sub icode {
 220         my($self, $value) = @_;
 221
 222         if (defined $value) {
 223                 $self->{'icode'} = $value;
 224         }
 225         return $self->{'icode'};
 226 }
 227
 228
 229 =head2 serial()
 230
 231  Title   : serial
 232  Usage   : $serial = $atom->serial($serial)
 233  Function: Sets/gets the serial number
 234  Returns : Returns the serial number for this atom
 235  Args    : reference to an Atom
 236
 237 =cut
 238
 239 sub serial {
 240         my($self, $value) = @_;
 241
 242         if (defined $value) {
 243                 $self->{'serial'} = $value;
 244         }
 245         return $self->{'serial'};
 246 }
 247
 248
 249 =head2 occupancy()
 250
 251  Title   : occupancy
 252  Usage   : $occupancy = $atom->occupancy($occupancy)
 253  Function: Sets/gets the occupancy
 254  Returns : Returns the occupancy for this atom
 255  Args    : reference to an Atom
 256
 257 =cut
 258
 259 sub occupancy {
 260         my($self, $value) = @_;
 261
 262         if (defined $value) {
 263                 $self->{'occupancy'} = $value;
 264         }
 265         return $self->{'occupancy'};
 266 }
 267
 268
 269 =head2 tempfactor()
 270
 271  Title   : tempfactor
 272  Usage   : $tempfactor = $atom->tempfactor($tempfactor)
 273  Function: Sets/gets the tempfactor
 274  Returns : Returns the tempfactor for this atom
 275  Args    : reference to an Atom
 276
 277 =cut
 278
 279 sub tempfactor {
 280         my($self, $value) = @_;
 281
 282         if (defined $value) {
 283                 $self->{'tempfactor'} = $value;
 284         }
 285         return $self->{'tempfactor'};
 286 }
 287
 288
 289 =head2 segID()
 290
 291  Title   : segID
 292  Usage   : $segID = $atom->segID($segID)
 293  Function: Sets/gets the segID
 294  Returns : Returns the segID for this atom
 295  Args    : reference to an Atom
 296
 297 =cut
 298
 299 sub segID {
 300         my($self, $value) = @_;
 301
 302         if (defined $value) {
 303                 $self->{'segID'} = $value;
 304         }
 305         return $self->{'segID'};
 306 }
 307
 308
 309 =head2 pdb_atomname()
 310
 311  Title   : pdb_atomname
 312  Usage   : $pdb_atomname = $atom->pdb_atomname($pdb_atomname)
 313  Function: Sets/gets the pdb_atomname (atomname used in the PDB file)
 314  Returns : Returns the pdb_atomname for this atom
 315  Args    : reference to an Atom
 316
 317 =cut
 318
 319 sub pdb_atomname {
 320         my($self, $value) = @_;
 321
 322         if (defined $value) {
 323                 $self->{'pdb_atomname'} = $value;
 324         }
 325         return $self->{'pdb_atomname'};
 326 }
 327
 328
 329 =head2 element()
 330
 331  Title   : element
 332  Usage   : $element = $atom->element($element)
 333  Function: Sets/gets the element
 334  Returns : Returns the element for this atom
 335  Args    : reference to an Atom
 336
 337 =cut
 338
 339 sub element {
 340         my($self, $value) = @_;
 341
 342         if (defined $value) {
 343                 $self->{'element'} = $value;
 344         }
 345         return $self->{'element'};
 346 }
 347
 348
 349 =head2 charge()
 350
 351  Title   : charge
 352  Usage   : $charge = $atom->charge($charge)
 353  Function: Sets/gets the charge
 354  Returns : Returns the charge for this atom
 355  Args    : reference to an Atom
 356
 357 =cut
 358
 359 sub charge {
 360         my($self, $value) = @_;
 361
 362         if (defined $value) {
 363                 $self->{'charge'} = $value;
 364         }
 365         return $self->{'charge'};
 366 }
 367
 368
 369 =head2 sigx()
 370
 371  Title   : sigx
 372  Usage   : $sigx = $atom->sigx($sigx)
 373  Function: Sets/gets the sigx
 374  Returns : Returns the sigx for this atom
 375  Args    : reference to an Atom
 376
 377 =cut
 378
 379 sub sigx {
 380         my($self, $value) = @_;
 381
 382         if (defined $value) {
 383                 $self->{'sigx'} = $value;
 384         }
 385         return $self->{'sigx'};
 386 }
 387
 388
 389 =head2 sigy()
 390
 391  Title   : sigy
 392  Usage   : $sigy = $atom->sigy($sigy)
 393  Function: Sets/gets the sigy
 394  Returns : Returns the sigy for this atom
 395  Args    : reference to an Atom
 396
 397 =cut
 398
 399 sub sigy {
 400         my($self, $value) = @_;
 401
 402         if (defined $value) {
 403                 $self->{'sigy'} = $value;
 404         }
 405         return $self->{'sigy'};
 406 }
 407
 408
 409 =head2 sigz()
 410
 411  Title   : sigz
 412  Usage   : $sigz = $atom->sigz($sigz)
 413  Function: Sets/gets the sigz
 414  Returns : Returns the sigz for this atom
 415  Args    : reference to an Atom
 416
 417 =cut
 418
 419 sub sigz {
 420         my($self, $value) = @_;
 421
 422         if (defined $value) {
 423                 $self->{'sigz'} = $value;
 424         }
 425         return $self->{'sigz'};
 426 }
 427
 428
 429 =head2 sigocc()
 430
 431  Title   : sigocc
 432  Usage   : $sigocc = $atom->sigocc($sigocc)
 433  Function: Sets/gets the sigocc
 434  Returns : Returns the sigocc for this atom
 435  Args    : reference to an Atom
 436
 437 =cut
 438
 439 sub sigocc {
 440         my($self, $value) = @_;
 441
 442         if (defined $value) {
 443                 $self->{'sigocc'} = $value;
 444         }
 445         return $self->{'sigocc'};
 446 }
 447
 448
 449 =head2 sigtemp()
 450
 451  Title   : sigtemp
 452  Usage   : $sigtemp = $atom->sigtemp($sigtemp)
 453  Function: Sets/gets the sigtemp
 454  Returns : Returns the sigtemp for this atom
 455  Args    : reference to an Atom
 456
 457 =cut
 458
 459 sub sigtemp {
 460         my($self, $value) = @_;
 461
 462         if (defined $value) {
 463                 $self->{'sigtemp'} = $value;
 464         }
 465         return $self->{'sigtemp'};
 466 }
 467
 468
 469 =head2 aniso()
 470
 471  Title   : aniso
 472  Usage   : $u12 = $atom->aniso("u12", $u12)
 473  Function: Sets/gets the anisotropic temperature factors
 474  Returns : Returns the requested factor for this atom
 475  Args    : reference to an Atom, name of the factor, value for the factor
 476
 477 =cut
 478
 479 sub aniso {
 480         my($self, $name, $value) = @_;
 481
 482         if ( !defined $name) {
 483                 $self->throw("You need to supply a name of the anisotropic temp factor you want to get");
 484         }
 485         if (defined $value) {
 486                 $self->{$name} = $value;
 487         }
 488         return $self->{$name};
 489 }
 490
 491 # placeholders
 492 sub u11 {
 493         my ($self, $name, $value) = @_;
 494         $self->aniso($name,$value);
 495 }
 496 sub u22 {
 497         my ($self, $name, $value) = @_;
 498         $self->aniso($name,$value);
 499 }
 500 sub u33 {
 501         my ($self, $name, $value) = @_;
 502         $self->aniso($name,$value);
 503 }
 504 sub u12 {
 505         my ($self, $name, $value) = @_;
 506         $self->aniso($name,$value);
 507 }
 508 sub u13 {
 509         my ($self, $name, $value) = @_;
 510         $self->aniso($name,$value);
 511 }
 512 sub u23 {
 513         my ($self, $name, $value) = @_;
 514         $self->aniso($name,$value);
 515 }
 516 sub sigu11 {
 517         my ($self, $name, $value) = @_;
 518         $self->aniso($name,$value);
 519 }
 520 sub sigu22 {
 521         my ($self, $name, $value) = @_;
 522         $self->aniso($name,$value);
 523 }
 524 sub sigu33 {
 525         my ($self, $name, $value) = @_;
 526         $self->aniso($name,$value);
 527 }
 528 sub sigu12 {
 529         my ($self, $name, $value) = @_;
 530         $self->aniso($name,$value);
 531 }
 532 sub sigu13 {
 533         my ($self, $name, $value) = @_;
 534         $self->aniso($name,$value);
 535 }
 536 sub sigu23 {
 537         my ($self, $name, $value) = @_;
 538         $self->aniso($name,$value);
 539 }
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553 =head2 id()
 554
 555  Title   : id
 556  Usage   : $atom->id("CZ2")
 557  Function: Gets/sets the ID for this atom
 558  Returns : the ID
 559  Args    : the ID
 560
 561 =cut
 562
 563 sub id {
 564         my ($self, $value) = @_;;
 565         if (defined $value) {
 566                 $self->{'id'} = $value;
 567         }
 568         return $self->{'id'};
 569 }
 570
 571 sub DESTROY {
 572         my $self =  shift;
 573
 574         # dummy, nothing needs to be done here
 575 }
 576
 577 #
 578 # from here on only private methods
 579 #
 580
 581 =head2 _remove_residue()
 582
 583  Title   : _remove_residue
 584  Usage   :
 585  Function: Removes the Residue this Atom is atttached to.
 586  Returns :
 587  Args    :
 588
 589 =cut
 590
 591 sub _remove_residue {
 592         my ($self) = shift;
 593
 594         $self->throw("no code here at the moment\n");
 595 }
 596
 597
 598 =head2 _grandparent()
 599
 600  Title   : _grandparent
 601  Usage   :
 602  Function: get/set a symbolic reference to our grandparent
 603  Returns :
 604  Args    :
 605
 606 =cut
 607
 608 sub _grandparent {
 609         my($self,$symref) = @_;
 610
 611         if (ref($symref)) {
 612                 $self->throw("Thou shall only pass strings in here, no references $symref\n");
 613         }
 614         if (defined $symref) {
 615                 $self->{'grandparent'} = $symref;
 616         }
 617         return $self->{'grandparent'};
 618 }
 619
 620
 621 1;