The Library allows for editing the coordinate hierarchy, that is, deletion and insertion of models, chains, residues or atoms. Editing operations change internal references between the elements of coordinate hierarchy and are therefore sensitive to program errors. An application may perform editing operations only by means provided by the Library.
In order to save computation time on calculations of all internal references after every editing operation, the Library, instead, provides a special function CMMDBManager::FinishStructEdit for such calculations, which must be called after all editing operations are done. It is important to keep in mind that a set of editing operations is not complete until this function is activated. From the other hand, CMMDBManager::FinishStructEdit is not a "commit" function and therefore applying any editing operation already means a change. The following two examples demonstrate two (and these are not the only two) alternative, perhaps equally efficient, ways of deletion of all oxygen atoms from the coordinate hierarchy: Example 1: using internal tablesCMMDBManager MMDB; int RC, im,ic,ir; int nModels,nChains,nResidues; PPCModel model; PPCChain chain; PPCResidue res; // read coordinate file RC = MMDB.ReadCoorFile ( CoorFileName ); if (RC) { .. checking for errors exit(1); } // get table of models MMDB.GetModelTable ( model,nModels ); // loop over all models for (im=0;im<nModels;im++) if (model[im]) { // get chain table of im-th model model[im]->GetChainTable ( chain,nChains ); // loop over all chains: for (ic=0;ic<nChains;ic++) if (chain[ic]) { // get residue table for current chain: chain[ic]->GetResidueTable ( res,nResidues ); // loop over all residues in current chain: for (ir=0;ir<nResidues;ir++) // delete all oxygens in the residue if (res[ir]) res[ir]->DeleteAtom ( "*","O","*" ); } } // update internal references; all tables above become // invalid. MMDB.FinishStructEdit();Example 2: using atom selection
CMMDBManager MMDB; int RC, i; int nAtoms; int selHnd; PPCAtom atom; // read coordinate file RC = MMDB.ReadCoorFile ( CoorFileName ); if (RC) { .. checking for errors exit(1); } // get new selection handle selHnd = MMDB.NewSelection(); // select all oxygens MMDB.Select ( selHnd,STYPE_ATOM,0,"*", ANY_RES,"*",ANY_RES,"*", "*","*","O","*",SKEY_NEW ); // get selected set of atoms MMDB.GetSelIndex ( selHnd,atom,nAtoms ); // deletion loop over all selected atoms. // NOTE that the atom array itself must // be neither deleted nor changed! for (i=0;i<nAtoms;i++) delete atom[i]; // update internal references MMDB.FinishStructEdit();
Function | Purpose |
CMMDBManager::PDBCleanup | Adjusting the coordinate hierarchy to the PDB format.
|
CMMDBManager::FinishStructEdit | Making internal references after editing operations.
|
CMMDBManager::DeleteModel | Deleting a model from coordinate hierarchy by model number.
|
CMMDBManager::DeleteModel | Deleting a model from coordinate hierarchy by coordinate ID.
|
CMMDBManager::DeleteAllModels | Deleting all models from coordinate hierarchy.
|
CMMDBManager::DeleteSelObjects | Deleting selected objects.
|
CMMDBManager::AddModel | Adding a model on the top of coordinate hierarchy.
|
CMMDBManager::InsModel | Inserting a model into the coordinate hierarchy.
|
CMMDBManager::RotateModels | Rearranging (rotating) models in the coordinate hierarchy.
|
CMMDBManager::SwapModels | Rearranging (swapping) models in the coordinate hierarchy.
|
word CMMDBManager::PDBCleanup ( |
word CleanKey ) |
Flag Name | Value | Description | |
PDBCLEAN_ATNAME | 0x00000001 | Pads atom names with spaces to form the PDB 4-character names | |
PDBCLEAN_TER | 0x00000002 | Inserts TER records in the end of each chain | |
PDBCLEAN_CHAIN | 0x00000004 | Generates 1-character chain IDs for chains having many-character IDs | |
PDBCLEAN_CHAIN_STRONG | 0x00000008 | Renames all the chains such that all the chains have 1-character IDs starting from 'A' for the first chain. Even 1-character chain IDs are renamed if chains are not named incrementally starting from 'A'. | |
PDBCLEAN_ALTCODE | 0x00000010 | Generates 1-character alternative location indicators for atoms having many-character alternative location IDs | |
PDBCLEAN_ALTCODE_STRONG | 0x00000020 | Renames all alternative location indicators such that all of them are of 1-character length starting from 'A'. Even 1-character indicators are renamed if they are not named incrementally starting from 'A'. | |
PDBCLEAN_SERIAL | 0x00000040 | Generates new serial numbers of atoms incrementally-by-one starting from 1. | |
PDBCLEAN_SEQNUM | 0x00000080 | Generates new sequence numbers for residues such that they go incrementally-by-one starting from 1 without insertion codes. | |
PDBCLEAN_CHAIN_ORDER | 0x00000100 | Rearranges chains in order of atoms' serial numbers. | |
PDBCLEAN_SOLVENT | 0x00000200 | Identifies chains consisting only of solvent molecules, and puts them in the end of models. Solvent molecules are those named ADE, CYT, GUA, INO, THY, URA, WAT, HOH, TIP, H2O, DOD or MOH. | |
PDBCLEAN_INDEX | 0x00000400 | Rearranges atoms in the internal table of atoms such that they follow precisely the order given by the model/chain/residue hierarchy. This flag may be used after adding or inserting atoms into residues (see the corresponding functions). |
The function should be used after operations that may result in violation of PDB standards, if the information is to be output into a PDB file. For example, insertion or deletion of atoms will create gaps in atoms' serial numbers, symmetry operations will assign many-character chain names to newly generated chains and so on. Checking for compliency with PDB rules is not implemented as a part of such operations in order to keep the computational costs down. PDBCleanup does not have to be called after each such operation. Probably a good style would be to call it once before writing the PDB file, if necessary.
The function returns 0 after successful operation. A non-zero return should be considered as a bitwise message:
Return Bit | Description |
PDBCLEAN_CHAIN | there are too many chains to generate 1-character chain IDs |
PDBCLEAN_ATNAME | there is no element names (as read from a coordinate file or otherwise set up for all atoms) to generate 4-character PDB atom names |
PDBCLEAN_ALTCODE | there are too many alternative locations to generate 1-character alternative location indicators |
void CMMDBManager::FinishStructEdit ( |
) |
The function checks the coordinate hierarchy for new and deleted items and makes new internal reference tables. The function must be called after all editing operations (insertion/deletion) are complete. There is no limit on the number of editing operations between calls to this function.
NOTE 1: An edited coordinate hierarchy is not usable if CMMDBManager::FinishStructEdit is not called after editing. Violation of this rule will cause memory fault in most cases.
NOTE 2: After the function returns, the previous tables of atoms, residues, chains and models become invalid. The function may change the number of atoms, residues etc. on all levels of coordinate hierarchy. The function also changes CAtom::index fields.
int CMMDBManager::DeleteModel ( |
int modelNum ) |
The function deletes the specified model from coordinate hierarchy. The model and all chains, residues and atoms contained in it, are disposed.
The function returns 1 if the model was deleted, and 0 if model with specified serial number was not found.
NOTE : An application must call CMMDBManager::FinishStructEdit in order to validate the deletion.
int CMMDBManager::DeleteModel ( |
pstr CID ) |
The function deletes the model found in the provided coordinate ID from coordinate hierarchy. The model and all chains, residues and atoms contained in it, are disposed.
The function returns 1 if the model was deleted, and 0 if model with serial number as found from the provided coordinate ID was not found.
NOTE : An application must call CMMDBManager::FinishStructEdit in order to validate the deletion.
int CMMDBManager::DeleteAllModels ( |
) |
The function deletes all model from coordinate hierarchy. All models, chains, residues and atoms contained in the hierarchy, are disposed.
The function returns the number of deleted models.
NOTE : As an exception, an application does not have to call CMMDBManager::FinishStructEdit in order to validate the deletion after this function. However, such a call would be completely harmless.
void CMMDBManager::DeleteSelObjects ( |
int selHnd ) |
The function deletes all selected objects associated with the given selection handle. The type of selected object is unambiguously defined by the handle. See more details about selection toold in Selection functions.
NOTE : An application must call CMMDBManager::FinishStructEdit in order to validate the deletion.
int CMMDBManager::AddModel ( |
PCModel model ) |
The function adds the specified model on the top of coordinate hierarchy. All chains, residues and atoms contained in the model, are physically copied into the hierarchy. The model may belong to the same hierarchy, in which case it will be duplicated.
The function returns the resulting number of models, which is the serial number of the model added.
NOTE 1: The model must be associated with a coordinate hierarchy. It may be retrieved from that hierarchy by calling CMMDBManager::GetModel.
NOTE 2: The function does change the models' serial numbers so that they are always incremental-by-one in PDB file. However, the function does not change the serial numbers of atoms. They may be put into proper order by calling the CMMDBManager::PDBCleanup with input flag PDBCLEAN_SERIAL.
NOTE 3: As an exception, an application does not have to call CMMDBManager::FinishStructEdit in order to validate the addition. However, such a call would be completely harmless.
int CMMDBManager::InsModel ( |
PCModel model, |
The function inserts the specified model on the
modelNo-th position in the
coordinate hierarchy. All chains,
residues and atoms contained in the model, are physically copied into
the hierarchy. The model may belong to the same hierarchy, in which
case it will be duplicated.
The model is assigned the serial number modelNo,
the former modelNo-th model gets the serial number
modelNo+1, and serial numbers of all models
greater than modelNo are increased by 1.
The function returns the resulting number of models.
NOTE 1: The model must be associated with a coordinate hierarchy. It may be retrieved from that hierarchy by calling CMMDBManager::GetModel.
NOTE 2: The function does change the models' serial numbers so that they are always incremental-by-one in PDB file. However, the function does not change the serial numbers of atoms. They may be put into proper order by calling the CMMDBManager::PDBCleanup with input flag PDBCLEAN_SERIAL.
NOTE 3: As an exception, an application does not have to call CMMDBManager::FinishStructEdit in order to validate the insertion. However, such a call would be completely harmless.
void CMMDBManager::RotateModels ( |
int modelNo1, |
The function rearranges model in the
coordinate hierarchy by cyclically
shifting them. The shift is performed on models with serial numbers
ranging from modelNo1 to modelNo2
in the direction specified by rotdir.
If rotdir is positive, the models are shifted
to the left, with modelNo1-th model replaced
by modelNo2-th.
If rotdir is negative, the models are shifted
to the right, with modelNo2-th model replaced
by modelNo1-th.
NOTE 1: The function does change the models' serial numbers so that they are always incremental-by-one in PDB file. However, the function does not change the serial numbers of atoms. They may be put into proper order by calling the CMMDBManager::PDBCleanup with input flag PDBCLEAN_SERIAL.
NOTE 2: As an exception, an application does not have to call CMMDBManager::FinishStructEdit in order to validate the insertion. However, such a call would be completely harmless.
void CMMDBManager::SwapModels ( |
int modelNo1, |
The function rearranges model in the coordinate hierarchy by swapping models modelNo1 and modelNo2.
NOTE 1: The function does change the models' serial numbers so that they are always incremental-by-one in PDB file. However, the function does not change the serial numbers of atoms. They may be put into proper order by calling the CMMDBManager::PDBCleanup with input flag PDBCLEAN_SERIAL.
NOTE 2: As an exception, an application does not have to call CMMDBManager::FinishStructEdit in order to validate the insertion. However, such a call would be completely harmless.