org.proteinshader.structure
Class Atom

java.lang.Object
  org.proteinshader.structure.Drawable
      org.proteinshader.structure.Atom

All Implemented Interfaces:

IDTest, Visitable

public class Atom
extends Drawable
implements IDTest

Extends abstract class Drawable to add data that is unique to an atom (atomID, type, temperature, occupancy, radius, etc.). An Atom also serves as a container for any Bonds where the Atom is the source Atom of the Bond.

The xyz-coordinate attributes are specified in Drawable, as all Drawables must have a position for their center. Conceptually, there are two kinds of information stored on an atom:
1) Mutable (changeable) data on how an atom is to be displayed.
2) Immutable (read-only) data from a PDB structure file.

In a PDB formatted file, each atom in a model will have a one-line record beginning with either ATOM or HETATM. An ATOM record holds the atomic coordinates of an atom that belongs to a standard residue (an amino acid or a nucleotide), while a HETATM record holds the same information for an atom that belongs to a non-standard group such as a water molecule, a metal ion, or any other group that is not an amino acid or a nucleotide.

Atom Attributes

The description of Atom attributes below refers to PDB formatted files, but the equivalent imformation can also be found in other file types (such as PDBML/XML or mmCIF). Most of the attributes are read-only, so they are set by the constructor and have only a getter method. Radius and charge, however, can be modified, so they also have a setter method.

Atom ID

If the Atom's Id (atomID argument of constructor) is the Atom name from a PDB formatted file, the info will be found in columns 13-16 of an ATOM record. The name usually combines an atomic symbol (columns 13-14), a remoteness indicator (column 15), and a branch designator (column 16). For example, in the 4 letter name ' CG1', ' C' stands for carbon, 'G' stands for gamma (atom position can be designated as alpha, beta, gamma, etc.), and '1' denotes the branch of a beta-branched amino acid.

Atom Type

AtomEnum is an enumeration of elements: CARBON, OXYGEN, etc. The one or two character symbol for an element is given in columns 77-78 of an ATOM record, which should be used rather than trying to extract the atom type from the name given in columns 13-16. The names of some large hetamers and some hydrogens are unable to follow the column 13-16 name conventions mentioned above, so columns 77-78 are used to specify the element unambiguously. However, the use of columns 77-78 for this purpose was added to the PDB specification in 1996, so older files may only have the element in columns 13-14.

Temperature

The temperature factor is specified in columns 61-66 of an ATOM record, and is intended as a measure of the degree of certainty for its xyz-coordinates. Temperatures of 20 or less indicate a well refined, correct structure, while temperatures greater than 40 indicate that a region is very flexible, or that considerable error is present.

Occupancy

Occupancy is specified in columns 55-60 of an ATOM record. If all protein molecules in a crystal have exactly the same conformation, then the occupancy for each atom should be 1.0. However, if 70% of the molecules have one conformation, and 30% have a slightly different conformation, then some atoms will be found in two locations. Such an atom would have two ATOM records, with 0.7 occupancy for one xyz-coordinate, and 0.3 occupancy for the other xyz-coordinate. The first version of the ProteinShader will show only the higher occupancy position for the atom, but a later version might show both and use the occupancy as an alpha value for semi-transparent atoms.

Radius

The default radius for an Atom is the van der Waals radius found in the AtomEnum, and its value can be scaled with scaleRadius(). The van der Waals radius is the radius normally used in space-filling models. Because a smaller size radius is required for use in a stick-and-ball type model, a ballRadius has been added to the AtomEnum. The ballRadius is set to some fraction of the covalent radius multiplied by BALL_SCALE. In class Atom, it can be scaled with scaleBallRadius().

Charge

The charge on an atom is specified in columns 79-80 of an ATOM record. This optional field was added in 1996, so it will not be used in older records. Charges are indicated by 2 characters in a form such as '2+', '1+', '1-', '2-', etc. The charge is often omitted from PDB files, so the user may want to modify this attribute.

Alternate Location

An alternate location identifier is specified as a character in column 17 of an ATOM record. Usually this column is blank, but if the occupancy attribute described right above is less than 1.0, then each alternate location for the atom should have a label like 'A' or 'B'.

Alternate Atom

If there is more than one location for an atom, the Atom object with the higher occupancy will hold a pointer to an Atom object that holds the coordinates for the lower occupancy position. Usually there will be only two alternate locations, but three might occur very rarely. Thefirst version of ProteinShader will only look at the Atom with the highest occupancy, but a later version might want to follow any altAtomreferences and have the option to display the alternate location.

