org.proteinshader.structure
Class Structure

java.lang.Object
  org.proteinshader.structure.Structure

All Implemented Interfaces:

IDTest, Visitable

public class Structure
extends Object
implements IDTest, Visitable

Structure is the top-level container for objects that store information on a protein structure from the Protein Data Bank. The primary data structure can be described as follows:

Structure - holds at least one Model.
Model - holds at least one Chain.
Chain - holds at least one Residue.
Residue - holds at least one Atom.
Atom - holds any Bonds where it is the source Atom.

A Structure also holds a single Description object, which holds Category objects that are used to group together Record objects, where each Record object holds a list of Strings read from a PDB file.

A Chain also holds a collection of SecondaryStructure objects, which are used to represent alpha-helices and beta-strands.

An important design decision is that classes in package structure hold not only the data from a Protein Data Bank entry, but also hold data needed purely for display purposes (e.g. atom radius, colors, textures, and visibility status). The reason for this decision is that the user is allowed to select almost any object in order to change how it is displayed, and it seems simpler to bundle all information on something like an Atom in one place, rather than have a second display-info data structure that would be almost equal in size and complexity to a Structure that held only Protein Data Bank information.

In almost all cases, numeric data from a Protein Data Bank entry is stored in final instance variables, and, therefore, must be set by the constructor and can have only getter methods. The changeable data needed purely for display purposes will of course have setter and getter methods.

Field Summary

static int

SERIAL_NO_CACHE_CAPACITY Default starting capacity for Atom serial number cache.

Constructor Summary

Structure(String structureID)
Constructs a Structure with the requested structureID.

Method Summary

void	accept(Visitor visitor) Accepts a Visitor and does a callback.
Atom	addNewAtom(int atomSerialNo, AtomEnum atomType, String atomID, String aminoAcidType, String residueID, String chainID, String modelID, double temperature, int charge, double occupancy, String altLocation, double x, double y, double z, VisibilityEnum visibility) Creates a new atom with the atomID given as an argument, adds the new Atom to the requested Model-Chain-AminoAcid, and then returns a reference to the new Atom.
void	addNewBetaStrand(String chainID, String betaStrandID, String betaStrandNumber, String sheetID, String startResidueID, String endResidueID, int sense, int strandsInSheet) The BetaStrand will be added to the equivalent Chain on each Model, but this addition will only work if the sequence of Residues that the BetaStrand refers to have already been added.
void	addNewHelix(String chainID, String helixID, String serialNo, String startResidueID, String endResidueID, HelixEnum type) The Helix will be added to the equivalent Chain on each Model, but this addition will only work if the sequence of Residues that the Helix refers to have already been added.
Atom	addNewHetAtom(int atomSerialNo, AtomEnum atomType, String atomID, String hetName, String residueID, String chainID, String modelID, double temperature, int charge, double occupancy, String altLocation, double x, double y, double z, VisibilityEnum visibility) Creates a new atom with the atomID given as an argument, adds the new Atom to the requested Model-Chain-(Heterogen or Water), and then returns a reference to the new Atom.
Model	addNewModel(String modelID) Creates a Model, adds it to the Structure, and returns a reference to the new Model.
void	calculateBounds() Sets the min and max values for x, y, and z on each Model held by the Structure.
void	calculateFrenetFrames() Before Regions objects (Helix, BetaStrand, and Loop) are added to the Structure, a rotation (the equivalent to a discrete Frenet Frame) should be calculated for each AminoAcid.
void	clearAllBonds() Clears all Bonds (AminoAcids, Heterogens, and Waters) from the Structure.
void	clearAtomSerialNoCache() Clears the cache that remembers Atom serial numbers and allows them to be used to retrieve an Atom.
void	clearBonds(ResidueMode residueMode) Clears Bonds from the Structure.
void	generateLoopRegions() Generates Loop objects from any AminoAcids that do not already belong to a Helix or BetaStrand object.
void	generateStandardBonds() Generates standard Bonds (AminoAcids and Waters).
List<String>	getAminoAcidLabels() Returns a list of all AminoAcid residueIDs.
Atom	getAtom(int atomSerialNo) Returns the Atom with Atom serial number given as an argument (or null if not found).
Atom	getAtom(String atomID, String residueID, String chainID, String modelID) Returns the Atom with the IDs given as arguments.
List<Atom>	getAtomSerialNoCache() Returns the Atom serial number cache as a list.
BetaStrand	getBetaStrand(String betaStrandID, String modelID) Returns the BetaStrand with the IDs given as arguments.
Chain	getChain(String chainID, String modelID) Returns the Chain with the IDs given as arguments.
Description	getDescription() Returns a reference to the Description object owned by this Structure.
Helix	getHelix(String helixID, String modelID) Returns the Helix with the IDs given as arguments.
Loop	getLoop(String loopID, String modelID) Returns the Loop with the IDs given as arguments.
Model	getModel(String modelID) Returns the Model with the modelID given as an argument.
Residue	getResidue(String residueID, String chainID, String modelID) Returns the Residue with the IDs given as arguments.
String	getStructureID() Returns the structureID, which is the sames as the PDB unique ID code.
Iterator<Model>	iteratorModels() Returns an Iterator for the Models held by this Structure.
int	numberOfModels() Returns the number of Models held by this Structure.
String	processID(String id, String typeOfID) Returns the ID after trimming any leading or trailing whitespace.
void	sortBetaStrands() Iterates through all Models of the Structure and modifies the linked hash map of beta-strands for each Chain so that when an iterator for beta-strands is handed over (based on the linked list part) the beta-strands will be ordered according to the starting amino acid.
String	toString() Returns the structureID, which is the sames as the PDB unique ID code.

