CCP4 Coordinate Library Project

Object interface: Selection functions.

Selection functions allows for selecting atoms, residues, chains and models. Selected objects are represented on a uniform indexed space, which may be used for extracting the objects' properties and performing different sort of operations, such as looking for contacts between atoms, on them.

COMMON NOTES AND DEFINITIONS
Technology
Physically, the selection of an object is done by assigning a dynamical-length bitwise mask to it. The mask is unique for each selection and all generated masks are orthogonal to each other (that is, they do not have common bits). The assignment of the mask is followed by compilation of an index for each selection. Any selection set may be expanded up or shrinked down using the Manager functions.

The selection masks are not available for application. Instead, they are associated with selection handles, which are the only references to particular selections.

There is no principal limitations on the number of selection sets; however each selection consumes certain amount of RAM, which may be roughly estimated as 2*Nsel words, where Nsel stands for the number of selected objects.

Selection Handle
Each selection is associated with an ID, called the selection handle (uniformly designated as selHnd below). Selection handles are generated by the Manager (see CMMDBManager::NewSelection) and cannot be otherwise created, changed or interpreted by application. Any object may participate in arbitrary number of selections simultaneously, however objects of different types cannot be mixed in one selection set (that is, e.g., atoms and chains cannot be addressed by the same selection handle). Thus each selection handle is assigned a selection type - STYPE_ATOM, STYPE_RESIDUEe, STYPE_CHAIN or STYPE_MODEL (see below) - which cannot be changed after first selection has been done. The assignment of the selection type takes place automatically at first selection according to the type of selection object. However, the selection of an object may be propagated up and down the coordinate hierarchy (it is possible, e.g., to select all atoms in selected chains or to select all chains containing selected residues).

Selection Key
The type of selection operation is defined by the value of selection key (uniformly designated as selKey below), which is a parameter of every selection function. The The key specifies how the requested selection operation applies to the existing selection associated with given selection handle:
Selection Key Value Description
SKEY_NEW 0 the previous selection, if existed, is wiped out. In the case of preexisting selection, the newly selected objects must have the same selection type (atom for this function).
SKEY_OR 1 the new selection is added to already selected set; if no selection preexists, SKEY_NEW and SKEY_OR are equivalent. This key is the default one in all selection functions
SKEY_AND 2 the new selection is made on already selected set; this corresponds to logical 'and' of the former and current selections. If no selection preexists, no selection will be made.
SKEY_XOR 3 only those atoms will be selected which are found in either former or newly selected sets, but not in both of them; this corresponds to logical 'exclusive or' of the former and current selections. If no selection preexists, SKEY_XOR, SKEY_OR and SKEY_NEW are equivalent.
SKEY_CLR 4 the atoms, which satisfy the selection criteria, are removed from the selection set. If no selection preexists, no changes occur apart of assigning a selection type (always atom for this function) to the selection handle.

Selection Type
Selection type, uniformly designated as selType below, specifies which objects are affected by the selection operation:
Selection Type Value Description
STYPE_ATOM 1 the selected objects are atoms satisfying the selection criteria
STYPE_RESIDUE 2 the selected objects are residues containing atoms that satisfy the selection criteria
STYPE_CHAIN 3 the selected objects are chains containing atoms that satisfy the selection criteria
STYPE_MODEL 4 the selected objects are models containing atoms that satisfy the selection criteria

Selection List
Many parameters, supplied to selection functions, may represent lists of values, for example, list of chains, list of residues, list of chemical elements etc. A selection list is always given as ASCII string containing comma-separated objects; all spaces in selection lists are ignored. For example, "A,B,C" is a list of chain IDs meaning that the selection operation should be applied to chains A, B and C. Selection list may contain a single asterisk character "*", which means that the selection operation should be applied to all objects of specified type.

Generally, any spaces in selection lists are ignored. This may cause potential problem in the selection on atom names, as PDB atom names contain significant spaces. In most cases this may be cured by specifying also the chemical element name, so that selection on "CA" for atom name and "C" for chemical element name assures that calcium atoms are not selected (selection on just "CA" for atom name would include calcium atoms if there are any in the coordinate hierarchy). In older PDB files, however, chemical element names may be missing or wrong (if ATOM records contain numbering in columns 72-80). If this is the case, significant spaces may be included into selection list by using the square brackets: "[ CA ],N" stands for the selection of C-alphas and nitrogen atoms, while "[CA  ],N" will select calciums and nitrogens (both are examples of atom name selection lists). Although all selection lists support square brackets, their use seems to be reasonable only for atom names. Consider that empty chain ID, insertion code and alternative location indicator correspond to empty items of the corresponding selection lists: the chain selection list ",A,B" (or " ,A,B") will select chains A, B and that without chain ID, while "[ ],A,B" selects only chains A and B.