Field Summary

Fields inherited from class org.proteinshader.structure.Drawable

DEFAULT_ALPHA, DEFAULT_BLUE, DEFAULT_GREEN, DEFAULT_RADIUS, DEFAULT_RED, DEFAULT_SPECULAR_EXP

Constructor Summary

Atom(int serialNo, AtomEnum type, String atomID, String residueID, String chainID, String modelID, String structureID, double temperature, int charge, double occupancy, String altLocation, double x, double y, double z, VisibilityEnum visibility)
This constructor uses the type argument (an AtomEnum) to set the default radius and CPK color for the Atom.

Method Summary

void	accept(Visitor visitor) Accepts a Visitor and does a callback.
void	addNewBond(Atom dstAtom, BondEnum type, VisibilityEnum visibility) Adds a new Bond with this Atom as the source Atom and the Atom given as an argument as the destination Atom.
void	clearBonds() Deletes all Bonds held by this Atom.
Atom	getAltAtom() Returns an alternate Atom with a lower occupancy (if it exists).
String	getAltLocation() Returns the alternate location if the occupancy is less than 1.0.
AminoAcidEnum	getAminoAcidType() If the Atom belongs to an AminoAcid, this method will return the AminoAcid type.
String	getAtomID() Returns the ID of this Atom.
double	getBallRadius() Returns the ball radius (for use in stick-and-ball type models).
Bond	getBond(Atom dstAtom) Returns the Bond from this Atom (the source) to the destination Atom.
String	getChainID() Returns the ID of the Chain that this Atom belongs to.
int	getCharge() Returns the electrical charge on the Atom.
String	getModelID() Returns the ID of the Model that this Atom belongs to.
double	getOccupancy() Returns the occupancy, which will be less than 1.0 only if the atom occupies more than one position in a crystal.
String	getResidueID() Returns the ID of the Residue that this Atom belongs to.
Segment	getSegment() Returns the Segment the Atom is associated with (or null if the Atom is not associated with any Segment).
int	getSerialNo() Returns the Atom serial number.
String	getStructureID() Returns the ID of the Structure that this Atom belongs to.
double	getTemperature() Returns the temperature factor from x-ray crystallography.
AtomEnum	getType() Returns the Atom's type as an enum based on the periodic table of the elements.
Iterator<Bond>	iteratorBonds() Returns an Iterator for the Bonds held by this Atom.
int	numberOfBonds() Returns the number of Bonds held by this Atom.
String	processID(String id, String typeOfID) Returns the ID after trimming any leading or trailing whitespace.
void	removeBond(Atom dstAtom) Removes the Bond from this Atom (the source) to the destination Atom.
void	removeBond(Bond bond) Removes the Bond if it exists.
void	scaleBallRadius(double scale) Scales the ball radius for use in stick-and-ball type models.
void	setAlphaToDefault() Uses the Atom type to set the alpha component of the color to the default value specified in AtomEnum.
void	setAltAtom(Atom atom) Sets the alternate Atom.
void	setAminoAcidType(AminoAcidEnum aminoAcidType) Marks the Atom as belonging to a particular type of AminoAcid.
void	setBallRadius(double ballRadius) Sets the ball radius for use in stick-and-ball type models.
void	setBallRadiusToDefault() Uses the AtomEnum type to set the ball radius to a fraction of the covalent radius.
void	setCharge(int charge) Sets the electrical charge on the Atom.
void	setRadiusToDefault() Uses the AtomEnum type to set the radius to the van der Waals radius.
void	setRGBToDefault() Uses the Atom type to set the RGB (red, green, blue) color components to the default CPK color value specified in AtomEnum.
void	setSegment(Segment s) Sets the Segment the Atom is associated with.
void	setToAminoAcidColor() Sets the color of this Atom to the color of the AminoAcid it belongs to (if any).
String	toString() Returns the ID of this Atom.

Methods inherited from class org.proteinshader.structure.Drawable

distance, getAlpha, getAngstromsPerPixel, getBlue, getCameraDepth, getCameraDistance, getColor, getDrawableType, getGreen, getPoint, getRadius, getRed, getSpecularExp, getTranslation, getVisibility, getX, getY, getZ, minus, scaleRadius, setAlpha, setAngstromsPerPixel, setCameraDepth, setCameraDistance, setColor, setColor, setColor, setRadius, setRGBAToDefault, setSpecularExp, setSpecularExpToDefault, setVisibility

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Atom

