CCP4 Coordinate Library Project

Object interface: Data class CChain.

Data class CChain represents a chain in the coordinate hierarchy.

CChain contains all information, which is relevant to particular chain, and reference to model that contains the chain. It also contains table of pointers on all residues (represented as classes of type CResidue) that belong to the chain.

Function Purpose
CChain::CChain Default constructor.
CChain::~CChain The class' destructor.
CChain::GetModelNum Obtaining number of model containing the chain.
CChain::GetModel Obtaining pointer on model containing the chain.
CChain::isInSelection Checking if chain is selected.
CChain::GetChainID Obtaining identifier of the chain.
CChain::SetChainID Setting the chain identifier.
CChain::GetChainID Obtaining a full chain's coordinate ID.
CChain::CheckID Checking the chain's ID by chainID.
CChain::CheckIDS Checking the chain's ID by coordinate ID.
CChain::GetNumberOfResidues Obtaining the number of residues in chain.
CChain::GetResidue Obtaining a residue pointer by residue sequence number and insertion code.
CChain::GetResidue Obtaining a residue pointer by residue number.
CChain::GetResidueNo Obtaining a residue position in the chain by residue sequence number and insertion code.
CChain::GetResidueTable Obtaining the chain's table of residues.
CChain::DeleteResidue Deleting a residue by residue sequence number and insertion code.
CChain::DeleteResidue Deleting a residue by residue number.
CChain::GetNumberOfAtoms Calculating the total number of atoms in the chain.
CChain::GetNumberOfAtoms Obtaining the number of atoms in residue by residue sequence number and insertion code.
CChain::GetNumberOfAtoms Obtaining the number of atoms in residue by residue number.
CChain::GetAtom Obtaining an atom pointer by residue sequence number, insertion code, atom name, element name, and alternative location indicator.
CChain::GetAtom Obtaining an atom pointer by residue sequence number, residue insertion code and atom number.
CChain::GetAtom Obtaining an atom pointer by residue number, atom name, element name and alternative location indicator.
CChain::GetAtom Obtaining an atom pointer by residue number and atom number.
CChain::GetAtomTable Obtaining the residue's table of atoms by residue sequence number and insertion code.
CChain::GetAtomTable Obtaining the residue's table of atoms by residue number.
CChain::DeleteAtom Deleting an atom specified by residue sequence number, insertion code, atom name, element name, and alternative location indicator.
CChain::DeleteAtom Deleting an atom specified by residue sequence number, residue insertion code and atom number.
CChain::DeleteAtom Deleting an atom specified by residue number, atom name, element name and alternative location indicator.
CChain::DeleteAtom Deleting an atom specified by residue number and atom number.
CChain::DeleteAllAtoms Deleting all atoms in the residue specified by sequence number and insertion code.
CChain::DeleteAllAtoms Deleting all atoms in the residue specified by its position in the chain.
CChain::DeleteAllAtoms Deleting all atoms in the chain.
CChain::AddAtom Adding an atom to the residue specified by sequence number and insertion code.
CChain::AddAtom Adding an atom to the residue specified by its position in the chain.
CChain::SetEntryID Setting the entry ID.
CChain::GetEntryID Obtaining the entry ID.
CChain::GetAtomStatistics Calculating the averaged properties of all atoms in the chain.
CChain::GetNofModResidues Obtaining the number of modified residues annotated in the chain.
CChain::GetModResidues Obtaining the information on modified residue.
CChain::ApplyTransform Applying a transformation matrix to coordinates of all atoms in the chain.
CChain::isSolventChain Checking if the chain consists only of solvent molecules.
CChain::PutUDData Storing an integer User-Defined Data (UDD) in the chain.
CChain::PutUDData Storing a real-type User-Defined Data (UDD) in the chain.
CChain::PutUDData Storing a string-type User-Defined Data (UDD) in the chain.
CChain::GetUDData Retrieving an integer User-Defined Data (UDD) from the chain.
CChain::GetUDData Retrieving a real-type User-Defined Data (UDD) from the chain.
CChain::GetUDData Retrieving a string-type User-Defined Data (UDD) from the chain, dynamic buffer.
CChain::GetUDData Retrieving a string-type User-Defined Data (UDD) from the chain, fixed-size buffer.
CChain::Copy Copying the chain contents.


 CChain::CChain ( 
 )