Methods inherited from class java.lang.Object

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

Field Detail

SERIAL_NO_CACHE_CAPACITY

public static final int SERIAL_NO_CACHE_CAPACITY

Default starting capacity for Atom serial number cache.

See Also:

Constant Field Values

Constructor Detail

Structure

public Structure(String structureID)
          throws InvalidIDException

Constructs a Structure with the requested structureID.

The structureID expected as an argument should be the unique PDB ID code for this structure. If there is any leading or trailing whitespace in the structureID, it will be trimmed off. The structureID will be set as a read-only attribute. This constructor will automatically create a Description object with the same structureID. The Description can then be obtained by calling getDescription(), so information from PDB records can be added to it. The structureID will also be used to mark any Models, Chains, Residues, SecondaryStructures, or Atoms that are owned by this Structure.

Parameters:

structureID - the unique ID code assigned by the Protein Data Bank.

Throws:

InvalidIDException - if structureID 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

Parameters:

visitor - the Visitor to do a callback with.

Throws:

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

addNewAtom

public Atom addNewAtom(int atomSerialNo,
                       AtomEnum atomType,
                       String atomID,
                       String aminoAcidType,
                       String residueID,
                       String chainID,
                       String modelID,
                       double temperature,
                       int charge,
                       double occupancy,
                       String altLocation,
                       double x,
                       double y,
                       double z,
                       VisibilityEnum visibility)
                throws MissingAtomTypeException,
                       MissingAATypeException,
                       InvalidIDException

Creates a new atom with the atomID given as an argument, adds the new Atom to the requested Model-Chain-AminoAcid, and then returns a reference to the new Atom.

This method is for adding a standard atom (an atom that belongs to an AminoAcid). The addNewHetAtom() method should be used for adding a Heterogen or Water to the Structure.

If objects corresponding to the modelID, chainID, or residueID already exist, then the Atom is added to the existing Residue. If any of these objects do not exist, then they will be created as needed, so that the Atom can be added to the correct Residue. At creation time, an Atom is stamped with not only its own atomID, but also with all ancestorIDs (ancestor in a container or graph hierarchy sense), so that these IDs can be used later to obtain any desired ancestor (Structure, Model, Chain, or Residue) of an Atom in hand.

The aminoAcidType String arg will be converted to an AminoAcidEnum before calling the AminoAcid constructor.

Parameters:

atomSerialNo - the atom serial number.

atomType - the Atom type as an AtomEnum.

atomID - the ID of the Atom.

aminoAcidType - the AminoAcid type as a String.

residueID - the ID of the AminoAcid to add the Atom to.

chainID - the ID of the Chain to add the Atom to.

modelID - the ID of the Model to add the Atom to.

temperature - the x-ray crystallography temperature factor.

charge - optional measure of electric charge.

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

altLocation - alternate location if occupancy less than 1.0.

x - x-coordinate of the Drawable's center.

