Skip to content

Commit 5b3ae0e

Browse files
lilyminiumorbeckstRMeli
authored
Add some preliminary guesser docs (#409)
* add some preliminary guesser docs * fix ipython blocks * Apply suggestions from code review Co-authored-by: Rocco Meli <[email protected]> * link to Guesser API * Update guessing.rst - address @RMeli comments - minor grammar fixes - moved note on radii guessing to explicit rst note * Apply suggestions from code review fix whitespace to make pre-hook check happy * fix ipython block * add changes from review * add link to changelog --------- Co-authored-by: Oliver Beckstein <[email protected]> Co-authored-by: Rocco Meli <[email protected]>
1 parent bbf1253 commit 5b3ae0e

File tree

4 files changed

+273
-72
lines changed

4 files changed

+273
-72
lines changed

‎doc/source/formats/guessers/default.rst‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
.. _default-guesser:
2+
3+
==============
4+
DefaultGuesser
5+
==============
6+
7+
8+
.. warning::
9+
10+
The default guesser has been created to reproduce pre-v2.8.0 MDAnalysis guessing behaviour as much as possible. However, minor changes were unavoidable and have been detailed in the `2.8.0 CHANGELOG notes <https://github.com/MDAnalysis/mdanalysis/blob/develop/package/CHANGELOG>`_ . **Default behaviours will change in MDAnalysis version 3**, as detailed in deprecation warnings.
11+
12+
13+
The :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` is the default guessing context for MDAnalysis. For historical reasons the ``DefaultGuesser`` largely works with biological conventions; for example, an atom named CA will be assumed to be a carbon rather than a calcium atom.
14+
15+
16+
Attributes guessed
17+
==================
18+
19+
The topology attributes guessed by the default guesser are listed below, as are their dependencies and broad assumptions.
20+
Please see the `Guesser API documentation`_ for more details.
21+
22+
.. _`Guesser API documentation`: https://docs.mdanalysis.org/stable/documentation_pages/guesser_modules/default_guesser.html
23+
24+
.. _default-guesser-types:
25+
26+
------------------
27+
Elements and types
28+
------------------
29+
30+
The default guesser guesses atom ``element``\ s and ``type``\ s using the same pathway; when atom ``type``\ s are guessed, they represent the atom ``element``. Atom elements are guessed from the atom name. The default guesser follows biological naming conventions, where atoms named "CA" are much more likely to represent an alpha-carbon than a calcium atom. This guesser is still relatively fragile for non-traditionally biological atom names.
31+
32+
The :meth:`~MDAnalysis.guesser.default_guesser.DefaultGuesser.guess_atom_element` method is used to guess atom elements or types following a process by which numbers, symbols, and some letters are stripped from the atom name and checked against a look-up table, as detailed in the `Guesser API documentation`_. With this method, for example, "AO5*" would be guessed as "O", and "3hg2" as "H".
33+
34+
35+
------
36+
Masses
37+
------
38+
39+
Masses are guessed by using a look-up table to get masses from the atom's ``element`` attribute. If ``element``\ s are not available, the atom's ``type`` is used in place of the element. If the ``type`` is not available, that is
40+
:ref:`guessed first <default-guesser-types>`.
41+
42+
43+
.. warning::
44+
45+
When an atom mass cannot be guessed from the atom ``type`` or ``name``, the atom is currently assigned a mass of 0.0.
46+
47+
Masses are guessed atom-by-atom, so even if most atoms have been guessed correctly, it is possible that some have been given masses of 0. It is important to check for non-zero masses before using methods that rely on them, such as :meth:`AtomGroup.center_of_mass`.
48+
49+
50+
.. important::
51+
52+
`np.nan` will be used as a default or "missing" value
53+
in place of 0.0 for atom masses in version 3.0 of MDAnalysis.
54+
55+
56+
-------------
57+
Aromaticities
58+
-------------
59+
60+
These are guessed using the :ref:`RDKit <RDKit-format>` converter by using the ``GetIsAromatic`` method.
61+
62+
.. note::
63+
RDKit needs to have been installed for aromaticity guessing to be available.
64+
RDKit is always installed when MDAnalysis was installed with conda-forge packages
65+
but this may not be the case when using other installation paths.
66+
67+
-----------------------------------
68+
Bonds, Angles, Dihedrals, Impropers
69+
-----------------------------------
70+
71+
MDAnalysis can guess if bonds exist between two atoms, based on the distance between them. A bond is created if the 2 atoms are within
72+
73+
.. math::
74+
75+
d < f \cdot (R_1 + R_2)
76+
77+
of each other, where :math:`R_1` and :math:`R_2` are the van der Waals radii
78+
of the atoms and :math:`f` is an ad-hoc *fudge factor*. This is
79+
the `same algorithm that VMD uses`_.
80+
81+
.. note::
82+
83+
Previously, guessing bonds would also guess angles and dihedrals. This is no longer the case. Angles, dihedrals, and impropers are not guessed by the default guesser unless
84+
explicitly requested by the user.
85+
86+
87+
Angles can be guessed from the bond connectivity. MDAnalysis assumes that if atoms 1 & 2 are bonded, and 2 & 3 are bonded, then (1,2,3) must be an angle.
88+
89+
::
90+
91+
1
92+
\
93+
2 -- 3
94+
95+
Dihedral angles and improper dihedrals can both be guessed from angles. Proper dihedrals are guessed by assuming that if (1,2,3) is an angle, and 3 & 4 are bonded, then (1,2,3,4) must be a dihedral.
96+
97+
::
98+
99+
1 4
100+
\ /
101+
2 -- 3
102+
103+
Likewise, if (1,2,3) is an angle, and 2 & 4 are bonded, then (2, 1, 3, 4) must be an improper dihedral (i.e. the improper dihedral is the angle between the planes formed by (1, 2, 3) and (1, 3, 4))
104+
105+
::
106+
107+
1
108+
\
109+
2 -- 3
110+
/
111+
4
112+
113+
114+
.. _`same algorithm that VMD uses`:
115+
http://www.ks.uiuc.edu/Research/vmd/vmd-1.9.1/ug/node26.html

‎doc/source/formats/guessing.rst‎

Lines changed: 0 additions & 71 deletions
This file was deleted.

‎doc/source/guessing.rst‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
.. -*- coding: utf-8 -*-
2+
.. _guessing:
3+
4+
============================
5+
Guessing Topology Attributes
6+
============================
7+
8+
Since version 2.8.0 MDAnalysis has introduced a new context-dependent guessing API to guess topology attributes that are not read from the file. This allows topology attributes such as masses, charges, and atom types to be guessed from existing information in a context-dependent manner (e.g. biological naming conventions) rather than file formats, as was previously done.
9+
10+
.. list-table:: Supported guesser contexts
11+
:widths: 25 25 50
12+
:header-rows: 1
13+
14+
* - Guesser
15+
- Context name
16+
- Topology attributes guessed
17+
* - :ref:`DefaultGuesser <default-guesser>`
18+
- "default"
19+
- elements, types, masses, bonds, angles, dihedrals, impropers, aromaticities
20+
21+
22+
Guessing at Universe creation
23+
=============================
24+
25+
Topology attributes can be guessed at Universe creation by passing in topology attributes to guess to the ``to_guess`` keyword. By default, as of version 2.8.0, the default guesser is used to guess ``types`` and ``masses``.
26+
27+
28+
.. ipython:: python
29+
30+
import MDAnalysis as mda
31+
from MDAnalysis.tests.datafiles import PRM12
32+
u = mda.Universe(PRM12, context="default", to_guess=["types", "masses", "bonds"])
33+
u.atoms.bonds
34+
35+
36+
In general, guessing at Universe creation works very similarly to guessing using the :ref:`guess_TopologyAttrs method<guess-topologyAttrs>` interface documented below. The main difference is that passing guesser-specific keyword arguments such as ``fudge_factor`` and ``vdwradii`` into Universe creation is **now deprecated and will be removed in version 3.0**. Instead, we recommend specifying these arguments through an explicit call to the :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs`.
37+
38+
.. _guess-topologyAttrs:
39+
40+
Guessing using the ``guess_TopologyAttrs()`` interface
41+
======================================================
42+
43+
Topology attributes can also be guessed after :class:`~MDAnalysis.core.universe.Universe` creation using the :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` method. The ``to_guess``, ``force_guess``, and ``context`` keywords are used to specify which attributes to guess, which attributes to forcibly re-guess, and which guesser to use, respectively. These three keywords perform the same way here as they do in Universe creation.
44+
45+
As with :class:`Universe` creation, the :ref:`DefaultGuesser <default-guesser>` is used as the default ``context``. The following example demonstrates how to guess atom types and masses after Universe creation.
46+
47+
.. ipython:: python
48+
49+
u = mda.Universe(PRM12, to_guess=[]) # in v2.8.0 masses and types are guessed by default
50+
u.guess_TopologyAttrs(to_guess=["types", "masses"])
51+
u.atoms.types
52+
53+
54+
The context can be specified either using a string (e.g., ``"default"``) or an already created *Guesser* object (which will have been derived from the base class :class:`~MDAnalysis.guesser.base.GuesserBase`). It may be convenient to pass in an already-created *Guesser* object (such as the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser`) if there are particular keywords you want to use in guessing methods, such as the ``fudge_factor``, ``vdwradii`` or ``lower_bound`` keywords for controlling bond guessing. However, if additional keyword arguments are passed into :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs`, they will **replace** any existing arguments inside the guesser.
55+
56+
.. ipython:: python
57+
58+
from MDAnalysis.guesser import DefaultGuesser
59+
from MDAnalysis.tests.datafiles import CONECT # example data file
60+
61+
u = mda.Universe(CONECT)
62+
guesser = DefaultGuesser(u, fudge_factor=1.2)
63+
u.guess_TopologyAttrs(to_guess=["bonds"], context=guesser, fudge_factor=0.5)
64+
guesser._kwargs["fudge_factor"]
65+
66+
67+
--------------------
68+
Forcibly re-guessing
69+
--------------------
70+
71+
MDAnalysis will preferentially read topology attributes from file instead of re-guessing them, even if the attribute is passed into ``to_guess``. For example, below, the ``types`` attributes reflects the actual atom types in the file.
72+
73+
.. ipython:: python
74+
75+
u = mda.Universe(PRM12, to_guess=["types", "masses"])
76+
u.atoms.types
77+
78+
.. note::
79+
80+
In cases where the attribute is only present for *some* atoms in the file (e.g. a patchy element column in a PDB), MDAnalysis will only guess the attribute for atoms where it is not present in the file.
81+
82+
To force MDAnalysis to re-guess a TopologyAttr, pass in the attribute to the ``force_guess`` keyword. This will force MDAnalysis to guess the attribute even if it is present in the file.
83+
84+
.. ipython:: python
85+
86+
u.guess_TopologyAttrs(to_guess=["types"], force_guess=["types"])
87+
u.atoms.types
88+
89+
90+
------------------------------------
91+
Guessing bonds, angles, and torsions
92+
------------------------------------
93+
94+
Whereas most attributes are guessed at the atom, residue, or segment level, guessing topology objects such as bonds, angles, dihedrals and impropers behaves somewhat differently, and interacts with the ``force_guess`` keyword specially.
95+
96+
Specifically, if these connectivity attributes are guessed, they are by default guessed **additively**. Therefore, if bonds and other objects are guessed twice, **the bonds of the second guess are added on.** Below, we see the number of bonds increase when guessed again with a looser criteria.
97+
98+
.. ipython:: python
99+
100+
from MDAnalysis.tests.datafiles import CONECT
101+
102+
u = mda.Universe(CONECT, to_guess=["bonds"])
103+
print(len(u.bonds))
104+
u.guess_TopologyAttrs(to_guess=["bonds"], fudge_factor=1.2) # looser
105+
print(len(u.bonds))
106+
107+
108+
However, the **number of bonds doesn't change when the bonds are guessed again with stricter criteria** -- no new bonds are found (and also no bonds are removed either, even if they do not match the new criteria):
109+
110+
.. ipython:: python
111+
112+
u.guess_TopologyAttrs(to_guess=["bonds"], fudge_factor=0.5) # stricter
113+
print(len(u.bonds))
114+
115+
116+
Moreover, bonds are unique, so if the bonds are guessed again with the same criteria, the guessed bonds don't change:
117+
118+
.. ipython:: python
119+
120+
u.guess_TopologyAttrs(to_guess=["bonds"], fudge_factor=0.5) # same
121+
print(len(u.bonds))
122+
123+
124+
However, if you want to forcibly overwrite all existing bonds, angles, dihedrals or impropers, you can pass the object to the ``force_guess`` keyword. This will **remove all existing objects of that type before guessing.** Below, we see the number of bonds has shrunk when guessed with stricter criteria:
125+
126+
.. ipython:: python
127+
128+
u.guess_TopologyAttrs(to_guess=["bonds"], force_guess=["bonds"], fudge_factor=0.5)
129+
print(len(u.bonds))
130+
131+
132+
-----------------
133+
Order of guessing
134+
-----------------
135+
136+
The order of the attributes guessed can matter in some cases. For example, bond guessing with the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` relies on looking up the vdW radii of the atoms involved by their atom ``type``. That means that for file formats where the atom ``type`` is not a valid element, the atom ``type`` must be forcefully re-guessed for bond-guessing to work.
137+
138+
.. note::
139+
140+
The behaviour of looking up radii by *type* will likely change to looking up by *element* in version 3.0.
141+
142+
Therefore the following will not work (in MDAnalysis < 3.0) due to the types encoded in the PSF file:
143+
144+
.. ipython:: python
145+
:okexcept:
146+
147+
from MDAnalysis.tests.datafiles import PSF, DCD
148+
u = mda.Universe(PSF, DCD)
149+
print(u.atoms.types)
150+
u.guess_TopologyAttrs(to_guess=["bonds"])
151+
152+
However, the snippet below will re-guess the types, and now bond-guessing can work as the elements have vdW radii defined:
153+
154+
.. ipython:: python
155+
156+
u.guess_TopologyAttrs(to_guess=["types", "bonds"], force_guess=["types"])
157+
print(u.atoms.types)

‎doc/source/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ Wherever possible, do not take these conversations to private channels, includin
8585
groups_of_atoms
8686
selections
8787
topology_system
88+
guessing
8889

8990
.. toctree::
9091
:maxdepth: 1
@@ -103,7 +104,6 @@ Wherever possible, do not take these conversations to private channels, includin
103104

104105
reading_and_writing
105106
formats/index
106-
formats/guessing
107107
formats/auxiliary
108108
formats/selection_exporters
109109
formats/format_reference

0 commit comments

Comments
 (0)