PURPOSE
Default constructor.
DESCRIPTION

Default constructor creates an empty CChain object.


 CChain::~CChain ( 
 )
PURPOSE
The class' destructor.
DESCRIPTION

The destructor is called implicitely whenever the class instance is deleted. It deletes all atoms and residues containing in the chain and the chain itself. If the chain is properly associated with the coordinate hierarchy, the destructor removes all references on the chain, its residues and atoms, from the hierarchy.

NOTE : Deleting a chain is an editing operation. If it is done by application explicitely, like in the following example:

    PCMMDBManager MMDB;
    PCChain       chain;
      chain = MMDB->GetChain ( "/1/A" );
      delete chain;  // this is where the destructor is called!
    
then the application must call CMMDBManager::FinishStructEdit function before using any results of such deletion(s).

If the deletion is done implicitely by a Library function in the course of other action(s), there is no need for application to call CMMDBManager::FinishStructEdit after that.


int CChain::GetModelNum ( 
 )
PURPOSE
Obtaining number of model containing the chain.
DESCRIPTION

The function returns number of model that contains the chain. Models are numbered 1.. on. If chain is not properly associated with coordinate hierarchy, the function returns 0.


PCModel CChain::GetModel ( 
 )
PURPOSE
Obtaining pointer on model containing the chain.
DESCRIPTION

The function returns pointer on model that contains the chain. If chain is not properly associated with coordinate hierarchy, the function returns NULL.


Boolean CChain::isInSelection ( 
int  selHnd )
PURPOSE
Checking if chain is selected.
ARGUMENTS
int selHnd
Selection handle.

DESCRIPTION

The function returns True if chain is selected for the specified selection handle, and False otherwise.

NOTE : The function returns False if chain is not properly associated with coordinate hierarchy.


pstr CChain::GetChainID ( 
 )
PURPOSE
Obtaining identifier of the chain.
DESCRIPTION

The function returns identifier of the chain. If the chain does not have an ID, the function returns empty string "".


void CChain::SetChainID ( 
ChainID  chainID )
PURPOSE
Setting the chain identifier.
ARGUMENTS
ChainID chainID
New chain ID.

DESCRIPTION

The function sets a new chain ID, i.e. renames the chain. Other parts of the coordinate file, such as PDB records DBREF, SEQRES and others, are updated automatically.


pstr CChain::GetChainID ( 
pstr  CID )
PURPOSE
Obtaining a full chain's coordinate ID.
ARGUMENTS
pstr CID
A string to accept the chain's coordinate ID.

DESCRIPTION

The function calculates a coordinate ID of the chain and returns it in the supplied string. The same string is returned as the function value.

If chain is not properly associated with coordinate hierarchy, the coordinate ID will contain dash "-" for model number.

NOTE : The function does not make any checks on the sufficiency of string buffer CID to accept the information.


int CChain::CheckID ( 
ChainID  chID )
PURPOSE
Checking the chain's ID by chainID.
ARGUMENTS
ChainID chID
The chain ID, represented as a null-terminated string without spaces. For unnamed chains, chID should be set to empty string "". chID may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function returns 1 if the chain is identified by given chain ID, and 0 otherwise. If chID is set to NULL or wildcard "*" then any chain is identified.

NOTE 1: The model serial number is not taken into account by this function.

NOTE 2: Comparison is case-sensitive. Consider that " " is not an empty string.


int CChain::CheckIDS ( 
pstr  CID )
PURPOSE
Checking the chain's ID by coordinate ID.
ARGUMENTS
pstr CID
The chain's coordinate ID. Only the part of coordinate ID containing the chain ID is taken into consideration.

DESCRIPTION

The function returns 1 if the chain is identified by chain ID found in the provided coordinate ID, and 0 otherwise. If CID contains a wildcard for chain ID, any chain is identified.

NOTE 1: The model serial number, as well as any residue and 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 CChain::GetNumberOfResidues ( 
 )
PURPOSE
Obtaining the number of residues in chain.
DESCRIPTION

The function returns the number of residues currently contained in the chain.


