Select#

Selecting elements from a molecular system

Element selection is probably one of the most frequent tasks when working with molecular systems. There are many circumstances under which we need to know lists of elements meeting certain conditions. We probably need, for instance, to calculate de contact map between CA atoms from two chains, or to remove the solvent atoms, or to know how many ‘HIS’ residues there are in a protein. All these conditions can be expressed as a query sentence the elements of the system needs to match. Each library to work with molecular systems has its own syntax you have to follow to write these query sentences. See for instance different examples in the tools MDTraj, PyTraj, MDAnalysis, NGLView.

The basic module of MolSysMT includes the function molsysmt.basic.select() to perform elements selection on molecular systems with a native syntax or making use of other supported supported syntaxes.

Added in version 1.0.0.

MolSysMT selection syntax#

Although you can use the function molsysmt.basic.select() with some of your preferred syntaxes (see User guide > Introduction > Selection syntaxes), MolSysMT has its own selection syntax based on the names of the attributes of the elements as atoms, groups, molecules, etc. These are the “words” allowed for the elements attributes to be include in the query strings:

Word	Attribute
“atom_index”	atom_index
“atom_name”	atom_name
“atom_id”	atom_id
“atom_type”	atom_type
“group_index”	group_index
“group_name”	group_name
“group_id”	group_id
“group_type”	group_type
“component_index”	component_index
“component_name”	component_name
“component_id”	component_id
“component_type”	component_type
“chain_index”	chain_index
“chain_name”	chain_name
“chain_id”	chain_id
“chain_type”	chain_type
“molecule_index”	molecule_index
“molecule_name”	molecule_name
“molecule_id”	molecule_id
“molecule_type”	molecule_type
“entity_index”	entity_index
“entity_name”	entity_name
“entity_id”	entity_id
“entity_type”	entity_type
“occupancy”	occupancy
“alternate_location”	alternate_location
“b_factor”	b_factor
“formal_charge”	formal_charge
“partial_charge”	partial_charge

The plural forms of the former words are also accepted. For example:

Word	Equivalent
“atom_indices”	“atom_index”
“component_names”	“component_name”
“occupancies”	“occupancy”
“formal_charges”	“formal_charge”

The boolean syntax MolSysMT accepts includes the following words and symbols:

Word	Symbol	Meaning
“and”	&	and
“or”	\|	or
“not”	~	not
“in”		in
	==	equal
	!=	not equal
	<	less than
	<=	less or equal than
	>	greater than
	>=	greater or equal than

MolSysMT includes in its native selection syntax some other query restrictions involving spatial coordinates and bonds:

Words	Meaning
“within … of”	Elements are selected if they are at a certain distance of other elements
“not within … of”	Elements are selected if they not are at a certain distance of other elements
“within … with pbc of”	Elements are selected if they are at a certain distance of other elements with periodic boundary conditions
“within … without pbc of”	Elements are selected if they are at a certain distance of other elements without periodic boundary conditions

Words	Meaning
“bonded to”	Elements are selected if they are bonded to other elements
“not bonded to”	Elements are selected if they are not bonded to other elements

Finally, lists of elements can be queried with the help of the following expressions:

Words	Meaning
“in groups of”	Elements are selected and returned in lists corresponding to different groups
“in components of”	Elements are selected and returned in lists corresponding to different components
“in molecules of”	Elements are selected and returned in lists corresponding to different molecules
“in chains of”	Elements are selected and returned in lists corresponding to different chains
“in entities of”	Elements are selected and returned in lists corresponding to different entities

Native selection shortcuts#

In addition to the former words and symbols, the native MolSysMT selection syntax includes some shortcuts:

Word	Equivalent
“all”	Any element in the system where element is given by the input argument `element`
“index” or “indices”	“element_index” where element is given by the input argument `element`
“id” or “ids”	“element_id” where element is given by the input argument `element`
“name” or “names”	“element_name” where element is given by the input argument `element`
“type” or “types”	“element_type” where element is given by the input argument `element`

Word	Equivalent
“backbone”	“atom_name in [‘CA’, ‘N’, ‘C’, ‘O’]”
“hydrogen” or “hydrogens”	“atom_type==’H’”

