docs/reference-manual/analysis/using-groups.rst

   1 .. _usinggroups:
   2
   3 Using Groups
   4 ------------
   5
   6 | In chapter :ref:`algorithms`, it was explained how *groups of atoms* can
   7   be used in :ref:`mdrun <gmx mdrun>` (see sec. :ref:`groupconcept`). In most analysis
   8   programs, groups of atoms must also be chosen. Most programs can
   9   generate several default index groups, but groups can always be read
  10   from an index file. Let’s consider the example of a simulation of a
  11   binary mixture of components A and B. When we want to calculate the
  12   radial distribution function (RDF) :math:`g_{AB}(r)` of A with respect
  13   to B, we have to calculate:
  14
  15   .. math:: 4\pi r^2 g_{AB}(r)      ~=~     V~\sum_{i \in A}^{N_A} \sum_{j \in B}^{N_B} P(r)
  16             :label: eqnanalysisrdf
  17
  18 | where :math:`V` is the volume and :math:`P(r)` is the probability of
  19   finding a B atom at distance :math:`r` from an A atom.
  20
  21 By having the user define the *atom numbers* for groups A and B in a
  22 simple file, we can calculate this :math:`g_{AB}` in the most general
  23 way, without having to make any assumptions in the RDF program about the
  24 type of particles.
  25
  26 Groups can therefore consist of a series of *atom numbers*, but in some
  27 cases also of *molecule numbers*. It is also possible to specify a
  28 series of angles by *triples* of *atom numbers*, dihedrals by
  29 *quadruples* of *atom numbers* and bonds or vectors (in a molecule) by
  30 *pairs* of *atom numbers*. When appropriate the type of index file will
  31 be specified for the following analysis programs. To help creating such
  32 :ref:`index file <ndx>` ``index.ndx``), there are a couple of programs to generate
  33 them, using either your input configuration or the topology. To generate
  34 an index file consisting of a series of *atom numbers* (as in the
  35 example of :math:`g_{AB}`), use :ref:`gmx make_ndx`
  36 or :ref:`gmx select`. To generate an index file with
  37 angles or dihedrals, use :ref:`gmx mk_angndx`. Of course you can also
  38 make them by hand. The general format is presented here:
  39
  40 ::
  41
  42     [ Oxygen ]
  43        1       4       7
  44
  45     [ Hydrogen ]
  46        2       3       5       6
  47        8       9
  48
  49 First, the group name is written between square brackets. The following
  50 atom numbers may be spread out over as many lines as you like. The atom
  51 numbering starts at 1.
  52
  53 Each tool that can use groups will offer the available alternatives for
  54 the user to choose. That choice can be made with the number of the
  55 group, or its name. In fact, the first few letters of the group name
  56 will suffice if that will distinguish the group from all others. There
  57 are ways to use Unix shell features to choose group names on the command
  58 line, rather than interactively. Consult our `webpage`_ for suggestions.
  59
  60 .. _defaultgroups:
  61
  62 Default Groups
  63 ~~~~~~~~~~~~~~
  64
  65 When no index file is supplied to analysis tools or
  66 :ref:`grompp <gmx grompp>`, a number of default
  67 groups are generated to choose from:
  68
  69 ``System``
  70     | all atoms in the system
  71
  72 ``Protein``
  73     | all protein atoms
  74
  75 ``Protein-H``
  76     | protein atoms excluding hydrogens
  77
  78 ``C-alpha``
  79     | C\ :math:`_{\alpha}` atoms
  80
  81 ``Backbone``
  82     | protein backbone atoms; N, C\ :math:`_{\alpha}` and C
  83
  84 ``MainChain``
  85     | protein main chain atoms: N, C\ :math:`_{\alpha}`, C and O,
  86       including oxygens in C-terminus
  87
  88 ``MainChain+Cb``
  89     | protein main chain atoms including C\ :math:`_{\beta}`
  90
  91 ``MainChain+H``
  92     | protein main chain atoms including backbone amide hydrogens and
  93       hydrogens on the N-terminus
  94
  95 ``SideChain``
  96     | protein side chain atoms; that is all atoms except N,
  97       C\ :math:`_{\alpha}`, C, O, backbone amide hydrogens, oxygens in
  98       C-terminus and hydrogens on the N-terminus
  99
 100 ``SideChain-H``
 101     | protein side chain atoms excluding all hydrogens
 102
 103 ``Prot-Masses``
 104     | protein atoms excluding dummy masses (as used in virtual site
 105       constructions of NH\ :math:`_3` groups and tryptophan
 106       side-chains), see also sec. :ref:`vsitetop`; this group is only
 107       included when it differs from the ``Protein`` group
 108
 109 ``Non-Protein``
 110     | all non-protein atoms
 111
 112 ``DNA``
 113     | all DNA atoms
 114
 115 ``RNA``
 116     | all RNA atoms
 117
 118 ``Water``
 119     | water molecules (names like ``SOL``, ``WAT``, ``HOH``, etc.) See
 120       ``residuetypes.dat`` for a full listing
 121
 122 ``non-Water``
 123     | anything not covered by the ``Water`` group
 124
 125 ``Ion``
 126     | any name matching an Ion entry in
 127       ``residuetypes.dat``
 128
 129 ``Water_and_Ions``
 130     | combination of the ``Water`` and ``Ions``
 131       groups
 132
 133 ``molecule_name``
 134     | for all residues/molecules which are not recognized as protein,
 135       DNA, or RNA; one group per residue/molecule name is generated
 136
 137 ``Other``
 138     | all atoms which are neither protein, DNA, nor RNA.
 139
 140 Empty groups will not be generated. Most of the groups only contain
 141 protein atoms. An atom is considered a protein atom if its residue name
 142 is listed in the
 143 ``residuetypes.dat``
 144 file and is listed as a “Protein” entry. The process for determinding
 145 DNA, RNA, etc. is analogous. If you need to modify these
 146 classifications, then you can copy the file from the library directory
 147 into your working directory and edit the local copy.
 148
 149 .. _selections:
 150
 151 Selections
 152 ~~~~~~~~~~
 153
 154 | :ref:`gmx select <gmx select>`
 155 | Currently, a few analysis tools support an extended concept of
 156   *(dynamic) selections*. There are three
 157   main differences to traditional index groups:
 158
 159 -  The selections are specified as text instead of reading fixed atom
 160    indices from a file, using a syntax similar to VMD. The text can be
 161    entered interactively, provided on the command line, or from a file.
 162
 163 -  The selections are not restricted to atoms, but can also specify that
 164    the analysis is to be performed on, e.g., center-of-mass positions of
 165    a group of atoms. Some tools may not support selections that do not
 166    evaluate to single atoms, e.g., if they require information that is
 167    available only for single atoms, like atom names or types.
 168
 169 -  The selections can be dynamic, i.e., evaluate to different atoms for
 170    different trajectory frames. This allows analyzing only a subset of
 171    the system that satisfies some geometric criteria.
 172
 173 As an example of a simple selection, ``resname ABC`` and
 174 ``within 2 of resname DEF`` selects all atoms in residues named ABC that are
 175 within 2nm of any atom in a residue named DEF.
 176
 177 Tools that accept selections can also use traditional index files
 178 similarly to older tools: it is possible to give an :ref:`ndx`
 179 file to the tool, and directly select a group from the index file as a
 180 selection, either by group number or by group name. The index groups can
 181 also be used as a part of a more complicated selection.
 182
 183 To get started, you can run :ref:`gmx select <gmx select>` with a single
 184 structure, and use the interactive prompt to try out different
 185 selections. The tool provides, among others, output options
 186 ``-on`` and ``-ofpdb`` to write out the selected
 187 atoms to an index file and to a :ref:`pdb` file, respectively.
 188 This does not allow testing selections that evaluate to center-of-mass
 189 positions, but other selections can be tested and the result examined.
 190
 191 The detailed syntax and the individual keywords that can be used in
 192 selections can be accessed by typing ``help`` in the
 193 interactive prompt of any selection-enabled tool, as well as with
 194 :ref:`gmx help <gmx help>` selections. The help is divided into subtopics
 195 that can be accessed with, e.g., ``help syntax``/
 196 :ref:`gmx help <gmx help>` ``selections syntax``. Some individual selection
 197 keywords have extended help as well, which can be accessed with, e.g.,
 198 ``help keywords`` within.
 199
 200 The interactive prompt does not currently provide much editing
 201 capabilities. If you need them, you can run the program under
 202 ``rlwrap``.
 203
 204 For tools that do not yet support the selection syntax, you can use
 205 :ref:`gmx select <gmx select>` -on to generate static index groups to pass
 206 to the tool. However, this only allows for a small subset (only the
 207 first bullet from the above list) of the flexibility that fully
 208 selection-aware tools offer.
 209
 210 It is also possible to write your own analysis tools to take advantage
 211 of the flexibility of these selections: see the
 212 ``template.cpp`` file in the
 213 ``share/gromacs/template`` directory of your installation
 214 for an example.