PCResidue CChain::GetResidue ( 
int  seqNum, 
InsCode insCode )
PURPOSE
Obtaining a residue pointer by residue sequence number and insertion code.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code represented as a null-terminated string without spaces. If a residues does not have insertion code, an empty string "" should be supplied.

DESCRIPTION

The function returns pointer on the residue identified by residue sequence number and insertion code. If any of these characteristics is invalid or if such a residue does not exist in chain, the function returns NULL.

NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.


PCResidue CChain::GetResidue ( 
int  resNo )
PURPOSE
Obtaining a residue pointer by residue number.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residues in the table are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CChain::GetNumberOfResidues.

DESCRIPTION

The function returns pointer on the resNoth residue in the chain's table of residues. If resNo is invalid or if such a residue does not exist in the chain, the function returns NULL.


int CChain::GetResidueNo ( 
int  seqNum, 
InsCode insCode )
PURPOSE
Obtaining a residue position in the chain by residue sequence number and insertion code.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code represented as a null-terminated string without spaces. If a residues does not have insertion code, an empty string "" should be supplied.

DESCRIPTION

The function returns the residue position (residue number) in the chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CChain::GetNumberOfResidues.

The residue is identified by residue sequence number and insertion code. If any of these characteristics is invalid or if such a residue does not exist in chain, the function returns -1.

NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.


void CChain::GetResidueTable ( 
PPCResidue &  resTable, 
int & NumberOfResidues )
PURPOSE
Obtaining the chain's table of residues.
ARGUMENTS
PPCResidue & resTable
The table of residues.

int & NumberOfResidues
The number of residues.

DESCRIPTION

The function returns table of pointers on all residues currently contained in the chain. NumberOfResidues returns the number of residues. The residues are indexed as 0..NumberOfResidues-1 in the table.

If there is no residues in the chain, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might dispose residues. This results in empty cells in the table of residues. Therefore, it is a good practice for application to check that resTable[i] is not NULL before using it.

NOTE 2: Under no circumstances should the application deallocate, reallocate or otherwise modify the table of residues.


int CChain::DeleteResidue ( 
int  seqNum, 
InsCode insCode )
PURPOSE
Deleting a residue by residue sequence number and insertion code.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code represenyted as null-terminated string without spaces. If a residues does not have insertion code, an empty string "" should be supplied.

DESCRIPTION

The function deletes residue identified by residue sequence number and insertion code, and all atoms contained in it. If the requested residue does not exist in the chain, the function does nothing.


RETURN

The function returns the number of deleted residues, that is 1 or 0.

NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.

NOTE 2: Deleted residues and 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 CChain::DeleteResidue ( 
int  resNo )
PURPOSE
Deleting a residue by residue number.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

DESCRIPTION

The function deletes the resNoth residue in the chain's table of residues, and all atoms contained in it. If resNo is invalid or if such a residue does not exist in the chain, the function does nothing.


RETURN

The function returns the number of deleted residues, that is 1 or 0.

NOTE 1: Deleted residues and 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 CChain::GetNumberOfAtoms ( 
Boolean  countTers )
PURPOSE
Calculating the total number of atoms in the chain.
ARGUMENTS
Boolean countTers
Flag specifying if any termination records ("TER") should be counted as atoms. In MMDB, the termination records are kept as a special case of CAtom objects. If countTers is set to True, the termination records will be counted as atoms, otherwise they are ignored.

DESCRIPTION

The function performs an actual calculation of all atoms in the chain, not just returning the sum of lengths of atom tables. If some cells in atom tables are empty (set to NULL), they are not counted.


int CChain::GetNumberOfAtoms ( 
int  seqNum, 
InsCode insCode )
PURPOSE
Obtaining the number of atoms in residue by residue sequence number and insertion code.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns the number of atoms currently contained in the chain's residue identified by residue sequence number and insertion code. If the residue identification is invalid or if such a residue is not found in the chain, the function returns 0.

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.


int CChain::GetNumberOfAtoms ( 
int  resNo )
PURPOSE
Obtaining the number of atoms in residue by residue number.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

DESCRIPTION