y - y-coordinate of the Drawable's center.

z - z-coordinate of the Drawable's center.

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

Returns:

The newly created Atom.

Throws:

MissingAtomTypeException - if atomType is null.

MissingAATypeException - if aminoAcidType is null or cannot be converted to an AminoAcidEnum.

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

addNewHetAtom

public Atom addNewHetAtom(int atomSerialNo,
                          AtomEnum atomType,
                          String atomID,
                          String hetName,
                          String residueID,
                          String chainID,
                          String modelID,
                          double temperature,
                          int charge,
                          double occupancy,
                          String altLocation,
                          double x,
                          double y,
                          double z,
                          VisibilityEnum visibility)
                   throws MissingAtomTypeException,
                          MissingHetNameException,
                          InvalidIDException

Creates a new atom with the atomID given as an argument, adds the new Atom to the requested Model-Chain-(Heterogen or Water), and then returns a reference to the new Atom.

This method is for adding an Atom that belongs to a Heterogen or Water. The addNewAtom() method should be used for adding an Atom to an AminoAcid.

If objects corresponding to the modelID, chainID, or residueID already exist, then the Atom is added to the existing Residue. If any of these objects do not exist, then they will be created as needed, so that the Atom can be added to the correct Residue. At creation time, an Atom is tamped with not only its own atomID, but also with all ancestorIDs (ancestor in a container or graph hierarchy sense), so that these IDs can be used later to obtain any desired ancestor (Structure, Model, Chain, or Residue) of an Atom in hand.

Parameters:

atomSerialNo - the atom serial number.

atomType - the Atom type as an AtomEnum.

atomID - the ID of the Atom.

hetName - the heterogen name ("HOH" for Water).

residueID - the ID of the Residue to add the Atom to.

chainID - the ID of the Chain to add the Atom to.

modelID - the ID of the Model to add the Atom to.

temperature - the x-ray crystallography temperature factor.

charge - optional measure of electric charge.

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

altLocation - alternate location if occupancy less than 1.0.

x - x-coordinate of the Drawable's center.

y - y-coordinate of the Drawable's center.

z - z-coordinate of the Drawable's center.

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

Returns:

The newly created Atom.

Throws:

MissingAtomTypeException - if atomType is null.

MissingHetNameException - if the heterogen name is null or does not have at least one non-whitespace character.

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

addNewModel

public Model addNewModel(String modelID)
                  throws InvalidIDException

Creates a Model, adds it to the Structure, and returns a reference to the new Model. Any leading or trailing whitespace in the modelID is automatically trimmed off by the Model constructor, and it must have at least one non-whitespace character. The Model will be stamped with the structureID of this Structure.

Parameters:

modelID - the ID of the Model.

Returns:

The newly created Model.

Throws:

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

calculateFrenetFrames

public void calculateFrenetFrames()
                           throws VisitorException

Before Regions objects (Helix, BetaStrand, and Loop) are added to the Structure, a rotation (the equivalent to a discrete Frenet Frame) should be calculated for each AminoAcid. This rotation (stored in the form of a Quaternion) will be needed for generating the Segment objects that will be used for drawing cartoon versions (tube and ribbons) of each region of protein secondary structure.

Throws:

VisitorException

addNewHelix

public void addNewHelix(String chainID,
                        String helixID,
                        String serialNo,
                        String startResidueID,
                        String endResidueID,
                        HelixEnum type)
                 throws InvalidRegionException,
                        InvalidIDException

The Helix will be added to the equivalent Chain on each Model, but this addition will only work if the sequence of Residues that the Helix refers to have already been added.

Region (the superclass of Helix) will cache the Residues from startResidueID to endResidueID (or throw an exception) so that an iterator to the Region's sequence can be easily obtained.

The Helix shape (a HelixShapeEnum) will be set to Helix.DEFAULT_SHAPE. If the type argument is null, the type will be set to Helix.DEFAULT_TYPE.

Any leading or trailing whitespace in the helixID, serialNo, startResidueID, or endResidueID will be trimmed. The Helix will be stamped with the chainID, modelID, and structureID of the Chain it belongs to.

Parameters:

chainID - the ID of the Chain to add the Helix to.

helixID - the Helix identifier from a PDB HELIX record.

serialNo - the serial number of the Helix.

