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