CCP4 Coordinate Library Project

Object interface: Data class CModel.

Data class CModel represents a model in the coordinate hierarchy.

CModel contains all information, which is relevant to particular model and table of pointers on all chains (represented as classes of type CChain) that belong to the model.

Function Purpose
CModel::CModel Default constructor.
CModel::~CModel The class' destructor.
CModel::isInSelection Checking if model is selected.
CModel::GetSerNum Obtaining the model's serial number.
CModel::GetModelID Obtaining the model's coordinate ID.
CModel::SetEntryID Setting the entry ID.
CModel::GetEntryID Obtaining the entry ID.
CModel::GetNumberOfChains Obtaining the number of chains in the model.
CModel::GetChain Obtaining a chain pointer by chain ID.
CModel::GetChain Obtaining a chain pointer by chain number.
CModel::GetChainTable Obtaining the model's table of chains.
CModel::AddChain Adding a chain to the model.
CModel::DeleteAtom Deleting an atom specified by chain ID, sequence number, insertion code and atom name.
CModel::DeleteAtom Deleting an atom specified by chain ID, sequence number, insertion code and atom number.
CModel::DeleteAtom Deleting an atom specified by chain ID, residue number and atom name.
CModel::DeleteAtom Deleting an atom specified by chain ID, residue number and atom number.
CModel::DeleteAtom Deleting an atom specified by chain number, sequence number, insertion code and atom name.
CModel::DeleteAtom Deleting an atom specified by chain number, sequence number, insertion code and atom number.
CModel::DeleteAtom Deleting an atom specified by chain number, residue number and atom name.
CModel::DeleteAtom Obtaining an atom pointer by chain number, residue number and atom number.
CModel::DeleteAllAtoms Deleting all atoms in the residue specified by chain ID, sequence number and insertion code.
CModel::DeleteAllAtoms Deleting all atoms in the residue specified by chain ID and residue position in the chain.
CModel::DeleteAllAtoms Deleting all atoms in the model's chain specified by chain ID.
CModel::DeleteAllAtoms Deleting all atoms in the residue specified by chain number, sequence number and insertion code.
CModel::DeleteAllAtoms Deleting all atoms in the residue specified by chain number and residue position in the chain.
CModel::DeleteAllAtoms Deleting all atoms in the model's chain specified by chain number.
Cmodel::DeleteAllAtoms Deleting all atoms in the model.
CModel::DeleteChain Deleting a chain by chain ID.
CModel::DeleteChain Deleting a chain by chain number.
CModel::DeleteSolventChains Deleting all solvent chains from the model.
CModel::GetNumberOfResidues Obtaining the total number of residues in model.
CModel::GetNumberOfResidues Obtaining the number of residues in a chain by chain ID.
CModel::GetNumberOfResidues Obtaining the number of residues in a chain by chain number.
CModel::GetResidue Obtaining a residue pointer by chain ID, sequence number and insertion code.
CModel::GetResidue Obtaining a residue pointer by chain number, sequence number and insertion code.
CModel::GetResidue Obtaining a residue pointer by chain ID and residue number.
CModel::GetResidue Obtaining a residue pointer by chain number and residue number.
CModel::GetResidueNo Obtaining a residue position in chain by chain ID, residue sequence number and insertion code.
CModel::GetResidueNo Obtaining a residue position in chain by chain number, residue sequence number and insertion code.
CModel::GetResidueTable Obtaining the residue table by chain ID.
CModel::GetResidueTable Obtaining the residue table by chain number.
CModel::GetNumberOfAtoms Calculating the total number of atoms in the model.
CModel::GetNumberOfAtoms Obtaining the number of atoms in a residue by chain ID, sequence number and insertion code.
CModel::GetNumberOfAtoms Obtaining the number of atoms in a residue by chain number, sequence number and insertion code.
CModel::GetNumberOfAtoms Obtaining the number of atoms in a residue by chain ID and residue number.
CModel::GetNumberOfAtoms Obtaining the number of atoms in a residue by chain number and residue number.
CModel::GetAtom Obtaining an atom pointer by chain ID, sequence number, insertion code and atom name.
CModel::GetAtom Obtaining an atom pointer by chain ID, sequence number, insertion code and atom number.
CModel::GetAtom Obtaining an atom pointer by chain ID, residue number and atom name.
CModel::GetAtom Obtaining an atom pointer by chain ID, residue number and atom number.
CModel::GetAtom Obtaining an atom pointer by chain number, sequence number, insertion code and atom name.
CModel::GetAtom Obtaining an atom pointer by chain number, sequence number, insertion code and atom number.
CModel::GetAtom Obtaining an atom pointer by chain number, residue number and atom name.
CModel::GetAtom Obtaining an atom pointer by chain number, residue number and atom number.
CModel::GetAtomTable Obtaining the residue's table of atoms by chain ID, sequence number and insertion code.
CModel::GetAtomTable Obtaining the residue's table of atoms by chain ID and residue number.
CModel::GetAtomTable Obtaining the residue's table of atoms by chain number, sequence number and insertion code.
CModel::GetAtomTable Obtaining the residue's table of atoms by chain number and residue number.
CModel::AddAtom Adding an atom to the residue of the model specified by chain ID, sequence number and insertion code.
CModel::AddAtom Adding an atom to the residue of the model specified by chain number, sequence number and insertion code.
CModel::AddAtom Adding an atom to the residue of the model specified by chain ID and residue number.
CModel::AddAtom Adding an atom to the residue of the model specified by chain number and residue number.
CModel::GetNumberOfHelices Obtaining the number of helices in the model.
CModel::GetHelix Obtaining pointer on helix by helix number.
CModel::GetNumberOfSheets Obtaining the number of sheets in the model.
CModel::GetSheetID Obtaining the sheet ID by sheet serial number.
CModel::GetSheet Obtaining the sheet by sheet serial number.
CModel::GetSheet Obtaining the sheet by sheet ID.
CModel::GetNumberOfStrands Obtaining the number of strands in a sheet by sheet number.
CModel::GetNumberOfStrands Obtaining the number of strands in a sheet by sheet ID.
CModel::GetStrand Obtaining the number of strands in a sheet by sheet ID.
CModel::GetStrand Obtaining the number of strands in a sheet by sheet serial number.
CModel::RemoveSecStructure Removing the annotation of secondary structure from the model.
CModel::ApplyTransform Applying a transformation matrix to coordinates of all atoms in the model.
CModel::GetAtomStatistics Calculating the averaged properties of all atoms in the model.
CModel::PutUDData Storing an integer User-Defined Data (UDD) in the model.
CModel::PutUDData Storing a real-type User-Defined Data (UDD) in the model.
CModel::PutUDData Storing a string-type User-Defined Data (UDD) in the model.
CModel::GetUDData Retrieving an integer User-Defined Data (UDD) from the model.
CModel::GetUDData Retrieving a real-type User-Defined Data (UDD) from the model.
CModel::GetUDData Retrieving a string-type User-Defined Data (UDD) from the model, dynamic buffer.
CModel::GetUDData Retrieving a string-type User-Defined Data (UDD) from the model, fixed-size buffer.
CModel::Copy Copying the model contents.


 CModel::CModel ( 
 )