startResidueID - ID of the first AminoAcid in the sequence.

endResidueID - ID of the last AminoAcid in the sequence.

type - the type of Helix as a HelixEnum.

Throws:

InvalidRegionException - if the sequence of AminoAcids (with at least two Residues) cannot be found on the Chain.

InvalidIDException - if the helixID, serialNo, startResidueID, or endResidueID is null or does not have at least one non-whitespace character.

addNewBetaStrand

public void addNewBetaStrand(String chainID,
                             String betaStrandID,
                             String betaStrandNumber,
                             String sheetID,
                             String startResidueID,
                             String endResidueID,
                             int sense,
                             int strandsInSheet)
                      throws InvalidRegionException,
                             InvalidIDException

The BetaStrand will be added to the equivalent Chain on each Model, but this addition will only work if the sequence of Residues that the BetaStrand refers to have already been added.

Region (the superclass of BetaStrand) will cache the Residues from startResidueID to endResidueID (or throw an exception) so that an iterator to the Region's sequence can be easily obtained.

The sense (orientation) of an individual BetaStrand is 0 if it is the first strand in a sheet, 1 if the strand is parallel to the previous strand in the sheet, and -1 if the strand is anti-parallel to the previous strand in the sheet.

Any leading or trailing whitespace in the betaStrandID, sheetID, startResidueID, or endResidueID will be trimmed. The BetaStrand will be stamped with the chainID, modelID, and structureID of the Chain it belongs to.

Parameters:

chainID - ID of the Chain to add the BetaStrand to.

betaStrandID - unique ID (strand number plus sheet ID).

betaStrandNumber - Strand number from a PDB SHEET record.

sheetID - sheet identifier from a PDB SHEET record

startResidueID - ID of the first AminoAcid in the sequence.

endResidueID - ID of the last AminoAcid in the sequence.

sense - strand sense (0, 1, or -1).

strandsInSheet - total number of BetaStrands in the sheet.

Throws:

InvalidRegionException - if the sequence of AminoAcids (with at least two Residues) cannot be found on the Chain.

InvalidIDException - if the betaStrandID, sheetID, startResidueID, or endResidueID is null or does not have at least one non-whitespace character.

sortBetaStrands

public void sortBetaStrands()

Iterates through all Models of the Structure and modifies the linked hash map of beta-strands for each Chain so that when an iterator for beta-strands is handed over (based on the linked list part) the beta-strands will be ordered according to the starting amino acid.

calculateBounds

public void calculateBounds()
                     throws VisitorException

Sets the min and max values for x, y, and z on each Model held by the Structure.

Throws:

VisitorException - if a Model has no Atoms.

getStructureID

public String getStructureID()

Returns the structureID, which is the sames as the PDB unique ID code. The String returned cannot be null or empty, because the constructor checks that this read-only attribute has at least one non-whitespace character.

Returns:

The unique Protein Data Bank entry identification code as a String.

getDescription

public Description getDescription()

Returns a reference to the Description object owned by this Structure. The Description is used to store text-type information on a PDB entry (title, date, remarks, etc.). The Description returned cannot be null, because the Structure constructor creates the Description object, and there is no setDescription() method. The Description object will always have the same read-only structureID as the Structure that owns it.

Returns:

The Description object owned by this Structure.

getAtom

public Atom getAtom(String atomID,
                    String residueID,
                    String chainID,
                    String modelID)

Returns the Atom with the IDs given as arguments. Returns null if the Atom is not found.

Parameters:

atomID - the ID of the Atom.

residueID - the ID of the Residue the Atom belongs to.

chainID - the ID of the Chain the Atom belongs to.

modelID - the ID of the Model the Atom belongs to.

Returns:

The requested Atom (or null if not found).

getAtom

public Atom getAtom(int atomSerialNo)

Returns the Atom with Atom serial number given as an argument (or null if not found).

Parameters:

atomSerialNo - the atom serial number.

Returns:

The requested Atom (or null if not found).

getResidue

public Residue getResidue(String residueID,
                          String chainID,
                          String modelID)

Returns the Residue with the IDs given as arguments. Returns null if the Residue is not found.

Parameters:

residueID - the ID of the Residue.

chainID - the ID of the Chain the Atom belongs to.

modelID - the ID of the Model the Atom belongs to.

Returns:

The requested Residue (or null if not found).

