Data class CResidue represents a residue in the coordinate hierarchy.
CResidue contains all information, which is relevant to particular residue, and reference to chain that contains the residue. It also contains table of pointers on all atoms (represented as classes of type CAtom) that belong to the residue.Public Data Fields | |
Function | Purpose |
CResidue::CResidue | Default constructor.
|
CResidue::~CResidue | The class' destructor.
|
CResidue::GetModelNum | Obtaining number of model containing the residue.
|
CResidue::GetChainID | Obtaining identifier of chain containing the residue.
|
CResidue::GetResName | Obtaining the residue name.
|
CResidue::SetResName | Setting the residue name.
|
CResidue::GetSeqNum | Obtaining the residue sequence number.
|
CResidue::GetInsCode | Obtaining the residue insertion code.
|
CResidue::GetChain | Obtaining pointer on chain containing the residue.
|
CResidue::GetModel | Obtaining pointer on model containing the residue.
|
CResidue::isInSelection | Checking if residue is selected.
|
CResidue::GetResidueID | Obtaining a full residue's coordinate ID.
|
CResidue::CheckID | Checking the residue's ID by sequence number, insertion code
and residue name.
|
CResidue::CheckIDS | Checking the residue's ID by coordinate ID.
|
CResidue::GetNumberOfAtoms | Calculating the number of atoms in the residue.
|
CResidue::GetNumberOfAtoms | Obtaining the number of atoms in residue.
|
CResidue::GetAtom | Obtaining an atom pointer by atom name, element name,
and alternative location indicator.
|
CResidue::GetAtom | Obtaining an atom pointer by atom number.
|
CResidue::GetAtomTable | Obtaining the residue's table of atoms.
|
CResidue::DeleteAtom | Deleting an atom by atom name, element name,
and alternative location indicator.
|
CResidue::DeleteAtom | Deleting an atom by atom number.
|
CResidue::DeleteAllAtoms | Deleting all atoms in the residue.
|
CResidue::AddAtom | Adding an atom to the residue.
|
CResidue::GetAtomStatistics | Calculating the averaged properties of atoms in the residue.
|
CResidue::ApplyTransform | Applying a transformation matrix to coordinates of
all atoms in the residue.
|
CResidue::isAminoacid | Checking if the residue represents an aminoacid.
|
CResidue::isNucleotide | Checking if the residue represents a nucleotide.
|
CResidue::isSugar | Checking if the residue represents a sugar molecule.
|
CResidue::isSolvent | Checking if the residue represents a solvent molecules.
|
CResidue::isModRes | Checking if the residue represents a modified standard residue.
|
CResidue::PutUDData | Storing an integer User-Defined Data (UDD) in the residue.
|
CResidue::PutUDData | Storing a real-type User-Defined Data (UDD) in the residue.
|
CResidue::PutUDData | Storing a string-type User-Defined Data (UDD) in the residue.
|
CResidue::GetUDData | Retrieving an integer User-Defined Data (UDD) from the residue.
|
CResidue::GetUDData | Retrieving a real-type User-Defined Data (UDD) from the residue.
|
CResidue::GetUDData | Retrieving a string-type User-Defined Data (UDD) from the residue,
dynamic buffer.
|
CResidue::GetUDData | Retrieving a string-type User-Defined Data (UDD) from the residue,
fixed-size buffer.
|
CResidue::Copy | Copying the residue contents.
|
Type | Field | Ok to Modify* |
Description |
ResName | name | N/R,R | The residue's (3-letter) name, represented as a null-terminated string. The field is left-aligned, all spaces are cut. |
int | seqNum | N/R,R | The residue's sequence number. |
InsCode | insCode | N/R,R | The residue's insertion code, represented as a null-terminated string. The field is left-aligned, all spaces are cut. For a residue without insertion code, insCode is set to empty string "". |
PCChain | chain | N | Pointer on chain (class CChain) containing the residue. If this pointer is NULL, it indicates a serious problem in the coordinate hierarchy, not yet a crash. |
int | index | N | Index (position) of the residue in the parential chain's table of residues. The index ranges as 0.. on. |
*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. |
CResidue::CResidue ( |
) |
Default constructor creates an empty CResidue object.
CResidue::~CResidue ( |
) |
The destructor is called implicitely whenever the class instance is deleted. It deletes all atoms containing in the residue and the residue itself. If the residue is properly associated with the coordinate hierarchy, the destructor removes all references on the residue and its atoms from the hierarchy.
NOTE :
Deleting a residue is an editing operation. If it is done by
application explicitely, like in the following example:
PCMMDBManager MMDB;
PCResidue res;
res = MMDB->GetResidue ( "/1/A/33(SER).A" );
delete res; // this is where the destructor is called!
then the application must call CMMDBManager::FinishStructEdit function before using
any results of such deletion(s).
int CResidue::GetModelNum ( |
) |
The function returns number of model that contains the residue. Models are numbered 1.. on. If residue is not properly associated with coordinate hierarchy, the function returns 0.
pstr CResidue::GetChainID ( |
) |
The function returns identifier of chain that contains the residue. If the chain does not have an ID, the function returns empty string "". If residue is not properly associated with coordinate hierarchy, the function returns NULL.
pstr CResidue::GetResName ( |
) |
The function returns the residue name.
pstr CResidue::SetResName ( |
ResName resName ) |
The function sets new residue name, i.e. renames the residue.
int CResidue::GetSeqNum ( |
) |
The function returns the residue sequence number.
pstr CResidue::GetInsCode ( |
) |
The function returns the residue insertion code. If the residue does not have insertion code, the function returns empty string "".
PCChain CResidue::GetChain ( |
) |
The function returns pointer on chain that contains the residue. If residue is not properly associated with coordinate hierarchy, the function returns NULL.
PCModel CResidue::GetModel ( |
) |
The function returns pointer on model that contains the residue. If residue is not properly associated with coordinate hierarchy, the function returns NULL.
Boolean CResidue::isInSelection ( |
int selHnd ) |
The function returns True if residue is selected for the specified selection handle, and False otherwise.
NOTE : The function returns False if residue is not properly associated with coordinate hierarchy.
pstr CResidue::GetResidueID ( |
pstr ResidueID ) |
The function calculates a coordinate ID of the residue and returns it in the supplied string. The same string is returned as the function value.
If residue 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 ResidueID to accept the information.
int CResidue::CheckID ( |
int * sNum, |
The function returns 1 if the residue is identified by given sequence number, insertion code and residue name, and 0 otherwise.
The residue is considered as identified, if all non-NULL, non-wildcard parameters do match. If all parameters are set NULL or wildcard, any residue is identified. Default values for inscode and resname correspond to 'no insertion code' and 'any residue name'.NOTE 1: The model serial number and chain ID are not taken into account by this function.
NOTE 2: Comparison is case-sensitive. Consider that " " is not an empty string.
int CResidue::CheckIDS ( |
pstr CID ) |
The function returns 1 if the residue is identified by residue sequence number, insertion code ans residue name found in the provided coordinate ID, and 0 otherwise.
The residue is considered as identified, if all identifying items in the provided coordinate ID do match those of residue. If all coordinate ID items are set to wildcards "*", any residue is identified.NOTE 1: The model serial number and chain ID, as well as any atom-related information in the coordinate ID are not taken into account by this function.
NOTE 2: Comparison is case-sensitive. Any spaces in the coordinate ID are ignored.
int CResidue::GetNumberOfAtoms ( |
Boolean countTers ) |
The function performs an actual calculation of all atoms in the residue, not just returning the length of atom tables. If some cells in the atom table are empty (set to NULL), they are not counted.
int CResidue::GetNumberOfAtoms ( |
) |
The function returns the number of atoms currently contained in the residue.
NOTE : The function actually returns the length of atom table of the residue. In the course of editing operations, the table may contain empty cells, which will be counted as atoms. Besides, a residue may contain a termination record ("TER"), which is kept in MMDB as a special case of CAtom object; the function will count such an object as atom.
PCAtom CResidue::GetAtom ( |
AtomName aname, |
The function returns pointer on the atom identified by its name, chemical element name and alternative location indicator. If any of these characteristics is invalid or if such an atom does not exist in residue, the function returns NULL.
The atom is considered as identified, if all non-NULL, non-wildcard parameters do match. If the specified parameters allow for identification of more than one atom in the residue, the first one from the begining of the residue's table of atoms is taken. Thus, if all parameters are set NULL or wildcard, pointer on the very first atom in the residue's table of atoms is returned. Default values for elname and aloc correspond to 'any element' and 'no alternative location indicator'.NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.
PCAtom CResidue::GetAtom ( |
int atomNo ) |
The function returns pointer on the atomNoth atom in the residue's table of atoms. If atomNo is invalid or if such an atom does not exist in residue, the function returns NULL.
void CResidue::GetAtomTable ( |
PPCAtom & atomTable, |
The function returns table of pointers on all atoms currently contained in the residue. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.
If there is no atoms in the residue, the function returns NULL for atomTable and 0 for NumberOfAtoms.NOTE 1: Certain editing operations might dispose atoms. This results in empty cells in the table of atoms. Therefore, it is a good practice for application to check that atomTable[i] is not NULL before using it.
NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the table of atoms.
int CResidue::DeleteAtom ( |
AtomName aname, |
The function deletes all atoms in the residue that answer to the provided atom name, chemical element name and alternative location indicator. An atom is considered as answering the conditions if all non-NULL, non-wildcard parameters do match. Thus, if all parameters are set NULL or wildcard, all atoms in the residue are deleted. Default values for elname and aloc correspond to 'any element' and 'no alternative location indicator'.
The function returns the number of deleted atoms.
NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.
NOTE 2: Deleted atoms are completely disposed and are not retrievable.
NOTE 3: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.
int CResidue::DeleteAtom ( |
int atomNo ) |
The function deletes the atomNoth atom as found in the residue's table of atoms. If atomNo is invalid or if such an atom does not exist in residue, the function does nothing.
The function returns the number of deleted atoms, that is 1 or 0.
NOTE 1: Deleted atoms are completely disposed and are not retrievable.
NOTE 2: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.
int CResidue::DeleteAllAtoms ( |
) |
The function deletes all atoms in the residue, leaving the residue empty.
The function returns the number of actually deleted atoms.
NOTE 1: Deleted atoms are completely disposed and are not retrievable.
NOTE 2: The application must call CMMDBManager::FinishStructEdit function after a set of editing operations is complete, before using the results of the editing.
NOTE 3: The function does not dispose the residue; neither does it delete it from a chain.
int CResidue::AddAtom ( |
PCAtom atom ) |
The function adds atom atom to the residue, placing it on the top of the residue's table of atoms. The atom and the residue may be or may be not associated with a coordinate hierarchy.
If atom atom is not associated with a coordinate hierarchy, it is taken over by the residue, which means that its pointer is saved in the residue's table of atoms. If atom atom already belongs to a coordinate hierarchy (even though that of the residue), the residue adopts its (automatically created) copy, thus the atom is not removed from its own coordinate hierarchy. If residue is associated with a coordinate hierarchy, the newly added atom is automatically associated with it. Otherwise, the atom is checked in the hierarchy once the residue is checked in (see example below).Upon success, the function returns the number of atoms in the residue, which should be a positive integer greater than 0. A negative or zero return means that the atom is already in the residue, found at position equal to minus return.
NOTE 1: Note the difference between adding atoms associated and not associated with a coordinate hierarchy as described above.
NOTE 2: Calling CMMDBManager::FinishStructEdit function is not necessary after adding atoms. However, it is advisable to call CMMDBManager::PDBCleanup with input flags PDBCLEAN_SERIAL and PDBCLEAN_INDEX after adding all atoms (don't call CMMDBManager::PDBCleanup after every addition of an atom). PDBCLEAN_SERIAL will put atoms' serial numbers in due order, and "cleaning" on PDBCLEAN_INDEX is needed for the internal consistency of data.
Create a chain containing one residue having a few atoms,
and add it to model 1 of a coordinate hierarchy:
CMMDBManager MMDB;
PCModel model;
PCChain chain;
PCResidue res;
PCAtom atom;
int RC;
// ... read data into MMDB
RC = MMDB.ReadCoorFile ( filename );
// ... check for errors -- see details for
// CMMDBManager::ReadCoorFile(..)
if (RC) {
printf ( " errors.\n" );
exit(0);
}
// ... create a new residue
res = new CResidue(); // the residue IS NOT associated
// with MMDB
// ... stuff it with atoms now:
atom = new CAtom(); // the atom IS NOT associated with
// a residue or MMDB
// ... set atom characteristics:
atom->SetAtomName ( " CA " ); // it has to be a PDB name!
atom->SetElementName ( "C" );
atom->SetCoordinates ( x,y,z,occupancy,tFactor );
// ... add atom to the residue:
RC = res->AddAtom ( atom );
if (RC<=0) {
// this may happen only if you try to add the same atom twice.
printf ( " error adding atom.\n" );
exit(0);
}
// ... a slightly different way of doing the same:
atom = new CAtom ( res ); // the atom IS ALREADY associated with
// and added to the residue, but it
// IS NOT associated with MMDB
// NOTE: this way assures that the atom
// is added to the residue, because
// it was freshly allocated -- no other
// atom with the same pointer may exist.
// ... we still need to set the atom's characteristics:
atom->SetAtomName ( " CB " ); // it has to be a PDB name!
atom->SetElementName ( "C" );
atom->SetCoordinates ( x,y,z,occupancy,tFactor );
// ... add other atoms as necessary ...
// ... create a new chain
chain = new CChain(); // the chain IS NOT associated with MMDB
chain->SetChainID ( "X" ); // new chain ID
// ... and add residue to it
chain->AddResidue ( res );
// ... now add the chain to the model 1 of MMDB:
model = MMDB.GetModel ( 1 );
if (!model) {
// MMDB was empty. We have to create a new model:
model = new CModel();
MMDB.AddModel ( model ); // add empty model on the top of MMDB
}
model->AddChain ( chain ); // at this point, the chain is associated with
// and added to MMDB, all its residues and
// atoms get associated automatically
// The following call is more of a "gentleman" nature now,
// but it may be an absolute must for compliency with later
// versions of MMDB. You are strongly advised to call at least
// PDBCleanup(PDBCLEAN_INDEX) after adding or inserting
// atoms/residues/chains/models into MMDB. However don't make
// this call after every insertion/addition for the sake of
// computational efficiency. Do this call once as you finished
// building the structure and are going to proceed further.
MMDB.PDBCleanup ( PDBCLEAN_SERIAL | PDBCLEAN_INDEX );
void CResidue::GetAtomStatistics ( |
RSAtomStat AS ) |
Type | Field(s) | Description | |
int | nAtoms | Number of averaged atoms | |
realtype | xmin,ymin,zmin | Minimum X,Y,Z-coordinates | |
realtype | xmax,ymax,zmax | Maximum X,Y,Z-coordinates | |
realtype | xm,ym,zm | Average X,Y,Z-coordinates | |
realtype | xm2,ym2,zm2 | Square average X,Y,Z-coordinates | |
realtype | occ_min,occ_max | Minimum and maximum occupancies | |
realtype | occ_m,occ_m2 | Average and square average occupancies | |
realtype | tFmin,tFmax | Minimum and maximum isotropic temperature factors | |
realtype | tFm,tFm2 | Average and square average isotropic temperature factors | |
realtype | u11_min,u22_min, u33_min,u12_min, u13_min,u23_min |
Minimum anisotropic temperature factors | |
realtype | u11_max,u22_max, u33_max,u12_max, u13_max,u23_max |
Maximum anisotropic temperature factors | |
realtype | u11_m,u22_m, u33_m,u12_m, u13_m,u23_m |
Average anisotropic temperature factors | |
realtype | u11_m2,u22_m2, u33_m2,u12_m2, u13_m2,u23_m2 |
Square average anisotropic temperature factors | |
word | WhatIsSet | A word of bit flags, indicating which from the above fields have meaningful values. This field is identical to the WhatIsSet field of CAtom class. If any atom from the average does not have a particular attribute, the corresponding bit in WhatIsSet will be cleared and the averages for that attribute are not calculated. |
The function performs an actual calculation of averaged atom properties, none of them are stored as variables. It is therefore advised to avoid unnecessary calls to this function.
void CResidue::ApplyTransform ( |
mat44 & TMatrix ) |
The function applies the rotational-translational transformation given by matrix TMatrix, to coordinates of all atoms in the residue.
The transformation matrix TMatrix contains rotational part in columns 0,1,2, rows 0,1,2 (stands for x,y,z) and translational part in column 3, rows 0,1,2.Boolean CResidue::isAminoacid ( |
) |
The function returns True if the residue represents an aminoacid.
Boolean CResidue::isNucleotide ( |
) |
The function returns True if the residue represents a nucleotide.
Boolean CResidue::isSugar ( |
) |
The function returns True if the residue represents a sugar molecule.
Boolean CResidue::isSolvent ( |
) |
The function returns True if the residue represents a solvent molecule.
Boolean CResidue::isModRes ( |
) |
The function returns True if the residue represents a modified standard residue.
int CResidue::PutUDData ( |
int UDDhandle, |
The function stores an integer contained in iudd in the residue, 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 residue, the data was not stored |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in residues, the data was not stored |
int CResidue::PutUDData ( |
int UDDhandle, |
The function stores the real number contained in rudd in the residue, 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 CResidue::PutUDData, see returns there.int CResidue::PutUDData ( |
int UDDhandle, |
The function stores the string pointed by sudd in the residue, 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 CResidue::PutUDData, see returns there.int CResidue::GetUDData ( |
int UDDhandle, |
The function retrieves an integer previously stored in the residue by function CResidue::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 residue. iudd returns zero. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the residue. iudd returns zero. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in residues. iudd does not change. |
int CResidue::GetUDData ( |
int UDDhandle, |
The function retrieves a real number previously stored in the residue by function CResidue::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 residue. rudd returns zero. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the residue. rudd returns zero. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in residues. rudd does not change. |
int CResidue::GetUDData ( |
int UDDhandle, |
The function retrieves a string previously stored in the residue by function CResidue::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 residue. sudd returns NULL. |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the residue. sudd returns NULL. |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in residues. sudd does not change. |
int CResidue::GetUDData ( |
int UDDhandle, |
The function retrieves a string previously stored in the residue by function CResidue::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 residue. sudd returns empty string "". |
UDDATA_WrongHandle | the UDD handle UDDhandle does not correspond to any registered UDD for the residue. sudd returns empty string "". |
UDDATA_WrongUDRType | the UDD handle UDDhandle was not registered for use in residues. sudd does not change. |
void CResidue::Copy ( |
PCResidue residue ) |
The function copies the content of residue residue into internal class' fields. The function does copy all the table of residue's atoms and it does redefine the atoms' residue for the destination one. As a result, a new residue 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:
PCResidue res1,res2;
res1 = new CResidue();
res2 = new CResidue();
// doing something with res2
*res1 = *res2; // never do this!
// the right way:
res1->Copy ( res2 );
Function Copy is supplied for all classes
in the Library.