PURPOSE
Default constructor.
DESCRIPTION

Default constructor creates an empty CModel object.


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

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

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

    PCMMDBManager MMDB;
    PCModel       model;
      model = MMDB->GetModel ( "/1" );
      delete model;  // 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.


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

DESCRIPTION

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

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


int CModel::GetSerNum ( 
 )
PURPOSE
Obtaining the model's serial number.
DESCRIPTION

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


pstr CModel::GetModelID ( 
pstr  CID )
PURPOSE
Obtaining the model's coordinate ID.
ARGUMENTS
pstr CID
A string to accept the model's coordinate ID.

DESCRIPTION

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

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


void CModel::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 model is properly associated with coordinate hierarchy.


pstr CModel::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 model is not properly associated with coordinate hierarchy, the function returns empty string "".


int CModel::GetNumberOfChains ( 
 )
PURPOSE
Obtaining the number of chains in the model.
DESCRIPTION

The function returns the number of chains currently contained in the model


PCChain CModel::GetChain ( 
ChainID  chainID )
PURPOSE
Obtaining a chain pointer by chain ID.
ARGUMENTS
ChainID chainID
The chain ID.

DESCRIPTION

The function returns pointer on the chain identified by chain ID. If such a chain does not exist in the model, the function returns NULL.


PCChain CModel::GetChain ( 
int  chainNo )
PURPOSE
Obtaining a chain pointer by chain number.
ARGUMENTS
int chainNo
The chain number.

DESCRIPTION

The function returns pointer on the chain that identified by its position in the table of chains in the model. The chains are numbered as 0..NumberOfChains-1, where NumberOfChains is returned by CModel::GetNumberOfChains. If the chain number is invalid or if such a chain does not exist in the model, the function returns NULL.

The chain number is defined by the order of the chain appearance in the coordinate file. Certain sections of PDB file (e.g. the SEQRES records) may in practice mention the chains in arbitrary order, but it is the order of chains in the coordinate section that matters here.