The action of selection list may be inverted by setting the exclamation mark "!" as its first non-space symbol. For example, "!A,B,C" means that the selection operation should be applied to all chains except A, B and C. Note that selection list "!*" is invalid.

Invalid Selection Handle
If selection handle, given to a selection function, is invalid, the function does nothing. The selection handle may be invalid if
a) it has not been obtained from CMMDBManager::NewSelection
b) the previous selection, identified by this selection handle, was deleted explicitely (through CMMDBManager::DeleteSelection or CMMDBManager::DeleteAllSelections)
c) it has been used for the selection of different type of objects.

Empty Selection
If selection results in empty selection set, the selection handle remains valid, retaining its selection type or obtaining the specified selection type if no selection for that handle preexisted.

It should be kept in mind, that there may be interference between selecting and editing operations on the coordinate hierarchy. E.g., the Library cannot provide for automatical selection of atom which was inserted into selection range after a selection, for which it would qualify, has been done. Similarly, at deleting a selected atom, the Library cannot automatically update the selection index (which may have been passed to the application already).

In this section, only object selection tools are considered. All operations on selected objects are referred to in subject-specific sections.

Function Purpose
CMMDBManager::NewSelection Generating a new selection mask and its handle
CMMDBManager::DeleteSelection Deleting selection by selection handle
CMMDBManager::DeleteAllSelections Deleting all selections in the coordinate hierarchy
CMMDBManager::SelectAtoms Selecting atoms by their serial numbers
CMMDBManager::UnselectAtoms Unselecting atoms by their serial numbers
CMMDBManager::SelectAtoms Selecting atoms by their ID, space restriction and other bits
CMMDBManager::SelectAtoms Selecting atoms by their ID only
CMMDBManager::Select Selecting atoms, residues, chains and models by their ID, space restriction and other bits
CMMDBManager::Select Selecting atoms, residues, chains and models by their ID only.
CMMDBManager::Select Selecting atoms, residues, chains and models by their Coordinate ID.
CMMDBManager::Select Propagating the selection up and down the coordinate hierarchy.
CMMDBManager::SelectSphere Selecting atoms, residues, chains or models in a sphere.
CMMDBManager::SelectCylinder Selecting atoms, residues, chains or models in a cylinder.
CMMDBManager::SelectSlab Selecting atoms, residues, chains or models in a slab.
CMMDBManager::SelectNeighbours Selecting atoms, which are on a given distance from already selected atoms, or other objects containing such atoms.
CMMDBManager::GetSelIndex Obtaining the selection index.
CMMDBManager::GetAtomStatistics Calculating the averaged properties of all atoms in the selection.


int CMMDBManager::NewSelection ( 
 )
PURPOSE
Generating a new selection mask and its handle
DESCRIPTION

The function generates a new, unique, selection mask and returns its handle (the selection handle). The handle is always a positive (non-zero) integer. Calling CMMDBManager::NewSelection() is the only way to create a new selection mask. Notice, however, that the masks will be automatically copied from another coordinate hierarchy (cf. Copying coordinate hierarchies), if atom coordinates are copied; if this is the case, the mask handles will be inherited from the source MMDB as well. The masks and their handles will be automatically deleted from the hierarchy (cf. CMMDBManager::Delete) if all atomic coordinates are deleted.

Immediately after creation of a new selection mask, the type of selection object for that mask is undefined. Therefore the mask may be used for selection of either atoms, residues, chains or models. On the first selection, the mask is assigned a particular selection type (e.g. STYPE_ATOM), which cannot be changed in the future. An attempt to perform any selection operation with unmatching type of selection objects will be silently ignored.


RETURN

The function returns the selection handle.


void CMMDBManager::DeleteSelection ( 
int  selHnd )
PURPOSE
Deleting selection by selection handle
ARGUMENTS
int selHnd
Selection handle.

DESCRIPTION

The function deletes the selection mask, identified by the given selection handle, and removes the corresponding selection attributes from all selection objects that were selected with that mask. If a selection object was selected also with other mask(s), the other selection(s) will be kept.

NOTE 1: After CMMDBManager::DeleteSelection returns, the selection handle becomes invalid. This means that it cannot be used in new selections.

NOTE 2: It is completely harmless to use any integer input to this function. If the supplied argument does not represent a valid selection handle, the function does nothing.


void CMMDBManager::DeleteAllSelections ( 
 )
PURPOSE
Deleting all selections in the coordinate hierarchy
DESCRIPTION

The function deletes all selection mask and unselects all selection objects in the coordinate hierarchy.

NOTE : After CMMDBManager::DeleteAllSelection returns, all selection handles become invalid. This means that they cannot be used in new selections.


