Data class CAtom represents an atom in the coordinate hierarchy. As a special case, it may also represent a chain terminator - the equivalent of PDB TER card.
CAtom contains all information, which is relevant to particular atom, and reference to residue that contains the atom. Each instance of the class may be represented by several PDB records - ATOM, HETATM, SIGATM, ANISOU, SIGUIJ or TER.Public Data Fields | |
Function | Purpose |
CAtom::CAtom | Default constructor.
|
CAtom::CAtom | Add-to-residue constructor.
|
CAtom::~CAtom | The class' destructor.
|
CAtom::GetModelNum | Obtaining number of model containing the atom.
|
CAtom::GetChainID | Obtaining identifier of chain containing the atom.
|
CAtom::GetResName | Obtaining name of residue containing the atom.
|
CAtom::GetSeqNum | Obtaining sequence number of residue containing the atom.
|
CAtom::GetInsCode | Obtaining insertion code of residue containing the atom.
|
CAtom::GetResidue | Obtaining pointer on residue containing the atom.
|
CAtom::GetChain | Obtaining pointer on chain containing the atom.
|
CAtom::GetModel | Obtaining pointer on model containing the atom.
|
CAtom::isInSelection | Checking if atom is selected.
|
CAtom::SetAtomName | Setting the atom name.
|
CAtom::SetElementName | Setting the chamical element name.
|
CAtom::MakeTer | Converting atom into chain terminator.
|
CAtom::SetCoordinates | Setting coordinates, occupancy and temperature factor
for the atom.
|
CAtom::GetAtomID | Obtaining a full atom's coordinate ID.
|
CAtom::GetAtomIDfmt | Obtaining a full, formatted atom's coordinate ID.
|
CAtom::CheckID | Checking the atom's ID by atom name, chemical
element name and alternative location indicator.
|
CAtom::CheckIDS | Checking the atom's ID by coordinate ID.
|
CAtom::Transform | Transformation of atom coordinates with 3x3-matrix and
3-vector.
|
CAtom::Transform | Transformation of atom coordinates with 4x4-matrix.
|
CAtom::isMetal | Checking if the atom is identified as a metal.
|
CAtom::PutUDData | Storing an integer User-Defined Data (UDD) in the atom.
|
CAtom::PutUDData | Storing a real-type User-Defined Data (UDD) in the atom.
|
CAtom::PutUDData | Storing a string-type User-Defined Data (UDD) in the atom.
|
CAtom::GetUDData | Retrieving an integer User-Defined Data (UDD) from the atom.
|
CAtom::GetUDData | Retrieving a real-type User-Defined Data (UDD) from the atom.
|
CAtom::GetUDData | Retrieving a string-type User-Defined Data (UDD) from the atom,
dynamic buffer.
|
CAtom::GetUDData | Retrieving a string-type User-Defined Data (UDD) from the atom,
fixed-size buffer.
|
CAtom::AddBond | Adding an atom to the list of binded atoms.
|
CAtom::GetNBonds | Getting the total number of bonds set up for the atom.
|
CAtom::FreeBonds | Removing all bonds set up for the atom.
|
CAtom::GetBonds | Getting the list of indices of bonded atoms.
|
CAtom::GetBonds | Getting the dynamically-allocated list of bonded atoms.
|
CAtom::GetBonds | Getting the dynamically-allocated list of bonded atoms.
|
CAtom::Copy | Copying the atom contents.
|
Type | Field | Ok to Modify* |
Description | ||||||||||||||||||
int | serNum | N/R | Atom's serial number as it appears in coordinate (PDB) file. Although the PDB standard requires all atoms to have unique serial numbers, increasing monotonically by one, the Library does not enforce this, unless the MMDBF_AutoSerials flag is not set prior reading the coordinate file (cf. function CMMDBManager::SetFlag. The serial numbers thus may be considered as free additional atom identifiers. | ||||||||||||||||||
int | index | N | Atom's index in the Manager's global atom table. This table may be retrieved by function CMMDBManager::GetAtomTable. | ||||||||||||||||||
AtomName | name | N/R | A PDB name of the atom, represented as null-terminated string. The name is aligned by spaces in accordance with PDB rules. | ||||||||||||||||||
AltLoc | altLoc | N/R | The alternative location indicator, represented as null-terminated string. If there is no alternative location of the atom, altLoc is set to empty string "" rather than to space. | ||||||||||||||||||
PCResidue | residue | N,R | Pointer on residue (class CResidue) containing the atom. If this pointer is NULL, it indicates a serious problem in the coordinate hierarchy, not yet a crash. | ||||||||||||||||||
realtype | x,y,z | YH | x,y,z orthogonal coordinates of the atom, in angstroms; see interpretation of WhatIsSet field. | ||||||||||||||||||
realtype | occupancy | YH | Occupancy factor of the atom; see interpretation of WhatIsSet field. | ||||||||||||||||||
realtype | tempFactor | YH | Isotropic temperature factor; see interpretation of WhatIsSet field. | ||||||||||||||||||
SegID | segID | N/R | Identifier of segment containing the atom represented as left-justified null-terimnated string. | ||||||||||||||||||
Element | element | N/R | Atom's chemical element name represented as null-terminated string. The field is aligned with spaces in accordance with PDB rules. Note that old PDB files do not contain the element name. After reading such files, element represents a double-space null-terminated string. | ||||||||||||||||||
AtCharge | charge | N/R | Charge on the atom represented as left-justified null-terminated string. | ||||||||||||||||||
realtype | sigX,sigY, sigZ |
YH | Standard deviations of the x,y,z coordinates; see interpretation of WhatIsSet field. | ||||||||||||||||||
realtype | sigOcc | YH | Standard deviation of occupancy; see interpretation of WhatIsSet field. | ||||||||||||||||||
realtype | sigTemp | YH | Standard deviation of temperature factor; see interpretation of WhatIsSet field. | ||||||||||||||||||
realtype | u11,u22, u33,u12, u13,u23 |
YH | Anisotropic temperature factors; see interpretation of WhatIsSet field. | ||||||||||||||||||
realtype | su11,su22, su33,su12, su13,su23 |
YH | Standard deviations of anisotropic temperature factors; see interpretation of WhatIsSet field. | ||||||||||||||||||
Boolean | Het | Y | An indicator that the atom belongs to a non-standard residue. When Het is set to True, the corresponding PDB record is output with keyword HETATM rather than ATOM. | ||||||||||||||||||
Boolean | Ter | N/R | An indicator that the atom class represents a chain terminator rather than a real atom. When Ter is set to True, the corresponding PDB record is output with keyword TER rather than ATOM or HETATM. Converting an atom into chain terminator is generally somewhat more than just toggling this field, therefore use function CAtom::MakeTer for this purpose. | ||||||||||||||||||
word | WhatIsSet | N/R |
A word of bit flags, indicating which fields have meaningful
values. Many fields, such as standard deviations, have an
optional character and may be missing in coordinate files.
If this is the case, the corresponding bit in
WhatIsSet is set to zero.
Correspondingly, if an application modifies a field that is
associated with one of the set flags below, that flag should
be set on in WhatIsSet. Otherwise, the
field is neglected at file output.
Table of set flags:
|
*N: | modification of the field by application may cause malfunction or crash; |
Y: | the field may be modified by application; |
R: | reading function is available; |
Y/H: | the field may be modified by application however there are conditions; |
N/R: | modification of the field is generally harmless but not recommended. |
CAtom::CAtom ( |
) |
Default constructor creates an empty CAtom object. The object is not associated with any residue or coordinate hierarchy.
NOTE : The atom should be stuffed with data (set up using the class' functions or copied from another atom) and added to a residue (unless it has a special use like temporary storage). Empty atom does not make any record in PDB output.
CAtom::CAtom ( |
PCResidue res ) |
The constructor creates an empty CAtom object and adds it to the specified residue. If the residue is associated with a coordinate hierarchy, the atom is automatically associated with it.
NOTE 1: The atom should be stuffed with data (set up using the class' functions or copied from another atom). Empty atom does not make any record in PDB output.
NOTE 2: Statement "new CAtom(NULL)" is equivalent to "new CAtom()".
CAtom::~CAtom ( |
) |
The destructor is called implicitely whenever the class instance is deleted. If the atom is properly associated with the coordinate hierarchy, the destructor removes all references on the atom from the hierarchy.
NOTE :
Deleting an atom is an editing operation. If it is done by
application explicitely, like in the following example:
PCMMDBManager MMDB;
PCAtom atom;
atom = MMDB->GetAtom ( "/1/A/33(SER).A/CA[C]" );
delete atom; // this is where the destructor is called!
then the application must call CMMDBManager::FinishStructEdit function before using
any results of such deletion(s).
int CAtom::GetModelNum ( |
) |
The function returns number of model that contains the atom. Models are numbered 1.. on. If atom is not properly associated with coordinate hierarchy, the function returns 0.
pstr CAtom::GetChainID ( |
) |
The function returns identifier of chain that contains the atom. If the chain does not have an ID, the function returns empty string "". If atom is not properly associated with coordinate hierarchy, the function returns NULL.
pstr CAtom::GetResName ( |
) |
The function returns name of residue that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.
int CAtom::GetSeqNum ( |
) |
The function returns sequence number of residue that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns ATOM_NoSeqNum.
pstr CAtom::GetInsCode ( |
) |
The function returns insertion code of residue that contains the atom. If the residue does not have insertion code, the function returns empty string "". If atom is not properly associated with coordinate hierarchy, the function returns NULL.
PCResidue CAtom::GetResidue ( |
) |
The function returns pointer on residue that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.
PCChain CAtom::GetChain ( |
) |
The function returns pointer on chain that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.
PCModel CAtom::GetModel ( |
) |
The function returns pointer on model that contains the atom. If atom is not properly associated with coordinate hierarchy, the function returns NULL.
Boolean CAtom::isInSelection ( |
int selHnd ) |
The function returns True if atom is selected for the specified selection handle, and False otherwise.
NOTE : The function returns False if atom is not properly associated with coordinate hierarchy.
pstr CAtom::SetAtomName ( |
AtomName atomName ) |
This function assigns a new name to the atom, i.e. renames it.
NOTE : The function does not align atom names. It is responsibility of application to check that the new atom name complies with PDB standard.
pstr CAtom::SetElementName ( |
Element elName ) |
This function assigns a new chemical element name to the atom, i.e. renames its chemical name.
NOTE : The function does align the chemical element name to the right of 2-character field, if necessary. The function however does not check validity of the new name.
void CAtom::MakeTer ( |
) |
The function converts atom into chain terminator. Using this function is the only proper way of setting a terminator in the end of chain. An application should simply add an atom to chain and then convert it to chain terminator.
void CAtom::SetCoordinates ( |
realtype xx, |
The function writes the values of x,y,z coordinates, occupancy and temperature factors into the corresponding class' fields, and set up the relevant bits in WhatIsSet word.
pstr CAtom::GetAtomID ( |
pstr AtomID ) |
The function calculates a full coordinate ID of the atom and returns it in the supplied string. The same string is returned as the function value.
If atom is not properly associated with coordinate hierarchy, the coordinate ID will contain dashes "-" for those elements that could not be identified.NOTE : The function does not make any checks on the sufficiency of string buffer AtomID to accept the information. A value of 100 characters for the buffer length is recommended.
pstr CAtom::GetAtomIDfmt ( |
pstr AtomID ) |
The function is similar to CAtom::GetAtomID, but it produces CIDs aligned with spaces such that they look uniformly when output tablewise.
The alignment is reached by giving all necessary space for the model number (depends on the total number of models present in the coordinate hierarchy, not less than 3 symbols for the sequence number and exactly 1, 3, 1, 4, 2 and 1 symbols for the chain ID, residue name, insertion code, atom name, chemical element name and alternative location indicator, respectively. If atom is not properly associated with coordinate hierarchy, the coordinate ID will contain dashes "-" for those elements that could not be identified. The number of dashes is chosen such that to suite the alignment criteria.NOTE : The function does not make any checks on the sufficiency of string buffer AtomID to accept the information. A value of 100 characters for the buffer length is recommended.
int CAtom::CheckID ( |
AtomName aname, |
The function returns 1 if the atom is identified by given atom name, chemical element and alternative location indicator, and 0 otherwise.
The atom is considered as identified, if all non-NULL, non-wildcard parameters do match. If all parameters are set NULL or wildcard, any atom is identified. Default values for elname and aloc correspond to 'any element' and 'no alternative location indicator'.NOTE 1: The model serial number, chain ID, residue sequence number and insertion code are not taken into account by this function.
NOTE 2: Comparison is case-sensitive. Consider that " " is not an empty string.
int CAtom::CheckIDS ( |
pstr CID ) |
The function returns 1 if the atom is identified by atom name, chemical element and alternative location indicator found in the provided coordinate ID, and 0 otherwise.
The atom is considered as identified, if all identifying items in the provided coordinate ID do match those of atom. If all coordinate ID items are set to wildcards "*", any atom is identified.NOTE 1: The model serial number, chain ID, residue sequence number and insertion code are not taken into account by this function.
NOTE 2: Comparison is case-sensitive. Any spaces in the coordinate ID are ignored.
NOTE 3: This function allows for coordinate ID containing only atom name, e.g. "CA", without accompanying square brackets or colon, as is generally required by the coordinate ID syntax.
void CAtom::Transform ( |
mat33 & m, |
The function performs the following transformation of
atom's x,y,z coordinates:
x := m[0][0]*x + m[0][1]*y + m[0][2]*z + v[0]
y := m[1][0]*x + m[1][1]*y + m[1][2]*z + v[1]
z := m[2][0]*x + m[2][1]*y + m[2][2]*z + v[2]
void CAtom::Transform ( |
mat44 & m ) |
The function performs the following transformation of
atom's x,y,z coordinates:
x := m[0][0]*x + m[0][1]*y + m[0][2]*z + m[0][3]
y := m[1][0]*x + m[1][1]*y + m[1][2]*z + m[1][3]
z := m[2][0]*x + m[2][1]*y + m[2][2]*z + m[2][3]
Boolean CAtom::isMetal ( |
) |
The function returns True if the atom is identified as a metal.
int CAtom::PutUDData ( |
int UDDhandle, |
The function stores an integer contained in iudd in the atom, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDInteger in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully stored |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the atom, the data was not stored |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in atoms, the data was not stored |
int CAtom::PutUDData ( |
int UDDhandle, |
The function stores the real number contained in rudd in the atom, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDReal in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The function is conceptually identical to CAtom::PutUDData, see returns there.int CAtom::PutUDData ( |
int UDDhandle, |
The function stores the string pointed by sudd in the atom, associating it with UDD handle UDDhandle. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The function is conceptually identical to CAtom::PutUDData, see returns there.int CAtom::GetUDData ( |
int UDDhandle, |
The function retrieves an integer previously stored in the atom by function CAtom::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDInteger in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The data is returned in iudd.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the atom. iudd returns zero. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the atom. iudd returns zero. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in atoms. iudd does not change. |
int CAtom::GetUDData ( |
int UDDhandle, |
The function retrieves a real number previously stored in the atom by function CAtom::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDReal in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The data is returned in rudd.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the atom. rudd returns zero. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the atom. rudd returns zero. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in atoms. rudd does not change. |
int CAtom::GetUDData ( |
int UDDhandle, |
The function retrieves a string previously stored in the atom by function CAtom::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The string is returned in buffer pointed by sudd. If sudd was not set to NULL, it will be deallocated first. The string is allocated within the function, and it is responsibility of the application to eventually deallocate it.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the atom. sudd returns NULL. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the atom. sudd returns NULL. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in atoms. sudd does not change. |
int CAtom::GetUDData ( |
int UDDhandle, |
The function retrieves a string previously stored in the atom by function CAtom::PutUDData. The UDD handle UDDhandle identifies the data. The handle must be previously obtained from CMMDBManager::RegisterUDString in the course of UDD registration or from CMMDBManager::GetUDDHandle after the registration has been done.
The string is returned in buffer pointed by sudd, with no more than maxlen symbols, including the terminating NULL returned. The string sudd is not allocated or deallocated within the function.The function may return:
Return | Description |
UDDATA_Ok | the data has been successfully retrieved. |
UDDATA_NoData | no data found for the handle UDDhandle in the atom. sudd returns empty string "". |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the atom. sudd returns empty string "". |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in atoms. sudd does not change. |
int CAtom::AddBond ( |
PCAtom bond_atom, |
The function adds pointer on the bond_atom and bond order characteristics bond_order to the atom's list of bonds.
The function returns a positive (>0) number of total bonds for the atom in the case of successful completion. A zero or negative return means that the atom has already been added into the list of bonds and if found there at position -return.
NOTE : Setting bond_atom bonded to "this" atom does not imply that "this" atom is automatically bonded to bond_atom. The application should take care of setting symmetrical bonds if necessary.
int CAtom::GetNBonds ( |
) |
The function returns the total number of bonds set up for the atom by function CAtom::AddBond.
void CAtom::FreeBonds ( |
) |
The function removes all bonds set up for the atom by function CAtom::AddBond.
void CAtom::GetBonds ( |
RPSAtomBondI AtomBondI, |
The function returns the list of indices of bonded atoms.
Each item is represented by SAtomBondI
structure:
struct SAtomBondI {
int index; // bonded atom index
byte order; // bond order
}
where index is the absolute position of
atom in coordinate hierarchy
plus one. In an ideal PDB file, index is
equal to the atom's serial number, however in MMDB these
generally do not coincide.
NOTE : The application must not attempt to deallocate or alterate AtomBondI obtained from this function. Violation of this will eventually cause a crash.
void CAtom::GetBonds ( |
RPSAtomBond AtomBond, |
The function returns the list of bonded atoms.
Each item is represented by SAtomBond
structure:
struct SAtomBond {
PCAtom atom; // bonded atom pointer
byte order; // bond order
}
If AtomBond was not set to NULL
before calling this function, the latter will first try to
deallocate it. The list of atoms is then allocated in memory,
and filled up with atom pointers retrieved from
coordinate hierarchy.
NOTE : It is responsibility of the application to deallocate AtomBond obtained from this function.
void CAtom::GetBonds ( |
PSAtomBond AtomBond, |
The function returns the list of bonded atoms (no more than
maxlength first items) in the vector
AtomBond allocated by the application.
The structure SAtomBond is defined as
follows:
struct SAtomBond {
PCAtom atom; // bonded atom pointer
byte order; // bond order
}
NOTE : It is responsibility of the application to allocate and deallocate vector AtomBond.
void CAtom::Copy ( |
PCAtom atom ) |
The function copies the content of atom atom into internal class' fields. The function does not copy the residue pointer. As a result, a new atom is created that is identical to the source one, but physically they do not overlap.
NOTE :
An application should never copy contents of classes by direct
assignment; in most cases this will result in crash because
of inducing a mess in cross-references. See the following example:
PCAtom a1,a2;
a1 = new CAtom();
a2 = new CAtom();
a2->SetCoordinates ( 1.0,2.0,3.0,1.0,1.0 );
*a1 = *a2; // never do this!
// the right way:
a1->Copy ( a2 );
Function Copy is supplied for all classes
in the Library.