void CModel::GetChainTable ( 
PPCChain &  chainTable, 
int & NumberOfChains )
PURPOSE
Obtaining the model's table of chains.
ARGUMENTS
PPCChain & chainTable
The table of chains.

int & NumberOfChains
The number of chains.

DESCRIPTION

The function returns table of pointers on all chains currently contained in the model, and their number. The chains are indexed as 0..NumberOfChains-1 in the table.

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

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


void CModel::AddChain ( 
PCChain  chain )
PURPOSE
Adding a chain to the model.
ARGUMENTS
PCChain chain
The chain to be added. The chain must be associated with a coordinate hierarchy.

DESCRIPTION

The function adds the specified chain on the top of current chain table. No checks on the duplication of chain IDs is being made. The chain with all atoms and residues, is copied, not moved.

Both the model and the added chain must be associated with coordinate hierarchies. If both model and chain belong to the same coordinate hierarchy, the chain will be duplicated.

NOTE 1: The application does not have to call CMMDBManager::FinishStructEdit after return from this function, although such a call would be completely harmless.

NOTE 2: The function does not take care about serial numbers of copied atoms. If they need to be put in order, the application should call CMMDBManager::PDBCleanup with input flag PDBCLEAN_SERIAL. Similarly, possible clashes of duplicated chain IDs can be resolved by CMMDBManager::PDBCleanup with input flag PDBCLEAN_CHAIN or PDBCLEAN_CHAIN_STRONG.