void CMMDBManager::SelectAtoms ( 
int  selHnd, 
int iSer1,
int iSer2,
int selKey )
PURPOSE
Selecting atoms by their serial numbers
ARGUMENTS
int selHnd
Selection handle.

int iSer1
Starting serial number

int iSer2
Ending serial number

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

The function selects atoms with serial numbers ranging from iSer1 to iSer2 by adding them to the set of atoms associated with given selection handle. If iSer1=iSer2=0 then all atoms in coordinate hierarchy are selected. Each atom may participate in arbitrary number of selections simultaneously.

The selection is done according to the value of selection key (selKey) given.

NOTE : Serial numbers in a valid PDB file should count from 1 on, incrementing by one, including TER records. In reality this condition often does not hold. The Library differentiates position (index) of an atom, from its serial number. In ideal PDB file, index of atom always coincide with serial number. CMMDBManager::SelectAtoms operates on the serial numbers as they are given in the coordinate file, and not on the atom indices.


void CMMDBManager::UnselectAtoms ( 
int  selHnd, 
int iSer1,
int iSer2 )
PURPOSE
Unselecting atoms by their serial numbers
ARGUMENTS
int selHnd
Selection handle.

int iSer1
Starting serial number

int iSer2
Ending serial number

DESCRIPTION

The function unselects atoms with serial numbers ranging from iSer1 to iSer2, rtemoving them from the set of atoms associated with given selection handle. If iSer1=iSer2=0 then the unselection applies to all atoms in coordinate hierarchy. If selHnd=0, the operation applies to all currently defined selection handles.

NOTE : Serial numbers in a valid PDB file should count from 1 on, incrementing by one, including TER records. In reality this condition often does not hold. The Library differentiates position (index) of an atom, from its serial number. In ideal PDB file, index of atom always coincide with serial number. CMMDBManager::UnselectAtoms operates on the serial numbers as they are given in the coordinate file, and not on the atom indices.


void CMMDBManager::SelectAtoms ( 
int  selHnd, 
int iModel,
pstr Chains,
int ResNo1,
pstr Ins1,
int ResNo2,
pstr Ins2,
pstr RNames,
pstr ANames,
pstr Elements,
pstr altLocs,
pstr Segments,
pstr Charges,
realtype occ1,
realtype occ2,
realtype x0,
realtype y0,
realtype z0,
realtype d0,
int selKey )
PURPOSE
Selecting atoms by their ID, space restriction and other bits
ARGUMENTS
int selHnd
Selection handle.

int iModel
Model number. Model #1 is always present in coordinate hierarchy. iModel=0 means "any model".

pstr Chains
Chain ID or list of chain IDs.

int ResNo1
Starting residue sequence number.

pstr Ins1
Starting residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code".

int ResNo2
Ending residue sequence number.

pstr Ins2
Ending residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code". Combination of ResNo1=ResNo2=ANY_RES and Ins1=Ins2="*" means "any residue".

pstr RNames
Residue name or list of residue names.

pstr ANames
Atom name or list of atom names.

pstr Elements
Chemical element name or list of chemical element names.

pstr altLocs
Alternative location indicator or list of alternative location indicators. No alternative location indicator is specified by empty string "", "*" means 'any alternative location indicator'.

pstr Segments
Segment ID or list of segment IDs.

pstr Charges
Atom charge or list of atom charges.

realtype occ1
Lowest occupancy.

realtype occ2
Highest occupancy. occ1=occ2<0.0 means "any occupancy".

realtype x0
x-center of a selection sphere, in angstroms.

realtype y0
y-center of selection sphere, in angstroms.

realtype z0
z-center of selection sphere, in angstroms.

realtype d0
radius of selection sphere, in angstroms. d0<=0.0 means "no selection sphere" and values of x0, y0 and z0 are ignored.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

The function selects atoms which satisfy all selection criteria given by its arguments. All conditions implied by values of arguments are applied as logical "and" after applying logical "or" to all selection lists.


EXAMPLE

Select all C-alpha atoms in chains A and B:

CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.SelectAtoms (
     selHnd,0,    // any model
     "A,B",       // chains "A" and "B" only
     ANY_RES,"*", // any residue numbers,
     ANY_RES,"*", //    any insertion codes
     "*",         // any residue name
     "CA",        // atoms named "CA" only
     "C",         // carbons only ("CA" might stand for calcium as well)
     "*",         // any alternative location indicator
     "*",         // any segment
     "*",         // any charges
     -1.0,-1.0,   // any occupancy
     0.0,0.0,0.0,-1.0,  // no selection sphere
     SKEY_OR      // OR-selection
                   );