Your own selection shortcuts#

You can customize the selection experience with your own selection shortcuts. Have a look to the section User guide > Introduction > Configuration options

How this function works#

API documentation

Follow this link for a detailed description of the input arguments, raised errors, and returned objects of this function:molsysmt.basic.select().

Let’s explore how molsysmt.basic.select() works using its native selection syntax. The following are some examples where a list of atoms is obtained matching some selection criteria based on atoms attributes:

import molsysmt as msm

molsys = msm.convert('1TCD')

[1, 4, 10, 13, 17]

Tip

All functions defined in the molsysmt.basic module can be invoked also from the main level of the library. Hence, molsysmt.select() is the same function as molsysmt.basic.select().

# Heavy atoms
msm.select(molsys, 'not atom_type=="H"')

Tip

By default, the input argument element takes the value “atom” in molsysmt.basic.select().

The selection argument accepts also lists of indices, which are always intepreted as element indices.

msm.select(molsys, element='atom', selection=[0,1,2])

[0, 1, 2]

Some examples of atoms selections#

Let’s show here some examples of atoms selections using the MolSysMT native syntax.

# Atoms of type C not named CA
msm.select(molsys, 'atom_type=="C" and not atom_name=="CA"')

# Atoms not named CA, CB or C
msm.select(molsys, 'atom_name!=["CA","CB","C"]')

Atoms can be selected using attributes of other elements within the molecular system’s hierarchical structure: ‘group’, ‘component’, ‘molecule’, ‘chain’, ‘entity’. You can find further information of these elements in User guide > Introduction > Molecular system > Elements. These are some examples of selection sentences including other criteria than atoms attributes:

# Atoms belonging to molecules of type water.
msm.select(molsys, 'molecule_type=="water"')

# Heavy atoms belonging to molecules of type protein.
msm.select(molsys, 'molecule_type=="protein" and atom_type!="H" and group_index==3')

[25, 26, 27, 28, 29, 30, 31]

# Atoms belonging to residues named GLY, ALA or VAL in chain id A.
msm.select(molsys, 'group_name==["GLY","ALA","VAL"] and chain_name=="A"')

Remember that when selection takes a list of integers as value, this is always intepreted as a list of element indices -atoms in this case-:

msm.select(molsys, selection=[10,11,12,13])

[10, 11, 12, 13]

Some examples of other elements selections#

The selection method of MolSysMT can also return other elements indices than atoms. As many functions in MolSysMT, molsysmt.basic.select() has an input argument named element to select the elements to which the function operates. Let’s see some examples:

# Groups with name "ALA"
msm.select(molsys,  element='group', selection='group_name=="ALA"')

# Groups of atoms index 34, 44 or 64
msm.select(molsys, element='group', selection='atom_index==[34,44,64]')

[4, 5, 9]

# Groups belonging to chain id A or C and molecule of type anything but water
msm.select(molsys, element='group', selection='chain_name in ["A", "C"] and molecule_type!="water"')

# Molecules of type water
msm.select(molsys, 'molecule_type=="water"', element='molecule')

# Chains with molecules of type water
msm.select(molsys, 'molecule_type=="water"', element='chain')

[2, 3]

# Bonds in group index 5
msm.select(molsys, 'group_index==5', element='bond')

[42, 43, 44, 45]

When selection takes a list of integers as value, this is always intepreted as a list of elements indices:

msm.select(molsys, element='group', selection=[0,1,2,3,4,5,6,7,8,9,10,11])

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]

msm.select(molsys, element='molecule', selection=[3900, 3910, 3920])

[3900, 3910, 3920]

Including external variables in the selection sentence#

Pandas query method allows the use of external variables in the logical sentence. To include them, variables names have to be preceded by the character ‘@’. Let’s illustrate its use with some examples:

# Atoms in groups with indices 10, 11 or 12.
indices = [10,11,12]
msm.select(molsys, 'group_index==@indices')

[77,
 78,
 79,
 80,
 81,
 82,
 83,
 84,
 85,
 86,
 87,
 88,
 89,
 90,
 91,
 92,
 93,
 94,
 95,
 96,
 97,
 98,
 99]