public Atom(int serialNo,
            AtomEnum type,
            String atomID,
            String residueID,
            String chainID,
            String modelID,
            String structureID,
            double temperature,
            int charge,
            double occupancy,
            String altLocation,
            double x,
            double y,
            double z,
            VisibilityEnum visibility)
     throws MissingAtomTypeException,
            InvalidIDException

This constructor uses the type argument (an AtomEnum) to set the default radius and CPK color for the Atom. The new Atom will be stamped with the structureID, modelID, chainID, and residueID of the Residue, which are read-only attributes. The type argument cannot be null, or a MissingAtomTypeException will be thrown. An InvalidIDException will be thrown if atomID is null or an empty String (leading or trailing white space are trimmed from the atomID).

Parameters:

serialNo - Atom serial number.

type - Atom type as an AtomEnum.

atomID - ID of this Atom.

residueID - ID of the Residue the Atom belongs to.

chainID - ID of the Chain the Atom belongs to.

modelID - ID of the Model the Atom belongs to.

structureID - ID of the Structure the Atom belongs to.

temperature - x-ray crystallography temperature factor.

charge - optional measure of an atom's electric charge.

occupancy - less than 1 if atom has more than one location.

altLocation - alternate location if occupancy less than 1.0.

x - coordinate of the Drawable's center.

y - coordinate of the Drawable's center.

z - coordinate of the Drawable's center.

visibility - visibility status (OPAQUE, TRANSLUCENT, or INVISIBLE).

Throws:

MissingAtomTypeException - if type is null.

InvalidIDException - if atomID is null or does not have at least one non-whitespace character.

Method Detail

accept

public void accept(Visitor visitor)
            throws VisitorException

Accepts a Visitor and does a callback.

Specified by:

accept in interface Visitable

Specified by:

accept in class Drawable

Parameters:

visitor - the Visitor to do a callback with.

Throws:

VisitorException - if an error occurs while an object is being visited.

getSerialNo

public int getSerialNo()

Returns the Atom serial number.

Returns:

The Atom serial number as an int.

getAtomID

public String getAtomID()

Returns the ID of this Atom. The String returned cannot be null or empty, because the constructor checks that this read-only attribute has at least one character.

Returns:

The Atom ID as a String.

getResidueID

public String getResidueID()

Returns the ID of the Residue that this Atom belongs to.

Returns:

The Residue ID as a String.

getChainID

public String getChainID()

Returns the ID of the Chain that this Atom belongs to.

Returns:

The Chain ID as a String.

getModelID

public String getModelID()

Returns the ID of the Model that this Atom belongs to.

Returns:

The Model ID as a String.

getStructureID

public String getStructureID()

Returns the ID of the Structure that this Atom belongs to.

Returns:

The Structure ID as a String.

getType

public AtomEnum getType()

Returns the Atom's type as an enum based on the periodic table of the elements.

Returns:

The type as an AtomEnum.

getAminoAcidType

public AminoAcidEnum getAminoAcidType()

If the Atom belongs to an AminoAcid, this method will return the AminoAcid type. Otherwise, returns null.

Returns:

The AminoAcid type as an AminoAcidEnum (or null).

getTemperature

public double getTemperature()

Returns the temperature factor from x-ray crystallography.

Returns:

The temperature as a double.

getBallRadius

public double getBallRadius()

Returns the ball radius (for use in stick-and-ball type models). The ball radius is defined in AtomEnum as some fraction of the covalent radius.

Returns:

The ball radius as a double.

getSegment

public Segment getSegment()

Returns the Segment the Atom is associated with (or null if the Atom is not associated with any Segment).

Returns:

The associated Segment (or null).

setAminoAcidType

public void setAminoAcidType(AminoAcidEnum aminoAcidType)

Marks the Atom as belonging to a particular type of AminoAcid. This method was added so that the color of the Atom can be set based on AminoAcid type (if desired).

Parameters:

aminoAcidType - The type of AminoAcid the Atom belongs to.

setRadiusToDefault

public void setRadiusToDefault()

Uses the AtomEnum type to set the radius to the van der Waals radius. This is the radius recommended for use in space-filling models.

Overrides:

setRadiusToDefault in class Drawable

scaleBallRadius

public void scaleBallRadius(double scale)

Scales the ball radius for use in stick-and-ball type models.