void CMMDBManager::SelectAtoms ( 
int  selHnd, 
int iModel,
pstr Chains,
int ResNo1,
pstr Ins1,
int ResNo2,
pstr Ins2,
pstr RNames,
pstr ANames,
pstr Elements,
pstr altLocs,
int selKey )
PURPOSE
Selecting atoms by their ID only
ARGUMENTS
int selHnd
Selection handle.

int iModel
Model number. Model #1 is always present in coordinate hierarchy. iModel=0 means "any model".

pstr Chains
Chain ID or list of chain IDs.

int ResNo1
Starting residue sequence number.

pstr Ins1
Starting residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code".

int ResNo2
Ending residue sequence number.

pstr Ins2
Ending residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code". Combination of ResNo1=ResNo2=ANY_RES and Ins1=Ins2="*" means "any residue".

pstr RNames
Residue name or list of residue names.

pstr ANames
Atom name or list of atom names.

pstr Elements
Chemical element name or list of chemical element names.

pstr altLocs
Alternative location indicator or list of alternative location indicators. No alternative location indicator is specified by empty string "", "*" means 'any alternative location indicator'.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

The function selects atoms which satisfy all selection criteria given by its arguments. All conditions implied by values of arguments are applied as logical "and" after applying logical "or" to all selection lists.

The function represents a simplified call to the more general CMMDBManager::SelectAtoms. The code
  MMDB.SelectAtoms (
     selHnd,modNo,chainList,res1,insCode1,res2,insCode2,
     residueList,atomList,elementList,alocList,selKey );
is functionally identical to the following one:
  MMDB.SelectAtoms (
     selHnd,modNo,chainList,res1,insCode1,res2,insCode2,
     residueList,atomList,elementList,alocList,
     "*",               // any segment
     "*",               // any charges
     -1.0,-1.0,         // any occupancy
     0.0,0.0,0.0,-1.0,  // no selection sphere
     selKey );


EXAMPLE

Select all C-alpha and nitrogen atoms in GLU and SER residues of chains A and B:

CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.SelectAtoms (
     selHnd,0,    // any model
     "A,B",       // chains "A" and "B" only
     ANY_RES,"*", // any residue numbers,
     ANY_RES,"*", //    any insertion codes
     "GLU,SER",   // GLU and SER residues only
     "CA",        // atoms named "CA" only
     "C",         // carbons only ("CA" might stand for calcium as well)
     "*",         // any alternative location indicator
     SKEY_NEW     // NEW-selection
                   );
  MMDB.SelectAtoms (
     selHnd,0,    // any model
     "A,B",       // chains "A" and "B" only
     ANY_RES,"*", // any residue numbers,
     ANY_RES,"*", //    any insertion codes
     "GLU,SER",   // GLU and SER residues only
     "*",         // any atom names
     "N",         // nitrogens only
     "*",         // any alternative location indicator
     SKEY_OR      // OR-selection
                   );


void CMMDBManager::Select ( 
int  selHnd, 
int selType,
int iModel,
pstr Chains,
int ResNo1,
pstr Ins1,
int ResNo2,
pstr Ins2,
pstr RNames,
pstr ANames,
pstr Elements,
pstr altLocs,
pstr Segments,
pstr Charges,
realtype occ1,
realtype occ2,
realtype x0,
realtype y0,
realtype z0,
realtype d0,
int selKey )
PURPOSE
Selecting atoms, residues, chains and models by their ID, space restriction and other bits
ARGUMENTS
int selHnd
Selection handle.

int selType
Selection type.

int iModel
Model number. Model #1 is always present in coordinate hierarchy. iModel=0 means "any model".

pstr Chains
Chain ID or list of chain IDs.

int ResNo1
Starting residue sequence number.

pstr Ins1
Starting residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code".

int ResNo2
Ending residue sequence number.

pstr Ins2
Ending residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code". Combination of ResNo1=ResNo2=ANY_RES and Ins1=Ins2="*" means "any residue".

pstr RNames
Residue name or list of residue names.

pstr ANames
Atom name or list of atom names.

pstr Elements
Chemical element name or list of chemical element names.

pstr altLocs
Alternative location indicator or list of alternative location indicators. No alternative location indicator is specified by empty string "", "*" means 'any alternative location indicator'.

pstr Segments
Segment ID or list of segment IDs.

pstr Charges
Atom charge or list of atom charges.

realtype occ1
Lowest occupancy.

realtype occ2
Highest occupancy. occ1=occ2<0.0 means "any occupancy".

realtype x0
x-center of a selection sphere, in angstroms.

realtype y0
y-center of selection sphere, in angstroms.

realtype z0
z-center of selection sphere, in angstroms.