The function returns the number of atoms currently contained in the chain's residue identified by residue number (that is, the residue position in the chain's table of residues). If the residue number is invalid or if such a residue is not found in the chain, the function returns 0.

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 CChain::GetAtom ( 
int  seqNum, 
InsCode insCode,
AtomName aname,
Element elname,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by residue sequence number, insertion code, atom name, element name, and alternative location indicator.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName aname
The atom name. It may or may not be aligned (as in a PDB file), only first word of the name will be considered (thus "CA", " CA" and " CA B" are all considered as "CA"). aname may be set to NULL or to wildcard "*", then this parameter is ignored.

Element elname
The atom's chemical element code. This parameter will work only if the element code was set up for the atom (which may take place in the case of reading atoms from old PDB files that do not contain the chemical element names; or if the atom was created in a tricky way by application). elname should be used to distinguish between, e.g. "Ca" and "C_alpha". All spaces in elname are ignored. elname may be set to NULL or to the wildcard "*", then this parameter is ignored.

AltLoc aloc
The atom's alternative location indicator. If atom does not have alternative location, this is indicated by empty string "". aloc may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function returns pointer on the atom identified by residue sequence number and insertion code, atom name, chemical element name and alternative location indicator. If any of these characteristics is invalid or if such an atom does not exist in the chain, 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 chain, the first one from the begining of the chain's table of residues and the residue's table of atoms is taken.

NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.


PCAtom CChain::GetAtom ( 
int  seqNum, 
InsCode insCode,
int atomNo )
PURPOSE
Obtaining an atom pointer by residue sequence number, residue insertion code and atom number.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number, that is the atom's position in the residue's table of atoms. The atoms in the table are numbered as 0..NumberOfAtoms-1 where NumberOfAtoms is returned by CChain::GetNumberOfAtoms.

DESCRIPTION

The function returns pointer on the atomNoth atom in the atom table of the chain's residue identified by residue sequence number and insertion code. If atom identification is invalid or if such an atom does not exist in the chain, the function returns NULL.


PCAtom CChain::GetAtom ( 
int  resNo, 
AtomName aname,
Element elname,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by residue number, atom name, element name and alternative location indicator.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

AtomName aname
The atom name. It may or may not be aligned (as in a PDB file), only first word of the name will be considered (thus "CA", " CA" and " CA B" are all considered as "CA"). aname may be set to NULL or to wildcard "*", then this parameter is ignored.

Element elname
The atom's chemical element code. This parameter will work only if the element code was set up for the atom (which may take place in the case of reading atoms from old PDB files that do not contain the chemical element names; or if the atom was created in a tricky way by application). elname should be used to distinguish between, e.g. "Ca" and "C_alpha". All spaces in elname are ignored. elname may be set to NULL or to the wildcard "*", then this parameter is ignored.

AltLoc aloc
The atom's alternative location indicator. If atom does not have alternative location, this is indicated by empty string "". aloc may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function returns pointer on the atom identified by residue number (that is, the residue's position in the chain's table of residues), atom name, chemical element name and alternative location indicator. If any of these characteristics is invalid or if such an atom does not exist in the chain, 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 chain, the first one from the begining of the chain's table of residues and the residue's table of atoms is taken.

NOTE : Comparison is case-sensitive. Consider that " " is not an empty string.


PCAtom CChain::GetAtom ( 
int  resNo, 
int atomNo )
PURPOSE
Obtaining an atom pointer by residue number and atom number.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

int atomNo
The atom number, that is the atom's position in the residue's table of atoms. The atoms in the table are numbered as 0..NumberOfAtoms-1 where NumberOfAtoms is returned by CChain::GetNumberOfAtoms.

DESCRIPTION

The function returns pointer on the atomNoth atom in the atom table of the resNoth residue in the chain's table of residues. If atom identification is invalid or if such an atom does not exist in the chain, the function returns NULL.


void CChain::GetAtomTable ( 
int  seqNum, 
InsCode insCode,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the residue's table of atoms by residue sequence number and insertion code.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the chain's residue identified by residue sequence number and insertion code. 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 or if the specified residue is not found in the chain, 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.


void CChain::GetAtomTable ( 
int  resNo, 
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the residue's table of atoms by residue number.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

PPCAtom & atomTable
The table of atoms.

int & NumberOfAtoms
The number of atoms.

DESCRIPTION

The function returns table of pointers on all atoms currently contained in the resNoth residue in the chain's table of residues. 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 or if the specified residue is not found in the chain, 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.


PCAtom CChain::DeleteAtom ( 
int  seqNum, 
InsCode insCode,
AtomName aname,
Element elname,
AltLoc aloc )
PURPOSE
Deleting an atom specified by residue sequence number, insertion code, atom name, element name, and alternative location indicator.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName aname
The atom name. It may or may not be aligned (as in a PDB file), only first word of the name will be considered (thus "CA", " CA" and " CA B" are all considered as "CA"). aname may be set to NULL or to wildcard "*", then this parameter is ignored.

Element elname
The atom's chemical element code. This parameter will work only if the element code was set up for the atom (which may take place in the case of reading atoms from old PDB files that do not contain the chemical element names; or if the atom was created in a tricky way by application). elname should be used to distinguish between, e.g. "Ca" and "C_alpha". All spaces in elname are ignored. elname may be set to NULL or to the wildcard "*", then this parameter is ignored.

AltLoc aloc
The atom's alternative location indicator. If atom does not have alternative location, this is indicated by empty string "". aloc may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function deletes the specified atom from the coordinate hierarchy: the atom is checked out and disposed.
The function returns the number of actually deleted atoms, which may be more than one if NULL or wildcard parameters have been supplied (cf. above). A zero return indicates that either the requested residue or atom in the residue were not found.

NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.

NOTE 2: If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.


PCAtom CChain::DeleteAtom ( 
int  seqNum, 
InsCode insCode,
int atomNo )
PURPOSE
Deleting an atom specified by residue sequence number, residue insertion code and atom number.
ARGUMENTS
int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number, that is the atom's position in the residue's table of atoms. The atoms in the table are numbered as 0..NumberOfAtoms-1 where NumberOfAtoms is returned by CChain::GetNumberOfAtoms.

DESCRIPTION

The function deletes the specified atom from the coordinate hierarchy: the atom is checked out and disposed.
The function returns the number of actually deleted atoms, which may be more than one if NULL or wildcard parameters have been supplied (cf. above). A zero return indicates that either the requested residue or atom in the residue were not found.

NOTE : If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.


PCAtom CChain::DeleteAtom ( 
int  resNo, 
AtomName aname,
Element elname,
AltLoc aloc )
PURPOSE
Deleting an atom specified by residue number, atom name, element name and alternative location indicator.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

AtomName aname
The atom name. It may or may not be aligned (as in a PDB file), only first word of the name will be considered (thus "CA", " CA" and " CA B" are all considered as "CA"). aname may be set to NULL or to wildcard "*", then this parameter is ignored.

Element elname
The atom's chemical element code. This parameter will work only if the element code was set up for the atom (which may take place in the case of reading atoms from old PDB files that do not contain the chemical element names; or if the atom was created in a tricky way by application). elname should be used to distinguish between, e.g. "Ca" and "C_alpha". All spaces in elname are ignored. elname may be set to NULL or to the wildcard "*", then this parameter is ignored.

AltLoc aloc
The atom's alternative location indicator. If atom does not have alternative location, this is indicated by empty string "". aloc may be set to NULL or to wildcard "*", then this parameter is ignored.

DESCRIPTION

The function deletes the specified atom from the coordinate hierarchy: the atom is checked out and disposed.
The function returns the number of actually deleted atoms, which may be more than one if NULL or wildcard parameters have been supplied (cf. above). A zero return indicates that either the requested residue or atom in the residue were not found.

NOTE 1: Comparison is case-sensitive. Consider that " " is not an empty string.

NOTE 2: If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.


PCAtom CChain::DeleteAtom ( 
int  resNo, 
int atomNo )
PURPOSE
Deleting an atom specified by residue number and atom number.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

int atomNo
The atom number, that is the atom's position in the residue's table of atoms. The atoms in the table are numbered as 0..NumberOfAtoms-1 where NumberOfAtoms is returned by CChain::GetNumberOfAtoms.

DESCRIPTION

The function deletes the specified atom from the coordinate hierarchy: the atom is checked out and disposed.
The function returns the number of actually deleted atoms, which may be 0 or 1. A zero return indicates that either the requested residue or atom in the residue were not found.

NOTE : If deletion of an atom leaves residue empty, the latter is not deleted. Empty residue gives no records in PDB file.


int CChain::DeleteAllAtoms ( 
int  seqNo, 
InsCode insCode )
PURPOSE
Deleting all atoms in the residue specified by sequence number and insertion code.
ARGUMENTS
int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function deletes all atoms in the specified residue of the chain. The function returns the number of actually deleted atoms.

NOTE : Note that the residue is not deleted, however stays empty. Empty residue gives no records in a PDB file.


int CChain::DeleteAllAtoms ( 
int  resNo )
PURPOSE
Deleting all atoms in the residue specified by its position in the chain.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

DESCRIPTION

The function is completely identical to CChain::DeleteAllAtoms except that the residue is specified by its position in the chain.


int CChain::DeleteAllAtoms ( 
 )
PURPOSE
Deleting all atoms in the chain.
DESCRIPTION

The function deletes all atoms in the chain. The function returns the number of actually deleted atoms.

NOTE : Note that the chain is not deleted, however stays empty. Empty chain gives no coordinate records in a PDB file.


int CChain::AddAtom ( 
int  seqNo, 
InsCode insCode,
PCAtom atom )
PURPOSE
Adding an atom to the residue specified by sequence number and insertion code.
ARGUMENTS
int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

PCAtom atom
The atom to be added to the residue.

DESCRIPTION

The function adds atom atom to the specified 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).


RETURN

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. Zero return may also mean that the residue is not found in the chain.

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.


int CChain::AddAtom ( 
int  resNo, 
PCAtom atom )
PURPOSE
Adding an atom to the residue specified by its position in the chain.
ARGUMENTS
int resNo
The residue number. It has nothing in common with the residue sequence number and represents the residue position in the chain's table of residues. The residue in the table are numbered as 0..NumberOfResidues-1 where NumberOfResidues is returned by CChain::GetNumberOfResidues.

PCAtom atom
The atom to be added to the residue.

DESCRIPTION

The function is completely identical to CChain::AddAtom except that the residue is specified by its position in the chain.


void CChain::SetEntryID ( 
IDCode  idCode )
PURPOSE
Setting the entry ID.
ARGUMENTS
IDCode idCode
New entry ID.

DESCRIPTION

The function sets the new entry ID, that is normally the 4-letter PDB entry code. The function will accomplish successfully only if the chain is properly associated with coordinate hierarchy.


pstr CChain::GetEntryID ( 
 )
PURPOSE
Obtaining the entry ID.
DESCRIPTION

The function returns the entry ID, that is normally the 4-letter PDB entry code. The ID is returned as a null-teminated string. If chain is not properly associated with coordinate hierarchy, the function returns empty string "".


void CChain::GetAtomStatistics ( 
RSAtomStat  AS )
PURPOSE
Calculating the averaged properties of all atoms in the chain.
ARGUMENTS
RSAtomStat AS
Reference to structure SAtomStat , which returns the average results.

DESCRIPTION

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.


int CChain::GetNofModResidues ( 
 )
PURPOSE
Obtaining the number of modified residues annotated in the chain.
DESCRIPTION

The function returns the number of modified residues annotated in the chain, i.e. the number of PDB MODRES records showing the chain's ID.


PCModRes CChain::GetModResidues ( 
int  modResNo )
PURPOSE
Obtaining the information on modified residue.
ARGUMENTS
int modResNo
The modified residue number. Modified residues, found in the chain, are enumerated as 0..NmodRes-1, where NmodRes is returned by CChain::GetNofModResidues.

DESCRIPTION

The function returns pointer to the class data containing all contents of the corresponding PDB MODRES record.


RETURN

The CModRes class has the following public fields that may be read by application:
 
Type Name Description
ResName   resName   The residue name used
ResName stdRes Standard residue name
int seqNum The residue sequence number
InsCode insCode The residue insertion code
pstr comment Description of the residue modification

Changing these values by application is generally harmless.

NOTE : The class returned by the function, can not be disposed. An attempt to do so by application will eventually crash the latter.


void CChain::ApplyTransform ( 
mat44 &  TMatrix )
PURPOSE
Applying a transformation matrix to coordinates of all atoms in the chain.
ARGUMENTS
mat44 & TMatrix
The transformation matrix.

DESCRIPTION

The function applies the rotational-translational transformation given by matrix TMatrix, to coordinates of all atoms in the chain.

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 CChain::isSolventChain ( 
 )
PURPOSE
Checking if the chain consists only of solvent molecules.
DESCRIPTION

The function returns True if the chain consists only of solvent residues.


int CChain::PutUDData ( 
int  UDDhandle, 
int iudd )
PURPOSE
Storing an integer User-Defined Data (UDD) in the chain.
ARGUMENTS
int UDDhandle
The UDD handle.

int iudd
The integer number to be stored in the chain.

DESCRIPTION

The function stores an integer contained in iudd in the chain, 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.


RETURN

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 chain, the data was not stored
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in chains, the data was not stored


int CChain::PutUDData ( 
int  UDDhandle, 
realtype rudd )
PURPOSE
Storing a real-type User-Defined Data (UDD) in the chain.
ARGUMENTS
int UDDhandle
The UDD handle.

realtype rudd
The real number to be stored in the chain.

DESCRIPTION

The function stores the real number contained in rudd in the chain, 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 CChain::PutUDData, see returns there.


int CChain::PutUDData ( 
int  UDDhandle, 
pstr sudd )
PURPOSE
Storing a string-type User-Defined Data (UDD) in the chain.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr sudd
The string to be stored in the chain.

DESCRIPTION

The function stores the string pointed by sudd in the chain, 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 CChain::PutUDData, see returns there.


int CChain::GetUDData ( 
int  UDDhandle, 
int & iudd )
PURPOSE
Retrieving an integer User-Defined Data (UDD) from the chain.
ARGUMENTS
int UDDhandle
The UDD handle.

int & iudd
The buffer to accept the integer data.

DESCRIPTION

The function retrieves an integer previously stored in the chain by function CChain::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.


RETURN

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 chain. iudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the chain. iudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in chains. iudd does not change.


int CChain::GetUDData ( 
int  UDDhandle, 
real & rudd )
PURPOSE
Retrieving a real-type User-Defined Data (UDD) from the chain.
ARGUMENTS
int UDDhandle
The UDD handle.

real & rudd
The buffer to accept the real-type data.

DESCRIPTION

The function retrieves a real number previously stored in the chain by function CChain::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.


RETURN

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 chain. rudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the chain. rudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in chains. rudd does not change.


int CChain::GetUDData ( 
int  UDDhandle, 
pstr & sudd )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the chain, dynamic buffer.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr & sudd
A pointer to dynamically-allocated string accepting the data.

DESCRIPTION

The function retrieves a string previously stored in the chain by function CChain::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.


RETURN

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 chain. sudd returns NULL.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the chain. sudd returns NULL.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in chains. sudd does not change.


int CChain::GetUDData ( 
int  UDDhandle, 
pstr sudd,
int maxlen )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the chain, fixed-size buffer.
ARGUMENTS
int UDDhandle
The UDD handle.

pstr sudd
A pointer to a string accepting the data.

int maxlen
A maximal number of characters, including the terminating NULL that sudd may to accept (not more than the physical length of sudd).

DESCRIPTION

The function retrieves a string previously stored in the chain by function CChain::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.


RETURN

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 chain. sudd returns empty string "".
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the chain. sudd returns empty string "".
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in chains. sudd does not change.


void CChain::Copy ( 
PCChain  chain )
PURPOSE
Copying the chain contents.
ARGUMENTS
PCChain chain
The source chain, whose contents is to be copied.

DESCRIPTION

The function copies the content of chain chain into internal class' fields. The function does copy all the chain's table of residues and it does redefine the residues' chain for the destination one. As a result, a new chain 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:

      PCChain chain1,chain2;
      chain1 = new CChain();
      chain2 = new CResidue();
      // doing something with chain2
      
      *chain1 = *chain2;  // never do this!
      
      // the right way:
      chain1->Copy ( chain2 );
    
Function Copy is supplied for all classes in the Library.



Back to index