# Atoms named CA, C, O or N in groups with indices 10 to 29.
indices = list(range(10,30))
atoms = ["CA", "C", "O", "N"]
msm.select(molsys, 'atom_name==@atoms & atom_index==@indices')

[10, 11, 12, 16, 17, 18, 19, 25, 26, 27, 28]

# Groups with indices equal to 0, 100 or 200
indices = [0,100,200]
msm.select(molsys, element='group', selection='group_index==@indices')

[0, 100, 200]

Selecting elements “within a distance of”#

A selection of elements within a certain distance of a set of elements can be obtained using the string within ... of. Here you can find some examples:

msm.select(molsys, 'chain_name=="A" within 0.3 nm of chain_name=="B"')

msm.select(molsys, '(atom_name=="N" and chain_name=="A") within 3 angstroms of (atom_type=="O" and molecule_type=="water")')

[119, 213, 473, 531, 654, 696, 799, 1049]

msm.select(molsys, '(atom_name=="CA" and chain_name=="A") within 0.5 nm of (atom_name=="CA" and chain_name=="B")',
          element='group')

[10, 42, 62, 72, 73]

The string “not within … of …” can also be used:

msm.select(molsys, 'chain_name=="A" not within 7.8 nanometers of chain_name=="B"')

[1521, 1522, 1723, 1724, 3882]

And distances can be interpreted with or without periodic boundary conditions:

msm.select(molsys, 'chain_name=="A" within 0.3 nm without pbc of chain_name=="B"')

msm.select(molsys, 'chain_name=="A" within 0.3 nm with pbc of chain_name=="B"')

Selecting atoms “bonded to …”#

Atoms bonded to specific atoms can also be selected with bonded to:

msm.select(molsys, 'atom_name=="N" bonded to atom_type=="C"')

msm.select(molsys, '(atom_type=="O" and chain_name=="A") bonded to (atom_type=="C" and chain_name=="A")')

The string “not bonded to” can also be used:

msm.select(molsys, '(all not bonded to atom_type==["H","N","C","O"]) and molecule_type=="protein"')

[363, 1714, 2275, 3626]

And both, within .. of and bonded to, can be mixed in the same selection sentence:

msm.select(molsys, '((atom_name=="N" and chain_name=="A") bonded to atom_type=="C") within 3 angstroms of (atom_type=="O" and molecule_type=="water")')

[119, 213, 473, 531, 654, 696, 799, 1049]

Selecting elements “in elements of …”#

The function molsysmt.basic.select() does not only return single lists of elements. This tool can also be used to find a list of elements lists fulfilling a query condition with the assistance of the strings: groups of, components of, molecules of, chains of or entities of. Let’s see a couple of examples to understand how this option works.

Let’s first of all get the lists of atoms belonging to the groups of molecule index 0 named ‘CYS’:

msm.select(molsys, 'all in groups of molecule_index==0 and group_name=="CYS"')

[[86, 87, 88, 89, 90, 91],
 [273, 274, 275, 276, 277, 278],
 [880, 881, 882, 883, 884, 885],
 [943, 944, 945, 946, 947, 948]]

We can now narrow the search to only carbon atoms:

msm.select(molsys, 'atom_type=="C" in groups of molecule_index==0 and group_name=="CYS"')

[[87, 88, 90], [274, 275, 277], [881, 882, 884], [944, 945, 947]]

Let’s show how other elements lists can be queried like groups for instance:

msm.select(molsys, element='group',
           selection='group_name=="ALA" in components of molecule_name=="TRIOSEPHOSPHATE ISOMERASE"')

msm.select(molsys, element='molecule',
           selection='entity_name=="water" in chains of chain_name==["A","B"]')

The logic behind “… in elements of …” can be used redundantly. Check the following example:

msm.select(molsys, 'all in groups of group_name=="CYS" in components of component_index==[0,1]')