realtype d0
radius of selection sphere, in angstroms. d0<=0.0 means "no selection sphere" and values of x0, y0 and z0 are ignored.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects either atoms satisfying all selection criteria, given by its arguments, or other objects (residues, chains or models), which contain such atoms. All conditions implied by values of arguments are applied as logical "and" after applying logical "or" to all selection lists. The selection operation is given by the value of selKey.

The following code
  MMDB.Select ( selHnd, STYPE_ATOM, .... );
is equivalent to (cf. CMMDBManager::SelectAtoms)
  MMDB.SelectAtoms ( selHnd, .... );
provided that the rest of parameters is identical in both examples.


EXAMPLE

Select all residues in chains A and B, which are not SER or GLU and which contain at least one non-hydrogen, non-oxygen atom falling into a sphere of a given radius:

CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.Select (
     selHnd,
     STYPE_RESIDUE, // select residues
     0,             // any model
     "A,B",         // chains "A" and "B" only
     ANY_RES,"*",   // any residue numbers,
     ANY_RES,"*",   //    any insertion codes
     "!SER,GLU",    // any residue but SER and GLU
     "*",           // any atom
     "!H,O",        // any chemical element but O and H
     "*",           // any alternative location indicator
     "*",           // any segment
     "*",           // any charges
     -1.0,-1.0,     // any occupancy
     1.0,2.0,3.0,   // (x,y,z) center of the sphere
     10.0,          // radius of the sphere
     SKEY_OR        // OR-selection
                   );


void CMMDBManager::Select ( 
int  selHnd, 
int selType,
int iModel,
pstr Chains,
int ResNo1,
pstr Ins1,
int ResNo2,
pstr Ins2,
pstr RNames,
pstr ANames,
pstr Elements,
pstr altLocs,
int selKey )
PURPOSE
Selecting atoms, residues, chains and models by their ID only.
ARGUMENTS
int selHnd
Selection handle.

int selType
Selection type.

int iModel
Model number. Model #1 is always present in coordinate hierarchy. iModel=0 means "any model".

pstr Chains
Chain ID or list of chain IDs.

int ResNo1
Starting residue sequence number.

pstr Ins1
Starting residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code".

int ResNo2
Ending residue sequence number.

pstr Ins2
Ending residue insertion code. Ins1="" means "residue without insertion code, Ins1="*" means "any insertion code". Combination of ResNo1=ResNo2=ANY_RES and Ins1=Ins2="*" means "any residue".

pstr RNames
Residue name or list of residue names.

pstr ANames
Atom name or list of atom names.

pstr Elements
Chemical element name or list of chemical element names.

pstr altLocs
Alternative location indicator or list of alternative location indicators. No alternative location indicator is specified by empty string "", "*" means 'any alternative location indicator'.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects either atoms satisfying all selection criteria, given by its arguments, or other objects (residues, chains or models), containing such atoms. All conditions implied by values of arguments are applied as logical "and" after applying logical "or" to all selection lists. The selection operation is given by the value of selKey.

The function is a simplified version of a more general CMMDBManager::Select. The code
  MMDB.Select (
     selHnd,selType,modNo,chainList,res1,insCode1,res2,insCode2,
     residueList,atomList,elementList,alocList,selKey );
is functionally identical to the following one:
  MMDB.Select (
     selHnd,selType,modNo,chainList,res1,insCode1,res2,insCode2,
     residueList,atomList,elementList,alocList,
     "*",               // any segment
     "*",               // any charges
     -1.0,-1.0,         // any occupancy
     0.0,0.0,0.0,-1.0,  // no selection sphere
     selKey );


EXAMPLE

Select all residues in range 30 to 100 in chains A and B, which do not contain sulphur:

CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.Select (
     selHnd,
     STYPE_RESIDUE,  // select residues
     0,              // any model
     "A,B",          // chains "A" and "B" only
     30,"*",100,"*", // any residue in range 30 to 100,
                     // any insertion code
     "*",            // any residue name
     "*",            // any atom name
     "!S",           // any chemical element but sulphur
     "*",            // any alternative location indicator
     SKEY_OR         // OR-selection
              );


void CMMDBManager::Select ( 
int  selHnd, 
int selType,
pstr CID,
int selKey )
PURPOSE
Selecting atoms, residues, chains and models by their Coordinate ID.
ARGUMENTS
int selHnd
Selection handle.

int selType
Selection type.

pstr CID
The selection coordinate ID.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects either atoms satisfying the provided coordinate ID, or other objects (residues, chains or models), containing such atoms. The selection operation is given by the value of selKey.

