Tutorial:Molecular Object Getters

The identifiers

There are 5 pieces of information to identify an atom:

1. chain
2. residue number
3. insertion code
4. residue name
5. atom name

Now this information can be passed using "identifiers", i.e. comma separated strings that specify a Chain, Position, Residue or Atom in this order. There is an identifier for each level and their syntax is the following:

1. Chain identifier: "A"
2. Position identifier: "A,37" or "A,37A" with an icode
3. Identity: "A,37,ILE" "A,37A,ILE"
4. Atom: "A,37,CA" "A,37A,CA"
5. Atom of a specific identity: "A,37,ILE,CA" "A,37A,CA"

Space separated identifier are also parsed ("A 37 CA"), as well as underscore separated ("A_37_CA")

Getters

The getters have been rationalized. Here are the examples that apply to the System but the usage is made homogeneous across the hierarchy (Position, Residue, Atom)

In the System we have now 3 getters:

by index (starting from 0, like an array)

Chain & getChain(unsigned int _index);
Atom & getPosition(unsigned int _index);
Residue & getIdentity(unsigned int _index); // the current identity of the _index position
Atom & getAtom(unsigned int _index);

by individual fields (note, the icode is now always required, if there is no icode, use a blank string)

Chain & getChain(string _chain);
Position & getPosition(string _chain, int _resnum, string _icode);
Residue & getIdentity(string _chain, int _resnum, string _icode, string _resname);
Atom & getAtom(string _chain, int _resnum, string _icode, string atomName); // active identity
Atom & getAtom(string _chain, int _resnum, string _icode, string _resname, string atomName);

and finally by identifier

Chain & getChain(string _chainid); // "A"
Atom & getPosition(string _positionId); // "A,37" "A,37A"
Residue & getIdentity(string _identityId); // "A,37,ILE" "A,37A, ILE"
Atom & getAtom(string _atomId); // "A,37,CA" "A,37,ILE,CA"

Exists functions

The functions atomExists, identityExists, positionExists and chainExists check for the existance of a Chain/Position/Residue/Atom and store a reference to the address of the object. The object can then be retreived using a getLastFoundXxxx function (getLastFoundChain(), getLastFoundPosition(), getLastFoundIdentity(), getLastFoundAtom()).

The various exists function take the same arguments of the getters, for example:

bool chainExists(string _chainId); // "A"
bool positionExists(string _chain, int _resnum, string _icode);
bool positionExists(string _positionId); // "A,37"
bool identityExists(string _chain, int _resnum, string _icode, string _resname);
bool identityExists(string _identityId); // "A,37,LEU"
bool atomExists(string _atomId); // "A,37,CA" "A,37,ILE,CA"
bool atomExists(string _chain, int _resnum, string _icode, string _resname, string atomName);

So the safest and most efficient way to code is something on the lines of the following:

System sys;
if (sys.chainExists("A") {
	Chain & chainA = sys.getLastFoundChain();
}
if (sys.positionExists("A,37") {
	Position & posA37 = sys.getLastFoundPosition();
}
if (sys.identityExists("A,37,ILE") {
	Residue & resA37ILE = sys.getLastFoundIdentity();
}
if (sys.atomExists("A,37,CA") {
  Atom & atomA37CA = sys.getLastFoundAtom();
}

Atoms, Residues, Positions and Chains can return their identifier:

string chainId = chain.getChainId();         // returns "A"
string posId = pos.getPositionId();          // returns "A,37"
string identityId = res.getIdentityId();     // returns "A,37,ILE"
string atomId = atom.getAtomId();            // returns "A,37,CA"
string atomId = atom.getAtomofIdentityId();  // returns "A,37,ILE,CA"

Operators

The braket operators are wrapper for the "by index" and "by identifier" getters. The round braket () always return the next down in the hierarchy (System->Chain->Position->Residue->Atom). The square braket [] returns Atoms for all objects

// round () returns the "next" object in the hierarchy
sys.getChain("A") <-> sys("A")  // by chainId
sys.getChain(2) <-> sys(2)      // 3-rd atom in the array
// square [] always return atoms
sys.getAtom("A,37,CA") <-> sys["A,37,CA"]   // by atomId
sys.getAtom(56) <-> sys[56]                 // 57-th atom

Going down the hierarchy things behave similarly

Chain

The following is the API for the Chain. Very similar to the one of System, but note how the chain id drops from the identifier ("A,37,CA" becomes "37,CA"). "A,37,CA" is actually legal, but the chain ID is ignored, it will just look for resnum 37, icode "" and name "CA"

// getters
Position & getPosition(unsigned int _index);
Position & getPosition(int _resnum, string _icode);
Position & getPosition(string _positionId); // "37" or "37A"
Residue & getIdentity(unsigned int _index);
Residue & getIdentity(int _resnum, string _icode, string _identity);
Residue & getIdentity(string _identityId); // "37,ILE" or "37A,ILE"
Atom & getAtom(unsigned int _index);
Atom & getAtom(int _resnum, string _icode, string _atomName);
Atom & getAtom(int _resnum, string _icode, string _identity, string _atomName);
Atom & getAtom(string _atomId); // "37,ILE,CA" or "37,CA"
// existance
bool positionExists(int _resnum, string _icode);
bool positionExists(string _positionId); // "37" or "37A"
// ...
bool atomExists(string _atomId); "37,CA" "37,ILE,CA"
// getters operators () []
Position & operator()(unsigned int _index);
Position & operator()(string _positionId);  // "37" or "37A"
Atom & operator[](unsigned int _index);
Atom & operator[](string _atomId);  "37,CA" "37,ILE,CA"

Position

// getters
Residue & getIdentity(unsigned int _index);
Residue & getIdentity(string _identityId); // "ILE"
Atom & getAtom(unsigned int _index);
Atom & getAtom(string _identity, string _atomName);
Atom & getAtom(string _atomId); // "ILE,CA" or "CA"
// existance
bool identityExists(string _identityId); // "ILE"
// ...
bool atomExists(string _identity, string _atomName);
bool atomExists(string _atomId); "37,CA" "37,ILE,CA"
// getters operators () []
Residue & operator()(unsigned int _index);
Residue & operator()(string _identityId);  // "ILE"
Atom & operator[](unsigned int _index);
Atom & operator[](string _atomId);  "CA" "ILE,CA"

Residue

// getters
Atom & getAtom(unsigned int _index);
Atom & getAtom(string _atomId); // "CA"
// existance
bool atomExists(string _atomId); "CA"
// getters operators []
Atom & operator[](unsigned int _index);
Atom & operator[](string _atomId);  "CA"