getHelix

public Helix getHelix(String helixID,
                      String modelID)

Returns the Helix with the IDs given as arguments. Returns null if the Helix is not found.

Parameters:

helixID - the ID of the Helix.

modelID - the ID of the Model the Helix belongs to.

Returns:

The requested Helix (or null if not found).

getBetaStrand

public BetaStrand getBetaStrand(String betaStrandID,
                                String modelID)

Returns the BetaStrand with the IDs given as arguments. Returns null if the BetaStrand is not found.

Parameters:

betaStrandID - the ID of the BetaStrand.

modelID - the ID of the Model the BetaStrand belongs to.

Returns:

The requested BetaStrand (or null if not found).

getLoop

public Loop getLoop(String loopID,
                    String modelID)

Returns the Loop with the IDs given as arguments. Returns null if the Loop is not found.

Parameters:

loopID - the ID of the Loop.

modelID - the ID of the Model the Loop belongs to.

Returns:

The requested Loop (or null if not found).

getChain

public Chain getChain(String chainID,
                      String modelID)

Returns the Chain with the IDs given as arguments. Returns null if the Chain is not found.

Parameters:

chainID - the ID of the Chain.

modelID - the ID of the Model the Chain belongs to.

Returns:

The requested Chain (or null if not found).

getModel

public Model getModel(String modelID)

Returns the Model with the modelID given as an argument. Returns null if modelID does not match any Model in the hash. If modelID is null, an exception is not thrown. Rather, this method simply returns null.

Parameters:

modelID - the unique ID for the desired Model.

Returns:

The requested Model (or null if not found).

iteratorModels

public Iterator<Model> iteratorModels()

Returns an Iterator for the Models held by this Structure. The order of iteration is the same as the order in which Models were added to the Structure. In the rare case where a Model was replaced (by adding a Model with the same modelID), the replacement would not change the iteration order in any way.

Returns:

An Iterator for the Models held by this Structure.

numberOfModels

public int numberOfModels()

Returns the number of Models held by this Structure.

Returns:

The total number of Models.

getAtomSerialNoCache

public List<Atom> getAtomSerialNoCache()

Returns the Atom serial number cache as a list.

Returns:

The list of Atoms.

clearAtomSerialNoCache

public void clearAtomSerialNoCache()

Clears the cache that remembers Atom serial numbers and allows them to be used to retrieve an Atom. This cache is only useful for interpreting CONECT records, so it would save memory to dump the cache after a parser is done with all CONECT records.

generateLoopRegions

public void generateLoopRegions()
                         throws VisitorException

Generates Loop objects from any AminoAcids that do not already belong to a Helix or BetaStrand object. All Helix and BetaStrand objects must be generated before this method is called.

Throws:

VisitorException - if an error occurs while generating Loops.

generateStandardBonds

public void generateStandardBonds()
                           throws VisitorException

Generates standard Bonds (AminoAcids and Waters). This method should be called only after all Atoms from a PDB structure entry have been added to this Structure.

Throws:

VisitorException

clearBonds

public void clearBonds(ResidueMode residueMode)
                throws VisitorException

Clears Bonds from the Structure.

Parameters:

residueMode - the type of Residues to remove Bonds from.

Throws:

VisitorException

clearAllBonds

public void clearAllBonds()
                   throws VisitorException

Clears all Bonds (AminoAcids, Heterogens, and Waters) from the Structure.

Throws:

VisitorException

getAminoAcidLabels

public List<String> getAminoAcidLabels()
                                throws VisitorException

Returns a list of all AminoAcid residueIDs.

This list will be needed by the TextLabelManager object held by the StructureToGraphics object, and it will be used to generate texture maps to place labels on the curved surfaces of Segments rendered as three-dimensional tube or ribbon structures. The same AminoAcid residueID can show up on different Models or even on different Chains within the same Model, but the list will be generated in away that prevents the same residueID from showing up more than once in the list.

Returns:

A non-redundant list of AminoAcid residueIDs.

Throws:

VisitorException

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 (for possible inclusion in 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 structureID, which is the sames as the PDB unique ID code. The String returned cannot be null or empty, because the constructor checks that this read-only attribute has at least one non-whitespace character.

Overrides:

toString in class Object

Returns:

The unique Protein Data Bank entry identification code as a String.