The selection coordinate ID has generally the same syntax as the "ordinary" CID, however there are the following important extensions:
  1. Specifications for chains, residue names, atom names, chemical elements and alternative location indicators may represent lists rather than single values. These lists should contain comma-separated items, for example "A,B,H" for selecting chains A, B and H only. If a list is preceeded by an exclamation mark "!", its meaining gets inversed. For example, "!ALA,SER" means 'any residue name but ALA and SER'.

  2. A range (but not a list) of residue sequence numbers and insertion codes may be specified in the following form:

    "seq1.ic1-seq2.ic2"

    where seq1, seq2 stand for the sequence numbers, and ic1, ic2 - for the insertion codes. A yet more complicated form of this range is

    "seq1.ic1-seq2(reslist).ic2"

    where reslist is a list of (comma-separated, optionally "!"-prefixed) residue names to be only selected in the specified range.

  3. Default items and incomplete selection CIDs are interpreted in exactly the same way as in "ordinary" CID.

  4. All spaces are ignored.

  5. All names are case-sensitive.

The following examples represent valid selection CIDs:

Coordinate ID Description
* all atoms in all models/chains/residues
[C] all carbons in all models/chains/residues
/1///:A all atoms in alternate location A in all residues of chain without a chain ID, in model 1
/1/*/*/*:A same as above
30-120 all atoms in residues 30 to 120 in all models and chains.
A/30.A-120.S all atoms in residues 30 insertion code A to 120 insertion code S in A-chains of all models.
A/30.A-120.S/[!S] all atoms but sulphur in residues 30 insertion code A to 120 insertion code S in A-chains of all models.
(ALA,SER) all atoms in residues ALA and SER in all models/chains.
/1/A/(!ALA,SER)/CA[C] all C-alpha atoms in all residues but ALA and SER in model 1 chain A.


EXAMPLE

The following codes perform identical actions.

Code 1:
CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.Select (
     selHnd,
     STYPE_ATOM,                             // select atoms
     "/0/A,B/30.A-100(!ALA,SER)./*[C,O,N]:", // full precise CID
     SKEY_OR                                 // OR-selection
              );
  //
  // Equivalent selection CIDs:
  //  "/*/A,B/30.A-100(!ALA,SER)./*[C,O,N]:"
  //
  // incomplete equivalent selection CIDs:
  //  "A,B/30.A-100(!ALA,SER)./*[C,O,N]:"
  //  "A,B/30.A-100(!ALA,SER)/*[C,O,N]:"
  //  "A,B/30.A-100(!ALA,SER)/[C,O,N]"
  //

Code 2:
CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.Select (
     selHnd,
     STYPE_ATOM,     // select atoms
     0,              // any model
     "A,B",          // chains "A" and "B" only
     30,"A",100,"",  // any residue in range 30.A to 100.
     "!ALA,SER",     // any residue name but ALA and SER
     "*",            // any atom name
     "C,O,N",        // carbons, oxygens and nitrogens only
     "",             // no alternate location
     SKEY_OR         // OR-selection
              );


void CMMDBManager::Select ( 
int  selHnd1, 
int selType,
int selHnd2,
int selKey )
PURPOSE
Propagating the selection up and down the coordinate hierarchy.
ARGUMENTS
int selHnd1
Selection handle for the "destination" selection.

int selType
Selection type for the "destination" selection.

int selHnd2
Selection handle for the "source" selection.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects objects (atoms, residues, chains or models), which are contained in objects belonging to selection selHnd2, or which contain such objects. The selection operation is given by the value of selKey.


EXAMPLE 1

Select all residues, which contain selected atoms:

CMMDBManager MMDB;
int          RC,selHnd_a,selHnd_r;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd_a = MMDB.NewSelection();
  MMDB.Select (
     selHnd_a,       // atom selection handle
     STYPE_ATOM,     // select atoms
     0,              // any model
     "A,B",          // chains "A" and "B" only
     30,"*",100,"*", // any residue in range 30 to 100
     "*",            // any residue name
     "*",            // any atom name
     "*",            // any chemical element
     "*",            // any alternative location indicator
     SKEY_NEW        // NEW-selection
              );
  selHnd_r = MMDB.NewSelection();
  MMDB.Select (
     selHnd_r,       // residue selection handle
     STYPE_RESIDUE,  // select residues
     selHnd_a,       // reference to selected atoms
     SKEY_OR         // OR-selection
              );


EXAMPLE 2

Select all atoms, which are contained in selected residues:

CMMDBManager MMDB;
int          RC,selHnd_a,selHdn_r;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd_r = MMDB.NewSelection();
  MMDB.Select (
     selHnd_r,       // atom selection handle
     STYPE_RESIDUE,  // select residues
     0,              // any model
     "A,B",          // chains "A" and "B" only
     30,"*",100,"*", // any residue in range 30 to 100
     "*",            // any residue name
     "*",            // any atom name
     "*",            // any chemical element
     "*",            // any alternative location indicator
     SKEY_NEW        // NEW-selection
              );
  selHnd_a = MMDB.NewSelection();
  MMDB.Select (
     selHnd_a,       // residue selection handle
     STYPE_ATOM,     // select atoms
     selHnd_r,       // reference to selected atoms
     SKEY_OR         // OR-selection
              );


void CMMDBManager::SelectSphere ( 
int  selHnd, 
int selType,
realtype x,
realtype y,
realtype z,
realtype r,
int selKey )
PURPOSE
Selecting atoms, residues, chains or models in a sphere.
ARGUMENTS
int selHnd
Selection handle.

int selType
Selection type.

realtype x
x-coordinate of the center of the sphere.

realtype y
y-coordinate of the center of the sphere.

realtype z
z-coordinate of the center of the sphere.

realtype r
radius of the sphere.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects either atoms found inside the specified sphere, or other objects (residues, chains or models), containing such atoms. The selection operation is given by the value of selKey.


EXAMPLE

Select all residues in chains A and B, which contain at least one atom in the specified sphere:

CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.SelectSphere (
     selHnd,
     STYPE_RESIDUE,  // select residues
     1.0,2.0,3.0,    // (x,y,z)-center of the sphere
     10.0,           // radius of the sphere
     SKEY_NEW        // NEW-selection
                    );


void CMMDBManager::SelectCylinder ( 
int  selHnd, 
int selType,
realtype x1,
realtype y1,
realtype z1,
realtype x2,
realtype y2,
realtype z2,
realtype r,
int selKey )
PURPOSE
Selecting atoms, residues, chains or models in a cylinder.
ARGUMENTS
int selHnd
Selection handle.

int selType
Selection type.

realtype x1
x1-coordinate of the cylinder's axis.

realtype y1
y1-coordinate of the cylinder's axis.

realtype z1
z1-coordinate of the cylinder's axis.

realtype x2
x2-coordinate of the cylinder's axis.

realtype y2
y2-coordinate of the cylinder's axis.

realtype z2
z2-coordinate of the cylinder's axis.

realtype r
radius of the cylinder.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects either atoms found inside the specified cylinder, or other objects (residues, chains or models), containing such atoms. The selection operation is given by the value of selKey.

The cylinder is specified as that of radius r with axis running from point {x1,y1,z1} to point {x2,y2,z2}.


EXAMPLE

Select all atoms in chains A and B, which contain at least one atom in the specified cylinder:

CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.SelectCylinder (
     selHnd,
     STYPE_ATOM,   // select atoms
     1.0,0.0,0.0,  // {x1,y1,z1}-point of the cylinder's axis
     10.0,0.0,0.0, // {x2,y2,z2}-point of the cylinder's axis
     10.0,         // radius of the cylinder
     SKEY_NEW      // NEW-selection
                    );


void CMMDBManager::SelectSlab ( 
int  selHnd, 
int selType,
realtype a,
realtype b,
realtype c,
realtype d,
realtype r,
int selKey )
PURPOSE
Selecting atoms, residues, chains or models in a slab.
ARGUMENTS
int selHnd
Selection handle.

int selType
Selection type.

realtype a
a-parameter of the slab's plane.

realtype b
b-parameter of the slab's plane.

realtype c
c-parameter of the slab's plane.

realtype d
d-parameter of the slab's plane.

realtype r
r distance to the slab's plane.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects either atoms found inside the specified slab, or other objects (residues, chains or models), containing such atoms. The selection operation is given by the value of selKey.

The slab is defined as set of all points on a distance not greater than r from the slab's plane. The plane is defined as set of points that obey the equation a*x + b*y + c*z = d.


EXAMPLE

Select all chains, which contain at least one atom with x-coordinate in the region of -20 to -10 angstroms:

CMMDBManager MMDB;
int          RC,selHnd;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.SelectSlab (
     selHnd,
     STYPE_CHAIN,       // select chains
     1.0,0.0,0.0,-15.0, // slab's plane equation x=-15
     5.0,               // +/- 5 angstroms from the slab's plane
     SKEY_NEW           // NEW-selection
                  );


void CMMDBManager::SelectNeighbours ( 
int  selHnd, 
int selType,
PPCAtom sA,
int alen,
realtype d1,
realtype d1,
int selKey )
PURPOSE
Selecting atoms, which are on a given distance from already selected atoms, or other objects containing such atoms.
ARGUMENTS
int selHnd
Selection handle.

int selType
Selection type.

PPCAtom sA
vector of selected atoms (may be obtained from CMMDBManager::GetSelIndex).

int alen
length of array sA.

realtype d1
minimal distance to atoms in sA.

