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 DEFINITIONSSelection 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 | 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 |
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 ( |
) |
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.The function returns the selection handle.
void CMMDBManager::DeleteSelection ( |
int selHnd ) |
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 ( |
) |
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, |
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, |
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, |
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.
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, |
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 codeMMDB.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 );
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, |
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 codeMMDB.Select ( selHnd, STYPE_ATOM, .... );is equivalent to (cf. CMMDBManager::SelectAtoms)
MMDB.SelectAtoms ( selHnd, .... );provided that the rest of parameters is identical in both examples.
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, |
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 codeMMDB.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 );
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, |
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: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. |
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, |
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.
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
);
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, |
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.
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, |
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}.
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, |
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.
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, |
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.
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, |
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.
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, |
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.