int CModel::DeleteAtom ( 
ChainID  chainID, 
int seqNum,
InsCode insCode,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Deleting an atom specified by chain ID, sequence number, insertion code and atom name.
ARGUMENTS
ChainID chainID
The chain ID.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

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 chain, 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 or chain empty, the latter are not deleted. Empty residues and chains give no records in PDB file.


int CModel::DeleteAtom ( 
ChainID  chainID, 
int seqNum,
InsCode insCode,
int atomNo )
PURPOSE
Deleting an atom specified by chain ID, sequence number, insertion code and atom number.
ARGUMENTS
ChainID chainID
The chain ID.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function is conceptually identical to CModel::DeleteAtom, see there for details.


int CModel::DeleteAtom ( 
ChainID  chainID, 
int resNo,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Deleting an atom specified by chain ID, residue number and atom name.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function is conceptually identical to CModel::DeleteAtom, see there for details.


int CModel::DeleteAtom ( 
ChainID  chainID, 
int resNo,
int atomNo )
PURPOSE
Deleting an atom specified by chain ID, residue number and atom number.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function is conceptually identical to CModel::DeleteAtom, see there for details.


int CModel::DeleteAtom ( 
int  chainNo, 
int seqNum,
InsCode insCode,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Deleting an atom specified by chain number, sequence number, insertion code and atom name.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function is conceptually identical to CModel::DeleteAtom, see there for details.


int CModel::DeleteAtom ( 
int  chainNo, 
int seqNum,
InsCode insCode,
int atomNo )
PURPOSE
Deleting an atom specified by chain number, sequence number, insertion code and atom number.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function is conceptually identical to CModel::DeleteAtom, see there for details.


int CModel::DeleteAtom ( 
int  chainNo, 
int resNo,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Deleting an atom specified by chain number, residue number and atom name.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function is conceptually identical to CModel::DeleteAtom, see there for details.


int CModel::DeleteAtom ( 
int  chainNo, 
int resNo,
int atomNo )
PURPOSE
Obtaining an atom pointer by chain number, residue number and atom number.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's position in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function is conceptually identical to CModel::DeleteAtom, see there for details.

[undoc] CModel::DeleteAllAtoms ( int chNo, int seqNo, InsCode insCode ); [undoc] CModel::DeleteAllAtoms ( int chNo, int resNo ); [undoc] CModel::DeleteAllAtoms ( int chNo ); [undoc] CModel::DeleteAllAtoms ();


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

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function deletes all atoms in the specified residue of the model. 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 CModel::DeleteAllAtoms ( 
ChainID  chainID, 
int resNo )
PURPOSE
Deleting all atoms in the residue specified by chain ID and residue position in the chain.
ARGUMENTS
ChainID chainID
The chain ID.

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 conceptually identical to CModel::DeleteAllAtoms except that the residue is specified by its position in the chain.


int CModel::DeleteAllAtoms ( 
ChainID  chainID )
PURPOSE
Deleting all atoms in the model's chain specified by chain ID.
ARGUMENTS
ChainID chainID
The chain ID.

DESCRIPTION

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

NOTE : Note that the chain and residues in it are not deleted, however stay empty. Empty chain and residues give no records in a PDB file.


int CModel::DeleteAllAtoms ( 
int  chainNo, 
int seqNo,
InsCode insCode )
PURPOSE
Deleting all atoms in the residue specified by chain number, sequence number and insertion code.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int seqNo
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function deletes all atoms in the specified residue of the model. 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 CModel::DeleteAllAtoms ( 
int  chainNo, 
int resNo )
PURPOSE
Deleting all atoms in the residue specified by chain number and residue position in the chain.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

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 conceptually identical to CModel::DeleteAllAtoms except that the residue is specified by its position in the chain.


int CModel::DeleteAllAtoms ( 
int  chainNo )
PURPOSE
Deleting all atoms in the model's chain specified by chain number.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

DESCRIPTION

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

NOTE : Note that the chain and residues in it are not deleted, however stay empty. Empty chain and residues give no records in a PDB file.


int Cmodel::DeleteAllAtoms ( 
 )
PURPOSE
Deleting all atoms in the model.
DESCRIPTION

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

NOTE : Note that the model, its chains and residues are not deleted, however stay empty. Empty model gives no coordinate records in a PDB file.


int CModel::DeleteChain ( 
ChainID  chainID )
PURPOSE
Deleting a chain by chain ID.
ARGUMENTS
ChainID chainID
The chain ID.

DESCRIPTION

The function deletes the chain identified by chain ID and all residues and atoms contained in it. If the requested chain does not exist in the model, the function does nothing.


RETURN

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

NOTE 1: Comparison is case-sensitive. A chain that does not have a chain ID is identified by empty string "". Consider that " " is not an empty string.

NOTE 2: Deleted chains, 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 CModel::DeleteChain ( 
int  chainNo )
PURPOSE
Deleting a chain by chain number.
ARGUMENTS
int chainNo
The chain number.

DESCRIPTION

The function deletes chain that identified by its position in the table of chains in the model, and all residues and atoms contained in it. The chains are numbered as 0..NumberOfChains-1, where NumberOfChains is returned by CModel::GetNumberOfChains. If the chain number is invalid or if such a chain does not exist in the model, the function does nothing.

The chain number is defined by the order of the chain appearance in the coordinate file. Certain sections of PDB file (e.g. the SEQRES records) may in practice mention the chains in arbitrary order, but it is the order of chains in the coordinate section that matters here.


RETURN

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

NOTE 1: Deleted chains, 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 CModel::DeleteSolventChains ( 
 )
PURPOSE
Deleting all solvent chains from the model.
DESCRIPTION

The function deletes all solvent chains from the model. A solvent chain is a chain that contains only solvent molecules.


RETURN

The function returns the number of deleted chains.


int CModel::GetNumberOfResidues ( 
 )
PURPOSE
Obtaining the total number of residues in model.
DESCRIPTION

The function returns the number of residues currently contained in the model. The function performs an actual counting the residues, not just returning the sum of lengths of residue tables. If some cells of residue tables are empty (sert to NULL), they are not counted.


int CModel::GetNumberOfResidues ( 
ChainID  chainID )
PURPOSE
Obtaining the number of residues in a chain by chain ID.
ARGUMENTS
ChainID chainID
The chain ID.

DESCRIPTION

The function returns the number of residues currently contained in the chain identified by chain ID. If the specified chain is not found in the model, the function returns 0.


int CModel::GetNumberOfResidues ( 
int  chainNo )
PURPOSE
Obtaining the number of residues in a chain by chain number.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

DESCRIPTION

The function returns the number of residues currently contained in the chain identified by its position in the model's table of chains. If the specified chain number is invalid or such chain does not exist in the model, the function returns 0.


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

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 model's residue identified by sequence number, insertion code and chain ID. If any of these characteristics is invalid, or such a residue does not exist in the model, the function returns NULL.

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


PCResidue CModel::GetResidue ( 
int  chainNo, 
int seqNum,
InsCode insCode )
PURPOSE
Obtaining a residue pointer by chain number, sequence number and insertion code.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

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 model's residue identified by sequence number, insertion code and position of chain in the model's table of chains (chain number). If such a chain or residue does not exist, the function returns NULL.

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


PCResidue CModel::GetResidue ( 
ChainID  chainID, 
int resNo )
PURPOSE
Obtaining a residue pointer by chain ID and residue number.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns pointer on the residue identified by the residue number (within the chain) and chain ID. If such a chain or residue does not exist, the function returns NULL.

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


PCResidue CModel::GetResidue ( 
int  chainNo, 
int resNo )
PURPOSE
Obtaining a residue pointer by chain number and residue number.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns pointer on the residue identified by residue number (within a chain) and chain number (within the model). If such a chain or residue does not exist, the function returns NULL.


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

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 specified chain of the model. The residues in a chain are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues.

The residue is identified by chain ID, residue sequence number and insertion code. If chain with given chain ID does not exist, the function returns -2; if the residue does not exist in the chain, the return is -1.

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


int CModel::GetResidueNo ( 
int  chainNo, 
int seqNum,
InsCode insCode )
PURPOSE
Obtaining a residue position in chain by chain number, residue sequence number and insertion code.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

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 specified chain of the model. The residues in a chain are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues.

The residue is identified by chain number (that is, the chain position in the model), residue sequence number and insertion code. If chain number is incorrect, the function returns -2; if the residue does not exist in the chain, the return is -1.

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


void CModel::GetResidueTable ( 
ChainID  chainID, 
PPCResidue & resTable,
int & NumberOfResidues )
PURPOSE
Obtaining the residue table by chain ID.
ARGUMENTS
ChainID chainID
The chain ID.

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 identified by chain ID. NumberOfResidues returns the number of residues. The residues are indexed as 0..NumberOfResidues-1 in the table.

If the specified chain does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might leave residues empty. This results in empty cells in the residue table. 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 residue table.


void CModel::GetResidueTable ( 
int  chainNo, 
PPCResidue & resTable,
int & NumberOfResidues )
PURPOSE
Obtaining the residue table by chain number.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

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 identified by chain number (that is, the chain's position in the model's table of chains). NumberOfResidues returns the number of residues. The residues are indexed as 0..NumberOfResidues-1 in the table.

If the specified chain does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

NOTE 1: Certain editing operations might leave residues empty. This results in empty cells in the residue table. 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 residue table.


int CModel::GetNumberOfAtoms ( 
Boolean  countTers )
PURPOSE
Calculating the total number of atoms in the model.
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 model, 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 CModel::GetNumberOfAtoms ( 
ChainID  chainID, 
int SeqNum,
InsCode insCode )
PURPOSE
Obtaining the number of atoms in a residue by chain ID, sequence number and insertion code.
ARGUMENTS
ChainID chainID
The chain ID.

int SeqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the model. The residue is identified by chain ID, residue sequence number and insertion code. If any of these characteristics is invalid or if the residue is not found, 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 CModel::GetNumberOfAtoms ( 
int  chainNo, 
int SeqNum,
InsCode insCode )
PURPOSE
Obtaining the number of atoms in a residue by chain number, sequence number and insertion code.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

int SeqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the model. The residue is identified by chain number (that is, the chain's position in the model's table of chains), residue sequence number and insertion code. If any of these characteristics is invalid or if the residue is not found, 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 CModel::GetNumberOfAtoms ( 
ChainID  chainID, 
int resNo )
PURPOSE
Obtaining the number of atoms in a residue by chain ID and residue number.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the model. The residue is identified by chain ID and residue number (that is, the residue position in the chain's table of residues). If any of these characteristics is invalid or if the residue is not found, 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 CModel::GetNumberOfAtoms ( 
int  chainNo, 
int resNo )
PURPOSE
Obtaining the number of atoms in a residue by chain number and residue number.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

DESCRIPTION

The function returns the number of atoms currently contained in the specified residue of the model. The residue is identified by chain number (that is, the chain's position in the model's table of chains) and residue number (i.e. the residue's position in the chain's table of residues). If any of these characteristics is invalid or if the residue is not found, 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 CModel::GetAtom ( 
ChainID  chainID, 
int seqNum,
InsCode insCode,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by chain ID, sequence number, insertion code and atom name.
ARGUMENTS
ChainID chainID
The chain ID.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue sequence number, residue insertion code and chain ID. If any of these characteristics is invalid or if such an atom does not exist in coordinate hierarchy, the function returns NULL.


PCAtom CModel::GetAtom ( 
ChainID  chainID, 
int seqNum,
InsCode insCode,
int atomNo )
PURPOSE
Obtaining an atom pointer by chain ID, sequence number, insertion code and atom number.
ARGUMENTS
ChainID chainID
The chain ID.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's table of atoms, residue sequence number, residue insertion code and chain ID. If any of these characteristics is invalid or if such an atom does not exist in the model, the function returns NULL.


PCAtom CModel::GetAtom ( 
ChainID  chainID, 
int resNo,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by chain ID, residue number and atom name.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue number (that is the residue's position in the chain's table of residues) and chain ID. If any of these characteristics is invalid or if such an atom does not exist in the model, the function returns NULL.


PCAtom CModel::GetAtom ( 
ChainID  chainID, 
int resNo,
int atomNo )
PURPOSE
Obtaining an atom pointer by chain ID, residue number and atom number.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's table of atoms, residue number (that is the residue's position in the chain's table of residues) and chain ID. If any of these characteristics is invalid or if such an atom does not exist in the model, the function returns NULL.


PCAtom CModel::GetAtom ( 
int  chainNo, 
int seqNum,
InsCode insCode,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by chain number, sequence number, insertion code and atom name.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue sequence number, residue insertion code and chain number (that is, the position of chain in the model's table of chains). If any of these characteristics is invalid or if such an atom does not exist in the model, the function returns NULL.


PCAtom CModel::GetAtom ( 
int  chainNo, 
int seqNum,
InsCode insCode,
int atomNo )
PURPOSE
Obtaining an atom pointer by chain number, sequence number, insertion code and atom number.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int seqNum
The residue sequence number.

InsCode insCode
The residue insertion code.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's table of atoms, residue sequence number, residue insertion code and chain number (that is, the position of chain in the model's table of chains). If any of these characteristics is invalid or if such an atom does not exist in the model, the function returns NULL.


PCAtom CModel::GetAtom ( 
int  chainNo, 
int resNo,
AtomName atomName,
Element chelem,
AltLoc aloc )
PURPOSE
Obtaining an atom pointer by chain number, residue number and atom name.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's index in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

AtomName atomName
The atom name. This is the name that appears on PDB ATOM card, however all spaces are ignored.

Element chelem
The chemical element name. This parameter is optional and may be set to NULL, which stands for not taking it into account. The chemical element name should be however used for differentiating between atoms that have identical names after removing the aligning spaces. This is the case for, e.g., C-alphas and Calcium atoms.

AltLoc aloc
The alternative location indicator. The value of "" means "no alternative location indicator".

DESCRIPTION

The function returns pointer on the atom identified by its name, chemical element name, alternative location indicator, residue number (that is the residue's position in the chain's table of residues) and chain number - the position of chain in the model's table of chains. If any of these characteristics is invalid or if such an atom does not exist in the model, the function returns NULL.


PCAtom CModel::GetAtom ( 
int  chainNo, 
int resNo,
int atomNo )
PURPOSE
Obtaining an atom pointer by chain number, residue number and atom number.
ARGUMENTS
int chainNo
The chain number. The chain number is the chain's position in the model's table of chains. This table keeps chains in the order as they appear in the coordinate file. The table is indexed as chainNo=0..NumberOfChains-1, where NumberOfChains is obtained from CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

int atomNo
The atom number. The atom number is the atom's index in the residue's table of atoms. This table keeps atoms in the order as they appear in the coordinate file. The table is indexed as atomNo=0..NumberOfAtoms-1, where NumberOfAtoms is obtained from CModel::GetNumberOfAtoms or one of its overloaded analogues.

DESCRIPTION

The function returns pointer on the atom identified by its position in the residue's table of atoms, residue number (that is the residue's position in the chain's table of residues) and chain number - the position of chain in the model's table of a chains. If any of these characteristics is invalid or if such an atom does not exist in the model, the function returns NULL.


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

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 residue identified by sequence number, insertion code and chain ID. NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the specified chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

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 CModel::GetAtomTable ( 
ChainID  chainID, 
int resNo,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the residue's table of atoms by chain ID and residue number.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

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 residue identified by chain ID and the residue's position 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 the specified chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

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 CModel::GetAtomTable ( 
int  chainNo, 
int seqNum,
InsCode insCode,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the residue's table of atoms by chain number, sequence number and insertion code.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

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 residue identified by sequence number, insertion code and chain number (that is, the position of the chain in the model's table of chains). NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the specified chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

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 CModel::GetAtomTable ( 
int  chainNo, 
int resNo,
PPCAtom & atomTable,
int & NumberOfAtoms )
PURPOSE
Obtaining the residue's table of atoms by chain number and residue number.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

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 residue identified by its position in the chain's table of residues and chain number (that is, the chain's position in the model's table of chains). NumberOfAtoms returns the number of atoms. The atoms are indexed as 0..NumberOfAtoms-1 in the table.

If the specified model, chain or residue does not exist, the function returns NULL for resTable and 0 for NumberOfResidues.

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 CModel::AddAtom ( 
ChainID  chainID, 
int seqNum,
InsCode insCode,
PCAtom atom )
PURPOSE
Adding an atom to the residue of the model specified by chain ID, sequence number and insertion code.
ARGUMENTS
ChainID chainID
The chain ID.

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.

PCAtom atom
The atom that should 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 (chain and model) 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.

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 CModel::AddAtom ( 
int  chainNo, 
int seqNum,
InsCode insCode,
PCAtom atom )
PURPOSE
Adding an atom to the residue of the model specified by chain number, sequence number and insertion code.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

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.

PCAtom atom
The atom that should be added to the residue.

DESCRIPTION

The function is conceptually identical to CModel::AddAtom, see there for details.


int CModel::AddAtom ( 
ChainID  chainID, 
int resNo,
PCAtom atom )
PURPOSE
Adding an atom to the residue of the model specified by chain ID and residue number.
ARGUMENTS
ChainID chainID
The chain ID.

int resNo
The residue number. The residue number does not have any relation to residue sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

PCAtom atom
The atom that should be added to the residue.

DESCRIPTION

The function is conceptually identical to CModel::AddAtom, see there for details.


int CModel::AddAtom ( 
int  chainNo, 
int resNo,
PCAtom atom )
PURPOSE
Adding an atom to the residue of the model specified by chain number and residue number.
ARGUMENTS
int chainNo
The chain number. All chains in the model are numbered as 0..NumberOfChains-1, where NumberOfChains is given by CModel::GetNumberOfChains.

int resNo
The residue number. The residue number does not have any relation to sequence number, and is merely a serial number of the residue in chain. The residues are numbered as 0..NumberOfResidues-1, where NumberOfResidues is returned by CModel::GetNumberOfResidues or its overloaded analogue.

PCAtom atom
The atom that should be added to the residue.

DESCRIPTION

The function is conceptually identical to CModel::AddAtom, see there for details.


int CModel::GetNumberOfHelices ( 
 )
PURPOSE
Obtaining the number of helices in the model.
DESCRIPTION

The function returns the number of helices in the model.

NOTE : The function does not perform identification of the secondary structure elements. It returns number of helices as annotated in PDB file.


PCHelix CModel::GetHelix ( 
int  helixSerNum )
PURPOSE
Obtaining pointer on helix by helix number.
ARGUMENTS
int helixSerNum
The helix' serial number. The helices are numbered as 1..NumberOfHelices, where NumberOfHelices is returned by CModel::GetNumberOfHelices.

DESCRIPTION

The function returns pointer on the specified helix. If helix with given serial number is not found in the model, the function returns NULL.

NOTE : The function does not perform identification of the secondary structure elements. It returns the helix information block as annotated in PDB file.


int CModel::GetNumberOfSheets ( 
 )
PURPOSE
Obtaining the number of sheets in the model.
DESCRIPTION

The function returns the number of sheets in the model.

NOTE : The function does not perform identification of the secondary structure elements. It returns number of sheets as annotated in PDB file.


int CModel::GetSheetID ( 
int  sheetSerNum, 
SheetID sheetID )
PURPOSE
Obtaining the sheet ID by sheet serial number.
ARGUMENTS
int sheetSerNum
The serial number of the sheet. The sheets are numbered as 1..NumberOfSheets, where NumberOfSheets is returned by CModel::GetNumberOfSheets.

SheetID sheetID
String buffer to accept the sheet ID. The ID is returned as null-terminated string.

DESCRIPTION

The function returns the sheet ID corresponding to the sheet identified by the sheet's serial number. If this number is not valid, the function returns empty string "".

NOTE : The function does not perform identification of the secondary structure elements. It returns the sheet ID as annotated in PDB file.


PCSheet CModel::GetSheet ( 
int  sheetSerNum )
PURPOSE
Obtaining the sheet by sheet serial number.
ARGUMENTS
int sheetSerNum
The serial number of the sheet. The sheets are numbered as 1..NumberOfSheets, where NumberOfSheets is returned by CModel::GetNumberOfSheets.

DESCRIPTION

The function returns pointer on the specified sheet. If the provided sheet's serial number is invalid, the function returns NULL.

NOTE : The function does not perform identification of the secondary structure elements. It returns the sheet information block as annotated in PDB file.


PCSheet CModel::GetSheet ( 
SheetID  sheetID )
PURPOSE
Obtaining the sheet by sheet ID.
ARGUMENTS
SheetID sheetID
The sheet ID given as a null-terminated string.

DESCRIPTION

The function returns pointer on the specified sheet. If the provided sheet ID is invalid, the function returns NULL.

NOTE : The function does not perform identification of the secondary structure elements. It returns the sheet information block as annotated in PDB file.


int CModel::GetNumberOfStrands ( 
int  sheetSerNum )
PURPOSE
Obtaining the number of strands in a sheet by sheet number.
ARGUMENTS
int sheetSerNum
The serial number of the sheet. The sheets are numbered as 1..NumberOfSheets, where NumberOfSheets is returned by CModel::GetNumberOfSheets.

DESCRIPTION

The function returns the number of strands in the specified sheet found in the model.

NOTE : The function does not perform identification of the secondary structure elements. It returns number of strands as annotated in PDB file.


int CModel::GetNumberOfStrands ( 
SheetID  sheetID )
PURPOSE
Obtaining the number of strands in a sheet by sheet ID.
ARGUMENTS
SheetID sheetID
The sheet ID, represented as a null-terminated string.

DESCRIPTION

The function returns the number of strands in the specified sheet found in the model.

NOTE : The function does not perform identification of the secondary structure elements. It returns number of strands as annotated in PDB file.


PCStrand CModel::GetStrand ( 
SheetID  sheetID, 
int strandSerNum )
PURPOSE
Obtaining the number of strands in a sheet by sheet ID.
ARGUMENTS
SheetID sheetID
The sheet ID, represented as a null-terminated string.

int strandSerNum
The strand serial number. For a given sheet, the strands are numbered as 1..NumberOfStrands, where NumberOfStrands is returned by CModel::GetNumberOfStrands.

DESCRIPTION

The function returns a pointer on strand identified by sheet ID and the strand's serial number in the sheet. If such a strand is not found, the function returns NULL.

NOTE : The function does not perform identification of the secondary structure elements. It returns the strand information block as annotated in PDB file.


PCStrand CModel::GetStrand ( 
int  sheetSerNum, 
int strandSerNum )
PURPOSE
Obtaining the number of strands in a sheet by sheet serial number.
ARGUMENTS
int sheetSerNum
The serial number of the sheet. The sheets are numbered as 1..NumberOfSheets, where NumberOfSheets is returned by CModel::GetNumberOfSheets.

int strandSerNum
The strand serial number. For a given sheet, the strands are numbered as 1..NumberOfStrands, where NumberOfStrands is returned by CModel::GetNumberOfStrands.

DESCRIPTION

The function returns a pointer on strand identified by sheet serial number and the strand's serial number in the sheet. If such a strand is not found, the function returns NULL.

NOTE : The function does not perform identification of the secondary structure elements. It returns the strand information block as annotated in PDB file.


void CModel::RemoveSecStructure ( 
 )
PURPOSE
Removing the annotation of secondary structure from the model.
DESCRIPTION

The function removes annotation of secondary structure elements (PDB records HELIX, SHEET and TURN) from the model.


void CModel::ApplyTransform ( 
mat44 &  TMatrix )
PURPOSE
Applying a transformation matrix to coordinates of all atoms in the model.
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 model.

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.


void CModel::GetAtomStatistics ( 
RSAtomStat  AS )
PURPOSE
Calculating the averaged properties of all atoms in the model.
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 CModel::PutUDData ( 
int  UDDhandle, 
int iudd )
PURPOSE
Storing an integer User-Defined Data (UDD) in the model.
ARGUMENTS
int UDDhandle
The UDD handle.

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

DESCRIPTION

The function stores an integer contained in iudd in the model, 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 model, the data was not stored
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in models, the data was not stored


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

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

DESCRIPTION

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


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

pstr sudd
The string to be stored in the model.

DESCRIPTION

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


int CModel::GetUDData ( 
int  UDDhandle, 
int & iudd )
PURPOSE
Retrieving an integer User-Defined Data (UDD) from the model.
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 model by function CModel::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 model. iudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the model. iudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in models. iudd does not change.


int CModel::GetUDData ( 
int  UDDhandle, 
real & rudd )
PURPOSE
Retrieving a real-type User-Defined Data (UDD) from the model.
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 model by function CModel::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 model. rudd returns zero.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the model. rudd returns zero.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in models. rudd does not change.


int CModel::GetUDData ( 
int  UDDhandle, 
pstr & sudd )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the model, 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 model by function CModel::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 model. sudd returns NULL.
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the model. sudd returns NULL.
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in models. sudd does not change.


int CModel::GetUDData ( 
int  UDDhandle, 
pstr sudd,
int maxlen )
PURPOSE
Retrieving a string-type User-Defined Data (UDD) from the model, 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 model by function CModel::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 model. sudd returns empty string "".
UDDATA_WrongHandle    the UDD handle UDDhandle does not correspond to any registered UDD for the model. sudd returns empty string "".
UDDATA_WrongUDRType    the UDD handle UDDhandle was not registered for use in models. sudd does not change.


void CModel::Copy ( 
PCModel  model )
PURPOSE
Copying the model contents.
ARGUMENTS
PCModel model
The source model, whose contents is to be copied.

DESCRIPTION

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

      PCModel model1,model2;
      model1 = new CModel();
      model2 = new CModel();
      // doing something with model2
      
      *model1 = *model2;  // never do this!
      
      // the right way:
      model1->Copy ( model2 );
    
Function Copy is supplied for all classes in the Library.



Back to index