realtype d1
maximal distance to atoms in sA.

int selKey
Selection key. This parameter has default value of SKEY_OR.

DESCRIPTION

Depending on the value of selType, the function selects either atoms that are on distance d1<=r<=d2 from at least one atom in array sA, or other objects (residues, chains or models), containing such atoms. The selection operation is given by the value of selKey.

The function employs the bricking algorithm and is therefore considerably more efficient than straightforward checking the selection criteria for every atom in sA and in the coordinate hierarchy.


EXAMPLE

Select all residues, which contain at least one atom closer than 10 angstrom to C-alpha atoms of chain A:

CMMDBManager MMDB;
PPCAtom      SelAtom;
int          RC,selHnd,nSelAtoms;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.Select (
     selHnd,      // selection handle
     STYPE_ATOM,  // select atoms
     0,           // any model
     "A",         // chains "A" and "B" only
     ANY_RES,"*", // any residue
     ANY_RES,"*", //   any insertion code
     "*",         // any residue name
     "CA",        // C-alphas only
     "C",         // carbons only
     "*",         // any alternative location indicator
     SKEY_NEW     // NEW-selection
              );
  MMDB.GetSelIndex ( selHnd,SelAtom,nSelAtoms );
  MMDB.SelectNeighbours (
     selHnd,        // selection handle
     STYPE_RESIDUE, // select residues
     SelAtom,       // array of already selected atoms
     nSelAtoms,     // number of already selected atoms
     0.0,10.0,      // distance range 0 to 10 angstroms
     SKEY_OR        // OR-selection
                        );


void CMMDBManager::GetSelIndex ( 
int  selHnd, 
PPCObject SelObject,
int nSelObjects )
PURPOSE
Obtaining the selection index.
ARGUMENTS
int selHnd
Selection handle.

PPCObject SelObject
Pointer to the array of objects to receive the index. Overloaded instances of this function work with selected atoms, residues, chains and models, for which this parameter should have type of either PPCAtom, PPCResidue, PPCChain or PPCModel, correspondingly.

int nSelObjects
Length of index. The selected objects are addressed as SelObject[i], i=[0..nSelObjects-1].

DESCRIPTION

Depending on the type of selObject, the function returns the continuous-space indices of selected atoms, residues, chains or models, associated with the selection handle selHnd. The type of requested selection should coincide with what was actually selected for that handle. If this condition does not hold, or if the selection set is empty, the function returns SelObject=NULL and nSelObjects=0.

NOTE 1: The selection index is dynamically allocated and deallocated by the Manager. The application must not attempt to either dispose or reallocate the selection index.

NOTE 2: The application may delete objects from the index. Using ordinary delete operator will make a proper deletion of an object (i.e. it will be disposed and removed from the coordinate hierarchy), e.g. "delete SelObject[i]". However, and this is very important, the application must null the pointer of the object: "SelObject[i] = NULL" immediately after deletion.

NOTE 3: After the selection index has been passed to the application, it cannot be updated by the Manager if, for example, new selections for that selection handle are done. It should therefore be a common practice for application to be obtaining the selection indices immediately prior using them, making sure that those are the latest ones. Obtaining the selection index is very cheap; it invokes neither calculations nor compilation of the index.


EXAMPLE

Select all residues in chain A and obtain their index:

CMMDBManager MMDB;
PPCResidue   SelResidue;
int          RC,selHnd,nSelResidues;
  RC = MMDB.ReadCoorFile ( CoorFileName );
  if (RC)  {
    // interprete the error code
    ........................
    exit ( 1 );
  }
  selHnd = MMDB.NewSelection();
  MMDB.Select (
     selHnd,        // selection handle
     STYPE_RESIDUE, // select residues
     0,             // any model
     "A",           // chains "A" and "B" only
     ANY_RES,"*",   // any residue
     ANY_RES,"*",   //   any insertion code
     "*",           // any residue name
     "*",           // any atom names
     "*",           // any chemical elements
     "*",           // any alternative location indicator
     SKEY_NEW       // NEW-selection
              );
  MMDB.GetSelIndex ( selHnd,SelResidue,nSelResidues );
See also an example for function CMMDBManager::SelectNeighbours.


void CMMDBManager::GetAtomStatistics ( 
int  selHnd, 
RSAtomStat AS )
PURPOSE
Calculating the averaged properties of all atoms in the selection.
ARGUMENTS
int selHnd
Selection handle.

RSAtomStat AS
Reference to structure SAtomStat , which returns the average results.

DESCRIPTION

The function calculates the average properties of atoms regardless of the selection type. If, e.g., selHnd is associated with selected chains, the properties of all atoms belonging to those chains will be averaged.

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.



Back to index