Parameters:

scale - the scale factor to multiply the default ball radius by.

setBallRadius

public void setBallRadius(double ballRadius)

Sets the ball radius for use in stick-and-ball type models.

Parameters:

ballRadius - the ball radius.

setBallRadiusToDefault

public void setBallRadiusToDefault()

Uses the AtomEnum type to set the ball radius to a fraction of the covalent radius.

setToAminoAcidColor

public void setToAminoAcidColor()

Sets the color of this Atom to the color of the AminoAcid it belongs to (if any). If the Atom does not belong to any AminoAcid, then calling this method will have no effect.

setRGBToDefault

public void setRGBToDefault()

Uses the Atom type to set the RGB (red, green, blue) color components to the default CPK color value specified in AtomEnum. Default color values must always be in a range of 0.0 to 1.0, inclusive.

Overrides:

setRGBToDefault in class Drawable

setAlphaToDefault

public void setAlphaToDefault()

Uses the Atom type to set the alpha component of the color to the default value specified in AtomEnum. The default alpha value must always be in a range of 0.0 to 1.0, inclusive.

Overrides:

setAlphaToDefault in class Drawable

getCharge

public int getCharge()

Returns the electrical charge on the Atom.

Returns:

The charge as an int.

setCharge

public void setCharge(int charge)

Sets the electrical charge on the Atom.

Parameters:

charge - the electrical charge as an int.

getOccupancy

public double getOccupancy()

Returns the occupancy, which will be less than 1.0 only if the atom occupies more than one position in a crystal.

Returns:

The occupancy as a double.

getAltLocation

public String getAltLocation()

Returns the alternate location if the occupancy is less than 1.0.

Returns:

The alternate location as a String.

getAltAtom

public Atom getAltAtom()

Returns an alternate Atom with a lower occupancy (if it exists).

Returns:

The alternate Atom object.

setAltAtom

public void setAltAtom(Atom atom)

Sets the alternate Atom.

Parameters:

atom - the alternate Atom object.

setSegment

public void setSegment(Segment s)

Sets the Segment the Atom is associated with.

Parameters:

s - the Segment.

addNewBond

public void addNewBond(Atom dstAtom,
                       BondEnum type,
                       VisibilityEnum visibility)

Adds a new Bond with this Atom as the source Atom and the Atom given as an argument as the destination Atom.

Parameters:

dstAtom - The destination Atom for the Bond.

type - the type of Bond (SINGLE, DOUBLE, etc.)

visibility - visibility status (OPAQUE, TRANSLUCENT, or INVISIBLE)

Throws:

NullPointerException - if dstAtom is null.

getBond

public Bond getBond(Atom dstAtom)

Returns the Bond from this Atom (the source) to the destination Atom. Returns null if the Bond does not exist.

Returns:

The Bond from this Atom to a destination Atom.

removeBond

public void removeBond(Atom dstAtom)

Removes the Bond from this Atom (the source) to the destination Atom. No action is taken if the Bond does not exist.

Parameters:

dstAtom - the destination Atom for the Bond.

removeBond

public void removeBond(Bond bond)

Removes the Bond if it exists. No action is taken if the Bond does not exist.

Parameters:

bond - the Bond to remove.

iteratorBonds

public Iterator<Bond> iteratorBonds()

Returns an Iterator for the Bonds held by this Atom. The order of iteration is the same as the order in which Bonds were added to the Atom. In the rare case where a Bond was replaced (by adding a Bond to the same destination Atom), the replacement would ot change the iteration order in any way.

Returns:

An Iterator for the Bonds held by this Atom.

numberOfBonds

public int numberOfBonds()

Returns the number of Bonds held by this Atom.

Returns:

The total number of Bonds as an int.

clearBonds

public void clearBonds()

Deletes all Bonds held by this Atom.

processID

public String processID(String id,
                        String typeOfID)
                 throws InvalidIDException

Returns the ID after trimming any leading or trailing whitespace. An ID must have at least one non-whitespace character.

Specified by:

processID in interface IDTest

Parameters:

id - the ID to process.

typeOfID - the type of ID (if needed in an error message).

Returns:

The trimmed ID.

Throws:

InvalidIDException - if the trimmed ID does not have at least one character.

toString

public String toString()

Returns the ID of this Atom. The String returned cannot be null or empty, because the constructor checks that this read-only attribute has at least one character.

Overrides:

toString in class Object

Returns:

The Atom ID as a String.