CCP4 Coordinate Library Project

Object interface: Editing the coordinate hierarchy.

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 tables
CMMDBManager 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 )
PURPOSE
Adjusting the coordinate hierarchy to the PDB format.
ARGUMENTS
word CleanKey
A bitwise flag indicating which pieces of information should be adjusted to the PDB standard. It may be any combination (bitwise OR) of the following flags:

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).


DESCRIPTION

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.


RETURN

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 ( 
 )
PURPOSE
Making internal references after editing operations.
DESCRIPTION

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 )
PURPOSE
Deleting a model from coordinate hierarchy by model number.
ARGUMENTS
int modelNum
Model's serial number. The models are numbered as 1..NumberOfModels, where NumberOfModels is returned by CMMDBManager::GetNumberOfModels.

DESCRIPTION

The function deletes the specified model from coordinate hierarchy. The model and all chains, residues and atoms contained in it, are disposed.


RETURN

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 )
PURPOSE
Deleting a model from coordinate hierarchy by coordinate ID.
ARGUMENTS
pstr CID
Model's coordinate ID.

DESCRIPTION

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.


RETURN

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 ( 
 )
PURPOSE
Deleting all models from coordinate hierarchy.
DESCRIPTION

The function deletes all model from coordinate hierarchy. All models, chains, residues and atoms contained in the hierarchy, are disposed.


RETURN

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 )
PURPOSE
Deleting selected objects.
ARGUMENTS
int selHnd
The selection handle.

DESCRIPTION

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 )
PURPOSE
Adding a model on the top of coordinate hierarchy.
ARGUMENTS
PCModel model
Model that should be added. The model must be associated with a coordinate hierarchy.

DESCRIPTION

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.


RETURN

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, 
int modelNo )
PURPOSE
Inserting a model into the coordinate hierarchy.
ARGUMENTS
PCModel model
Model that should be added. The model must be associated with a coordinate hierarchy.

int modelNo
The number of model, before which the new model should be inserted.

DESCRIPTION

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.


RETURN

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, 
int modelNo2,
int rotdir )
PURPOSE
Rearranging (rotating) models in the coordinate hierarchy.
ARGUMENTS
int modelNo1
Starting model serial number.

int modelNo2
Ending model serial number

int rotdir
Direction of the rotation

DESCRIPTION

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, 
int modelNo2 )
PURPOSE
Rearranging (swapping) models in the coordinate hierarchy.
ARGUMENTS
int modelNo1
First swapping model serial number.

int modelNo2
Second swapping model serial number

DESCRIPTION

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.



Back to index