[[[86, 87, 88, 89, 90, 91],
  [273, 274, 275, 276, 277, 278],
  [880, 881, 882, 883, 884, 885],
  [943, 944, 945, 946, 947, 948]],
 [[1998, 1999, 2000, 2001, 2002, 2003],
  [2185, 2186, 2187, 2188, 2189, 2190],
  [2792, 2793, 2794, 2795, 2796, 2797],
  [2855, 2856, 2857, 2858, 2859, 2860]]]

The output in this last case is a list of lists of lists of atoms. More precisely, in the former example, the output corresponds to the list of atom indices of the list of CYS groups reported in two lists, those belonging to the component with index 0 and those to the component 1.

Finally, the lack of all or of all is allowed. It can be checked that the following four selections are equivalent:

sel1 = msm.select(molsys, 'all in groups of all in components of all')
sel2 = msm.select(molsys, 'all in groups of all in components')
sel3 = msm.select(molsys, 'all in groups in components of all')
sel4 = msm.select(molsys, 'all in groups in components')
sel5 = msm.select(molsys, 'in groups in components')

equal = True
for component1, component3 in zip(sel1, sel3):
    for group1, group3 in zip(component1, component3):
        for atom1, atom3 in zip(group1, group3):
            if atom1!=atom3:
                equal = False
                break

print(f'Are "sel1" and "sel3" equivalent selections?: {equal}')

equal = True
for component3, component5 in zip(sel3, sel5):
    for group3, group5 in zip(component3, component5):
        for atom3, atom5 in zip(group3, group5):
            if atom3!=atom5:
                equal = False
                break

print(f'Are "sel3" and "sel5" equivalent selections?: {equal}')

Are "sel1" and "sel3" equivalent selections?: True
Are "sel3" and "sel5" equivalent selections?: True

Multiple selections#

With molsysmt.basic.select() multiple selections can be done at once. The input argument selection admits lists of selections:

msm.select(molsys, ['group_name=="HIS" and atom_name=="CA"',
                    'group_name=="THR" and atom_name=="CA"',
                    'group_name=="TRP" and atom_name=="CA"'])

[[240, 332, 701, 912, 1401, 2152, 2244, 2613, 2824, 3313],
 [181,
  214,
  306,
  365,
  405,
  504,
  548,
  793,
  970,
  1043,
  1082,
  1307,
  1339,
  1517,
  1627,
  1672,
  1890,
  2093,
  2126,
  2218,
  2277,
  2317,
  2416,
  2460,
  2705,
  2882,
  2955,
  2994,
  3219,
  3251,
  3429,
  3539,
  3584,
  3802],
 [64, 661, 1183, 1276, 1458, 1976, 2573, 3095, 3188, 3370]]

Every selection included in the input list of selections works as described in these sections:

group_indices=[10,11,12]
msm.select(molsys, ['group_name=="HIS" and atom_name=="CA"',
                    'atom_type=="C" and group_index==@group_indices',
                     3,
                    [4,5,6]])

[[240, 332, 701, 912, 1401, 2152, 2244, 2613, 2824, 3313],
 [78, 79, 81, 82, 83, 84, 87, 88, 90, 93, 94, 96, 97],
 [3],
 [4, 5, 6]]

Other syntaxes supported#

There is no need for the user to learn the native syntax. Other syntaxes such as the used by MDTraj is also supported by MolSysMT:

msm.select(molsys, selection='(name =~ "C[A-B]") and (resid 1 to 3)', syntax='MDTraj')

array([10, 13, 17, 20, 26, 29])

Translation between different syntaxes#

MolSysMT aims to simplify interoperability with other libraries. Since each one uses a different selection syntax, MolSysMT allows converting queries to other syntaxes using the to_syntax argument. Lets illustrate some examples:

msm.select(molsys, selection='group_index==[3,4,5]', to_syntax='NGLView')

'@25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44'

msm.select(molsys, selection='group_index==[3,4,5]', to_syntax='MDTraj')

'index 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44'

The output string can be obtained, if the selection is done over other elementted elements, as a sequence of groups or chains:

msm.select(molsys, element='group', selection='group_index==[3,4,5]', to_syntax='NGLView')

'7:A 8:A 9:A'

msm.select(molsys, element='group', selection='group_index==[3,4,5]', to_syntax='MDTraj')

'resid 3 4 5'