From c0f0b213437763195e6c9b98cb9a097eaf5011f2 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Sat, 19 Oct 2024 15:45:31 +1100 Subject: [PATCH 1/6] update docs --- package/MDAnalysis/guesser/default_guesser.py | 136 ++++++++++++++---- package/MDAnalysis/topology/CRDParser.py | 13 ++ package/MDAnalysis/topology/DLPolyParser.py | 6 + package/MDAnalysis/topology/DMSParser.py | 8 +- .../MDAnalysis/topology/ExtendedPDBParser.py | 6 + package/MDAnalysis/topology/FHIAIMSParser.py | 7 + package/MDAnalysis/topology/GMSParser.py | 7 + package/MDAnalysis/topology/GROParser.py | 6 + package/MDAnalysis/topology/ITPParser.py | 7 + package/MDAnalysis/topology/LAMMPSParser.py | 6 + package/MDAnalysis/topology/MMTFParser.py | 6 + package/MDAnalysis/topology/MOL2Parser.py | 7 + package/MDAnalysis/topology/PDBParser.py | 7 + package/MDAnalysis/topology/PDBQTParser.py | 6 + package/MDAnalysis/topology/PQRParser.py | 8 ++ package/MDAnalysis/topology/TXYZParser.py | 6 + package/MDAnalysis/topology/XYZParser.py | 6 + .../documentation_pages/guesser_modules.rst | 34 +++-- 18 files changed, 247 insertions(+), 35 deletions(-) diff --git a/package/MDAnalysis/guesser/default_guesser.py b/package/MDAnalysis/guesser/default_guesser.py index a64b023309e..488ef4e5171 100644 --- a/package/MDAnalysis/guesser/default_guesser.py +++ b/package/MDAnalysis/guesser/default_guesser.py @@ -27,9 +27,70 @@ DefaultGuesser is a generic guesser class that has basic guessing methods. This class is a general purpose guesser that can be used with most topologies, -but being generic makes it the less accurate among all guessers. +but being generic makes it the least accurate among all guessers. +Guessing behavior +----------------- + +This section describes how each attribute is guessed by the DefaultGuesser. + +Masses +~~~~~~ + +We first attempt to look up the mass of an atom based on its element if the +element TopologyAttr is available. If not, we attempt to lookup the mass based +on the atom type (``type``) TopologyAttr. If neither of these is available, we +attempt to guess the atom type based on the atom name (``name``) and then +lookup the mass based on the guessed atom type. + + +Types +~~~~~ + +We attempt to guess the atom type based on the atom name (``name``). +The name is first stripped of any numbers and symbols, and then looked up in +the :data:`MDAnalysis.guesser.tables.atomelements` table. If the name is not +found, we continue checking variations of the name following the logic in +:meth:`DefaultGuesser.guess_atom_element`. Ultimately, if no match is found, the first character +of the stripped name is returned. + +Elements +~~~~~~~~ + +This follows the same method as guessing atom types. + + +Bonds +~~~~~ + +Bonds are guessed based on the distance between atoms. +See :meth:`DefaultGuesser.guess_bonds` for more details. + +Angles +~~~~~~ + +Angles are guessed based on the bonds between atoms. +See :meth:`DefaultGuesser.guess_angles` for more details. + +Dihedrals +~~~~~~~~~ + +Dihedrals are guessed based on the angles between atoms. +See :meth:`DefaultGuesser.guess_dihedrals` for more details. + +Improper Dihedrals +~~~~~~~~~~~~~~~~~~ + +Improper dihedrals are guessed based on the angles between atoms. +See :meth:`DefaultGuesser.guess_improper_dihedrals` for more details. + +Aromaticities +~~~~~~~~~~~~~ + +Aromaticity is guessed using RDKit's GetIsAromatic method. +See :meth:`DefaultGuesser.guess_aromaticities` for more details. + @@ -70,6 +131,23 @@ class DefaultGuesser(GuesserBase): You can use this guesser either directly through an instance, or through the :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` method. + Parameters + ---------- + universe : Universe + The Universe to apply the guesser on + box : np.ndarray, optional + The box of the Universe. This is used for bond guessing. + vdwradii : dict, optional + Dict relating atom types: vdw radii. This is used for bond guessing + fudge_factor : float, optional + The factor by which atoms must overlap each other to be considered + a bond. Larger values will increase the number of bonds found. [0.55] + lower_bound : float, optional + The minimum bond length. All bonds found shorter than this length + will be ignored. This is useful for parsing PDB with altloc records + where atoms with altloc A and B may be very close together and + there should be no chemical bond between them. [0.1] + Examples -------- to guess bonds for a universe:: @@ -84,8 +162,23 @@ class DefaultGuesser(GuesserBase): """ context = 'default' - def __init__(self, universe, **kwargs): - super().__init__(universe, **kwargs) + def __init__( + self, + universe, + box=None, + vdwradii=None, + fudge_factor=0.55, + lower_bound=0.1, + **kwargs + ): + super().__init__( + universe, + box=box, + vdwradii=vdwradii, + fudge_factor=fudge_factor, + lower_bound=lower_bound, + **kwargs + ) self._guesser_methods = { 'masses': self.guess_masses, 'types': self.guess_types, @@ -212,8 +305,16 @@ def guess_types(self, atom_types=None, indices_to_guess=None): def guess_atom_element(self, atomname): """Guess the element of the atom from the name. - Looks in dict to see if element is found, otherwise it uses the first - character in the atomname. The table comes from CHARMM and AMBER atom + First all numbers and symbols are stripped from the name. + Then the name is looked up in the :data:`MDAnalysis.guesser.tables.atomelements` + table. If the name is not found, we remove the last + character or first character from the name and check the table for both, + with a preference for removing the last character. If the name is still + not found, we iteratively continue to remove the last character or + first character until we find a match. If ultimately no match is found, + the first character of the stripped name is returned. + + The table comes from CHARMM and AMBER atom types, where the first character is not sufficient to determine the atom type. Some GROMOS ions have also been added. @@ -270,26 +371,11 @@ def guess_bonds(self, atoms=None, coords=None): Parameters ---------- - atoms : AtomGroup - atoms for which bonds should be guessed - fudge_factor : float, optional - The factor by which atoms must overlap eachother to be considered a - bond. Larger values will increase the number of bonds found. [0.55] - vdwradii : dict, optional - To supply custom vdwradii for atoms in the algorithm. Must be a - dict of format {type:radii}. The default table of van der Waals - radii is hard-coded as :data:`MDAnalysis.guesser.tables.vdwradii`. - Any user defined vdwradii passed as an argument will supercede the - table values. [``None``] - lower_bound : float, optional - The minimum bond length. All bonds found shorter than this length - will be ignored. This is useful for parsing PDB with altloc records - where atoms with altloc A and B maybe very close together and - there should be no chemical bond between them. [0.1] - box : array_like, optional - Bonds are found using a distance search, if unit cell information - is given, periodic boundary conditions will be considered in the - distance search. [``None``] + atoms: AtomGroup + atoms for which bonds should be guessed + coords: np.ndarray, optional + coordinates of the atoms. If not provided, the coordinates + of the ``atoms`` in the universe are used. Returns ------- diff --git a/package/MDAnalysis/topology/CRDParser.py b/package/MDAnalysis/topology/CRDParser.py index 5e4406732f3..1867f0b6871 100644 --- a/package/MDAnalysis/topology/CRDParser.py +++ b/package/MDAnalysis/topology/CRDParser.py @@ -33,6 +33,12 @@ Residues are detected through a change is either resid or resname while segments are detected according to changes in segid. +.. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. _CRD: https://www.charmmtutorial.org/index.php/CHARMM:The_Basics @@ -72,6 +78,13 @@ class CRDParser(TopologyReaderBase): - Resnums - Segids + + .. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. versionchanged:: 2.8.0 Type and mass are not longer guessed here. Until 3.0 these will still be set by default through through universe.guess_TopologyAttrs() API. diff --git a/package/MDAnalysis/topology/DLPolyParser.py b/package/MDAnalysis/topology/DLPolyParser.py index b85a0d188cc..0ae6af833dd 100644 --- a/package/MDAnalysis/topology/DLPolyParser.py +++ b/package/MDAnalysis/topology/DLPolyParser.py @@ -30,6 +30,12 @@ - Atomnames - Atomids +.. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. _Poly: http://www.stfc.ac.uk/SCD/research/app/ccg/software/DL_POLY/44516.aspx Classes diff --git a/package/MDAnalysis/topology/DMSParser.py b/package/MDAnalysis/topology/DMSParser.py index f165272fc26..a095bb2c4c6 100644 --- a/package/MDAnalysis/topology/DMSParser.py +++ b/package/MDAnalysis/topology/DMSParser.py @@ -86,11 +86,17 @@ class DMSParser(TopologyReaderBase): Segment: - Segids + .. note:: + + By default, atomtypes will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. _DESRES: http://www.deshawresearch.com .. _Desmond: http://www.deshawresearch.com/resources_desmond.html .. _DMS: http://www.deshawresearch.com/Desmond_Users_Guide-0.7.pdf .. versionchanged:: 2.8.0 - Removed type and mass guessing (attributes guessing takes place now + Removed type guessing (attributes guessing takes place now through universe.guess_TopologyAttrs() API). """ diff --git a/package/MDAnalysis/topology/ExtendedPDBParser.py b/package/MDAnalysis/topology/ExtendedPDBParser.py index ec6e1e527d2..df4beb4832b 100644 --- a/package/MDAnalysis/topology/ExtendedPDBParser.py +++ b/package/MDAnalysis/topology/ExtendedPDBParser.py @@ -77,6 +77,12 @@ class ExtendedPDBParser(PDBParser.PDBParser): - elements - bonds - formalcharges + + .. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. See Also diff --git a/package/MDAnalysis/topology/FHIAIMSParser.py b/package/MDAnalysis/topology/FHIAIMSParser.py index fcf95691f33..3cde90d27e4 100644 --- a/package/MDAnalysis/topology/FHIAIMSParser.py +++ b/package/MDAnalysis/topology/FHIAIMSParser.py @@ -66,6 +66,13 @@ class FHIAIMSParser(TopologyReaderBase): Creates the following attributes: - Atomnames + + .. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. versionchanged:: 2.8.0 Removed type and mass guessing (attributes guessing takes place now through universe.guess_TopologyAttrs() API). diff --git a/package/MDAnalysis/topology/GMSParser.py b/package/MDAnalysis/topology/GMSParser.py index 812207ed674..541e6bb9c48 100644 --- a/package/MDAnalysis/topology/GMSParser.py +++ b/package/MDAnalysis/topology/GMSParser.py @@ -73,6 +73,13 @@ class GMSParser(TopologyReaderBase): - names - atomic charges + + .. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. versionadded:: 0.9.1 .. versionchanged:: 2.8.0 Removed type and mass guessing (attributes guessing takes place now diff --git a/package/MDAnalysis/topology/GROParser.py b/package/MDAnalysis/topology/GROParser.py index 6bcaec24cb5..f9d333db624 100644 --- a/package/MDAnalysis/topology/GROParser.py +++ b/package/MDAnalysis/topology/GROParser.py @@ -66,6 +66,12 @@ class GROParser(TopologyReaderBase): - resnames - atomids - atomnames + + .. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. .. versionchanged:: 2.8.0 Removed type and mass guessing (attributes guessing takes place now diff --git a/package/MDAnalysis/topology/ITPParser.py b/package/MDAnalysis/topology/ITPParser.py index d8552160278..e6e468f3b4c 100644 --- a/package/MDAnalysis/topology/ITPParser.py +++ b/package/MDAnalysis/topology/ITPParser.py @@ -473,6 +473,13 @@ class ITPParser(TopologyReaderBase): .. _ITP: http://manual.gromacs.org/current/reference-manual/topologies/topology-file-formats.html#molecule-itp-file .. _TOP: http://manual.gromacs.org/current/reference-manual/file-formats.html#top + .. note:: + + By default, atomtypes and masses will be guessed on Universe creation + if they are not read from the input file. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. versionchanged:: 2.2.0 no longer adds angles for water molecules with SETTLE constraint .. versionchanged:: 2.8.0 diff --git a/package/MDAnalysis/topology/LAMMPSParser.py b/package/MDAnalysis/topology/LAMMPSParser.py index 62664b568bc..321a577343f 100644 --- a/package/MDAnalysis/topology/LAMMPSParser.py +++ b/package/MDAnalysis/topology/LAMMPSParser.py @@ -27,6 +27,12 @@ Parses data_ or dump_ files produced by LAMMPS_. +.. note:: + + By default, masses will be guessed on Universe creation if they are not read + from the input file. This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. _LAMMPS: http://lammps.sandia.gov/ .. _data: DATA file format: :http://lammps.sandia.gov/doc/2001/data_format.html .. _dump: http://lammps.sandia.gov/doc/dump.html diff --git a/package/MDAnalysis/topology/MMTFParser.py b/package/MDAnalysis/topology/MMTFParser.py index e9332e9d689..4cf652ab565 100644 --- a/package/MDAnalysis/topology/MMTFParser.py +++ b/package/MDAnalysis/topology/MMTFParser.py @@ -64,6 +64,12 @@ - segid - model + .. note:: + + By default, masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + Classes ------- diff --git a/package/MDAnalysis/topology/MOL2Parser.py b/package/MDAnalysis/topology/MOL2Parser.py index 4345ca0efe7..b13266279f7 100644 --- a/package/MDAnalysis/topology/MOL2Parser.py +++ b/package/MDAnalysis/topology/MOL2Parser.py @@ -77,6 +77,13 @@ class MOL2Parser(TopologyReaderBase): - Bonds - Elements + + .. note:: + + By default, masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + Notes ----- diff --git a/package/MDAnalysis/topology/PDBParser.py b/package/MDAnalysis/topology/PDBParser.py index bad6d2bc6d5..1579bebca6c 100644 --- a/package/MDAnalysis/topology/PDBParser.py +++ b/package/MDAnalysis/topology/PDBParser.py @@ -35,6 +35,13 @@ :mod:`~MDAnalysis.topology.ExtendedPDBParser`) that can handle residue numbers up to 99,999. +.. note:: + + Atomtypes will be created from elements if they are present and valid. + Otherwise, they will be guessed on Universe creation. + By default, masses will also be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. .. Note:: diff --git a/package/MDAnalysis/topology/PDBQTParser.py b/package/MDAnalysis/topology/PDBQTParser.py index 97640820218..14ddfefdec5 100644 --- a/package/MDAnalysis/topology/PDBQTParser.py +++ b/package/MDAnalysis/topology/PDBQTParser.py @@ -32,6 +32,12 @@ * Reads a PDBQT file line by line and does not require sequential atom numbering. * Multi-model PDBQT files are not supported. +.. note:: + + By default, masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + Notes ----- Only reads atoms and their names; connectivity is not diff --git a/package/MDAnalysis/topology/PQRParser.py b/package/MDAnalysis/topology/PQRParser.py index 1adcd7fba2a..91773d6d21a 100644 --- a/package/MDAnalysis/topology/PQRParser.py +++ b/package/MDAnalysis/topology/PQRParser.py @@ -80,6 +80,14 @@ class PQRParser(TopologyReaderBase): - Resnames - Segids + .. note:: + + Atomtypes will be read from the input file if they are present + (e.g. GROMACS PQR files). Otherwise, they will be guessed on Universe + creation. By default, masses will also be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. versionchanged:: 0.9.0 Read chainID from a PQR file and use it as segid (before we always used diff --git a/package/MDAnalysis/topology/TXYZParser.py b/package/MDAnalysis/topology/TXYZParser.py index 0781488c9dc..6370b5e88e8 100644 --- a/package/MDAnalysis/topology/TXYZParser.py +++ b/package/MDAnalysis/topology/TXYZParser.py @@ -73,6 +73,12 @@ class TXYZParser(TopologyReaderBase): - Atomtypes - Elements (if all atom names are element symbols) + .. note:: + + By default, masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. versionadded:: 0.17.0 .. versionchanged:: 2.4.0 Adding the `Element` attribute if all names are valid element symbols. diff --git a/package/MDAnalysis/topology/XYZParser.py b/package/MDAnalysis/topology/XYZParser.py index cb0df129e08..b737d0019d3 100644 --- a/package/MDAnalysis/topology/XYZParser.py +++ b/package/MDAnalysis/topology/XYZParser.py @@ -59,6 +59,12 @@ class XYZParser(TopologyReaderBase): Creates the following attributes: - Atomnames + .. note:: + + By default, atomtypes and masses will be guessed on Universe creation. + This may change in release 3.0. + See :ref:`Guessers`_ for more information. + .. versionadded:: 0.9.1 diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst index 7747fdc380f..6cc4aa4f8d7 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst @@ -1,19 +1,30 @@ .. Contains the formatted docstrings from the guesser modules located in 'mdanalysis/package/MDAnalysis/guesser' +.. _Guessers: + ************************** Guesser modules ************************** -This module contains the context-aware guessers, which are used by the :meth:`~MDAnalysis.core.Universe.Universe.guess_TopologyAttrs` API. Context-aware guessers' main purpose +This module contains the context-aware guessers, which are used by the :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` API. Context-aware guessers' main purpose is to be tailored guesser classes that target specific file format or force field (eg. PDB file format, or Martini forcefield). -Having such guessers makes attribute guessing more accurate and reliable than having generic guessing methods that doesn't fit all topologies. +Having such guessers makes attribute guessing more accurate and reliable than having generic guessing methods that don't fit all scenarios. Example uses of guessers ------------------------ +Default behavior +~~~~~~~~~~~~~~~~ + +By default, MDAnalysis will guess the "mass" and "type" (atom type) attributes for all particles in the Universe +using the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` at the time of Universe creation, +if they are not read from the input file. +Please see the :ref:`DefaultGuesser`_ for more information. + + + Guessing using :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Guessing can be done through the Universe's :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` as following:: import MDAnalysis as mda @@ -24,12 +35,12 @@ Guessing can be done through the Universe's :meth:`~MDAnalysis.core.universe.Uni u.guess_TopologyAttrs(to_guess=['elements']) print(u.atoms.elements) # print ['N' 'H' 'H' ... 'NA' 'NA' 'NA'] -In the above example, we passed ``elements`` as the attribute we want to guess, and +In the above example, we passed ``elements`` as the attribute we want to guess :meth:`~MDAnalysis.core.universe.Universe.guess_TopologyAttrs` guess then add it as a topology attribute to the ``AtomGroup`` of the universe. -If the attribute already exist in the universe, passing the attribute of interest to the ``to_guess`` parameter will only fill the empty values of the attribute if any exists. -To override all the attribute values, you can pass the attribute to the ``force_guess`` parameter instead of the to_guess one as following:: +If the attribute already exists in the universe, passing the attribute of interest to the ``to_guess`` parameter will only fill the empty values of the attribute if any exists. +To override all the attribute values, you can pass the attribute to the ``force_guess`` parameter instead of ``to_guess`` as following:: import MDAnalysis as mda from MDAnalysisTests.datafiles import PRM12 @@ -38,9 +49,14 @@ To override all the attribute values, you can pass the attribute to the ``force_ u.guess_TopologyAttrs(force_guess=['types']) # types ['H', 'O', ..] -N.B.: If you didn't pass any ``context`` to the API, it will use the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` -.. rubric:: available guessers +.. note:: + The default ``context`` will use the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` + + + + +.. rubric:: Available guessers .. toctree:: :maxdepth: 1 @@ -48,7 +64,7 @@ N.B.: If you didn't pass any ``context`` to the API, it will use the :class:`~MD guesser_modules/default_guesser -.. rubric:: guesser core modules +.. rubric:: Guesser core modules The remaining pages are primarily of interest to developers as they contain functions and classes that are used in the implementation of From 15e932c4e39b8f59ed0be6da3683530f527c459b Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Sat, 19 Oct 2024 16:58:39 +1100 Subject: [PATCH 2/6] i've forgotten how sphinx works --- package/MDAnalysis/topology/CRDParser.py | 4 ++-- package/MDAnalysis/topology/DLPolyParser.py | 2 +- package/MDAnalysis/topology/DMSParser.py | 2 +- package/MDAnalysis/topology/ExtendedPDBParser.py | 2 +- package/MDAnalysis/topology/FHIAIMSParser.py | 2 +- package/MDAnalysis/topology/GMSParser.py | 2 +- package/MDAnalysis/topology/GROParser.py | 2 +- package/MDAnalysis/topology/ITPParser.py | 2 +- package/MDAnalysis/topology/LAMMPSParser.py | 2 +- package/MDAnalysis/topology/MMTFParser.py | 2 +- package/MDAnalysis/topology/MOL2Parser.py | 2 +- package/MDAnalysis/topology/PDBParser.py | 2 +- package/MDAnalysis/topology/PDBQTParser.py | 2 +- package/MDAnalysis/topology/PQRParser.py | 2 +- package/MDAnalysis/topology/TXYZParser.py | 2 +- package/MDAnalysis/topology/XYZParser.py | 2 +- .../doc/sphinx/source/documentation_pages/guesser_modules.rst | 2 +- 17 files changed, 18 insertions(+), 18 deletions(-) diff --git a/package/MDAnalysis/topology/CRDParser.py b/package/MDAnalysis/topology/CRDParser.py index 1867f0b6871..eb7b1c2418f 100644 --- a/package/MDAnalysis/topology/CRDParser.py +++ b/package/MDAnalysis/topology/CRDParser.py @@ -37,7 +37,7 @@ By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. _CRD: https://www.charmmtutorial.org/index.php/CHARMM:The_Basics @@ -83,7 +83,7 @@ class CRDParser(TopologyReaderBase): By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionchanged:: 2.8.0 Type and mass are not longer guessed here. Until 3.0 these will still be diff --git a/package/MDAnalysis/topology/DLPolyParser.py b/package/MDAnalysis/topology/DLPolyParser.py index 0ae6af833dd..4148a38c064 100644 --- a/package/MDAnalysis/topology/DLPolyParser.py +++ b/package/MDAnalysis/topology/DLPolyParser.py @@ -34,7 +34,7 @@ By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. _Poly: http://www.stfc.ac.uk/SCD/research/app/ccg/software/DL_POLY/44516.aspx diff --git a/package/MDAnalysis/topology/DMSParser.py b/package/MDAnalysis/topology/DMSParser.py index a095bb2c4c6..f37a854c725 100644 --- a/package/MDAnalysis/topology/DMSParser.py +++ b/package/MDAnalysis/topology/DMSParser.py @@ -90,7 +90,7 @@ class DMSParser(TopologyReaderBase): By default, atomtypes will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. _DESRES: http://www.deshawresearch.com .. _Desmond: http://www.deshawresearch.com/resources_desmond.html diff --git a/package/MDAnalysis/topology/ExtendedPDBParser.py b/package/MDAnalysis/topology/ExtendedPDBParser.py index df4beb4832b..6fa5bff616e 100644 --- a/package/MDAnalysis/topology/ExtendedPDBParser.py +++ b/package/MDAnalysis/topology/ExtendedPDBParser.py @@ -82,7 +82,7 @@ class ExtendedPDBParser(PDBParser.PDBParser): By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. See Also diff --git a/package/MDAnalysis/topology/FHIAIMSParser.py b/package/MDAnalysis/topology/FHIAIMSParser.py index 3cde90d27e4..8738d5e3ce9 100644 --- a/package/MDAnalysis/topology/FHIAIMSParser.py +++ b/package/MDAnalysis/topology/FHIAIMSParser.py @@ -71,7 +71,7 @@ class FHIAIMSParser(TopologyReaderBase): By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionchanged:: 2.8.0 Removed type and mass guessing (attributes guessing takes place now diff --git a/package/MDAnalysis/topology/GMSParser.py b/package/MDAnalysis/topology/GMSParser.py index 541e6bb9c48..fbd7a6f602d 100644 --- a/package/MDAnalysis/topology/GMSParser.py +++ b/package/MDAnalysis/topology/GMSParser.py @@ -78,7 +78,7 @@ class GMSParser(TopologyReaderBase): By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionadded:: 0.9.1 .. versionchanged:: 2.8.0 diff --git a/package/MDAnalysis/topology/GROParser.py b/package/MDAnalysis/topology/GROParser.py index f9d333db624..15ffeceb2f3 100644 --- a/package/MDAnalysis/topology/GROParser.py +++ b/package/MDAnalysis/topology/GROParser.py @@ -71,7 +71,7 @@ class GROParser(TopologyReaderBase): By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionchanged:: 2.8.0 Removed type and mass guessing (attributes guessing takes place now diff --git a/package/MDAnalysis/topology/ITPParser.py b/package/MDAnalysis/topology/ITPParser.py index e6e468f3b4c..9c9dd37976b 100644 --- a/package/MDAnalysis/topology/ITPParser.py +++ b/package/MDAnalysis/topology/ITPParser.py @@ -478,7 +478,7 @@ class ITPParser(TopologyReaderBase): By default, atomtypes and masses will be guessed on Universe creation if they are not read from the input file. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionchanged:: 2.2.0 no longer adds angles for water molecules with SETTLE constraint diff --git a/package/MDAnalysis/topology/LAMMPSParser.py b/package/MDAnalysis/topology/LAMMPSParser.py index 321a577343f..92e3709db1d 100644 --- a/package/MDAnalysis/topology/LAMMPSParser.py +++ b/package/MDAnalysis/topology/LAMMPSParser.py @@ -31,7 +31,7 @@ By default, masses will be guessed on Universe creation if they are not read from the input file. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. _LAMMPS: http://lammps.sandia.gov/ .. _data: DATA file format: :http://lammps.sandia.gov/doc/2001/data_format.html diff --git a/package/MDAnalysis/topology/MMTFParser.py b/package/MDAnalysis/topology/MMTFParser.py index 4cf652ab565..5a58f1b2454 100644 --- a/package/MDAnalysis/topology/MMTFParser.py +++ b/package/MDAnalysis/topology/MMTFParser.py @@ -68,7 +68,7 @@ By default, masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. Classes ------- diff --git a/package/MDAnalysis/topology/MOL2Parser.py b/package/MDAnalysis/topology/MOL2Parser.py index b13266279f7..7743ed04196 100644 --- a/package/MDAnalysis/topology/MOL2Parser.py +++ b/package/MDAnalysis/topology/MOL2Parser.py @@ -82,7 +82,7 @@ class MOL2Parser(TopologyReaderBase): By default, masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. Notes diff --git a/package/MDAnalysis/topology/PDBParser.py b/package/MDAnalysis/topology/PDBParser.py index 1579bebca6c..8349be9133b 100644 --- a/package/MDAnalysis/topology/PDBParser.py +++ b/package/MDAnalysis/topology/PDBParser.py @@ -41,7 +41,7 @@ Otherwise, they will be guessed on Universe creation. By default, masses will also be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. Note:: diff --git a/package/MDAnalysis/topology/PDBQTParser.py b/package/MDAnalysis/topology/PDBQTParser.py index 14ddfefdec5..435ec5678c8 100644 --- a/package/MDAnalysis/topology/PDBQTParser.py +++ b/package/MDAnalysis/topology/PDBQTParser.py @@ -36,7 +36,7 @@ By default, masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. Notes ----- diff --git a/package/MDAnalysis/topology/PQRParser.py b/package/MDAnalysis/topology/PQRParser.py index 91773d6d21a..9ef6d3e6f95 100644 --- a/package/MDAnalysis/topology/PQRParser.py +++ b/package/MDAnalysis/topology/PQRParser.py @@ -86,7 +86,7 @@ class PQRParser(TopologyReaderBase): (e.g. GROMACS PQR files). Otherwise, they will be guessed on Universe creation. By default, masses will also be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionchanged:: 0.9.0 diff --git a/package/MDAnalysis/topology/TXYZParser.py b/package/MDAnalysis/topology/TXYZParser.py index 6370b5e88e8..206f381e9e0 100644 --- a/package/MDAnalysis/topology/TXYZParser.py +++ b/package/MDAnalysis/topology/TXYZParser.py @@ -77,7 +77,7 @@ class TXYZParser(TopologyReaderBase): By default, masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionadded:: 0.17.0 .. versionchanged:: 2.4.0 diff --git a/package/MDAnalysis/topology/XYZParser.py b/package/MDAnalysis/topology/XYZParser.py index b737d0019d3..5fe736fec6a 100644 --- a/package/MDAnalysis/topology/XYZParser.py +++ b/package/MDAnalysis/topology/XYZParser.py @@ -63,7 +63,7 @@ class XYZParser(TopologyReaderBase): By default, atomtypes and masses will be guessed on Universe creation. This may change in release 3.0. - See :ref:`Guessers`_ for more information. + See :ref:`Guessers` for more information. .. versionadded:: 0.9.1 diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst index 6cc4aa4f8d7..5b34609ea25 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst @@ -18,7 +18,7 @@ Default behavior By default, MDAnalysis will guess the "mass" and "type" (atom type) attributes for all particles in the Universe using the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` at the time of Universe creation, if they are not read from the input file. -Please see the :ref:`DefaultGuesser`_ for more information. +Please see the :ref:`DefaultGuesser` for more information. From 1c5353da727694d8622f1321359b70821fa6a540 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Sun, 20 Oct 2024 01:23:13 +1100 Subject: [PATCH 3/6] replace ref with class --- .../doc/sphinx/source/documentation_pages/guesser_modules.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst index 5b34609ea25..96cb324270e 100644 --- a/package/doc/sphinx/source/documentation_pages/guesser_modules.rst +++ b/package/doc/sphinx/source/documentation_pages/guesser_modules.rst @@ -18,7 +18,7 @@ Default behavior By default, MDAnalysis will guess the "mass" and "type" (atom type) attributes for all particles in the Universe using the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` at the time of Universe creation, if they are not read from the input file. -Please see the :ref:`DefaultGuesser` for more information. +Please see the :class:`~MDAnalysis.guesser.default_guesser.DefaultGuesser` for more information. From 6bb0781fb950a42dd2ac7440c1c99c6b4f6ef0f0 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Sun, 20 Oct 2024 01:24:40 +1100 Subject: [PATCH 4/6] update changelog --- package/CHANGELOG | 2 ++ 1 file changed, 2 insertions(+) diff --git a/package/CHANGELOG b/package/CHANGELOG index 64fcb63fe0e..85a7208627b 100644 --- a/package/CHANGELOG +++ b/package/CHANGELOG @@ -23,6 +23,8 @@ The rules for this file: * 2.8.0 Fixes + * Adds guessed attributes documentation back to each parser page + and updates overall guesser docs (Issue #4696) * Fix Bohrium (Bh) atomic mass in tables.py (PR #3753) * set `n_parts` to the total number of frames being analyzed if `n_parts` is bigger. (Issue #4685) From d7bf3f36347d459bea600313ae351e173a7323b0 Mon Sep 17 00:00:00 2001 From: Lily Wang Date: Sun, 20 Oct 2024 01:29:39 +1100 Subject: [PATCH 5/6] fix whitespace --- package/MDAnalysis/guesser/default_guesser.py | 23 ++++++++++--------- package/MDAnalysis/topology/CRDParser.py | 2 +- .../MDAnalysis/topology/ExtendedPDBParser.py | 2 +- package/MDAnalysis/topology/GMSParser.py | 2 +- package/MDAnalysis/topology/GROParser.py | 2 +- package/MDAnalysis/topology/LAMMPSParser.py | 4 ++-- package/MDAnalysis/topology/MOL2Parser.py | 2 +- 7 files changed, 19 insertions(+), 18 deletions(-) diff --git a/package/MDAnalysis/guesser/default_guesser.py b/package/MDAnalysis/guesser/default_guesser.py index 488ef4e5171..8f75ac0fa63 100644 --- a/package/MDAnalysis/guesser/default_guesser.py +++ b/package/MDAnalysis/guesser/default_guesser.py @@ -51,9 +51,9 @@ We attempt to guess the atom type based on the atom name (``name``). The name is first stripped of any numbers and symbols, and then looked up in the :data:`MDAnalysis.guesser.tables.atomelements` table. If the name is not -found, we continue checking variations of the name following the logic in -:meth:`DefaultGuesser.guess_atom_element`. Ultimately, if no match is found, the first character -of the stripped name is returned. +found, we continue checking variations of the name following the logic in +:meth:`DefaultGuesser.guess_atom_element`. Ultimately, if no match is found, +the first character of the stripped name is returned. Elements ~~~~~~~~ @@ -306,14 +306,15 @@ def guess_atom_element(self, atomname): """Guess the element of the atom from the name. First all numbers and symbols are stripped from the name. - Then the name is looked up in the :data:`MDAnalysis.guesser.tables.atomelements` - table. If the name is not found, we remove the last - character or first character from the name and check the table for both, - with a preference for removing the last character. If the name is still - not found, we iteratively continue to remove the last character or - first character until we find a match. If ultimately no match is found, - the first character of the stripped name is returned. - + Then the name is looked up in the + :data:`MDAnalysis.guesser.tables.atomelements` table. + If the name is not found, we remove the last character or + first character from the name and check the table for both, + with a preference for removing the last character. If the name is + still not found, we iteratively continue to remove the last character + or first character until we find a match. If ultimately no match + is found, the first character of the stripped name is returned. + The table comes from CHARMM and AMBER atom types, where the first character is not sufficient to determine the atom type. Some GROMOS ions have also been added. diff --git a/package/MDAnalysis/topology/CRDParser.py b/package/MDAnalysis/topology/CRDParser.py index eb7b1c2418f..9a1fc72ec00 100644 --- a/package/MDAnalysis/topology/CRDParser.py +++ b/package/MDAnalysis/topology/CRDParser.py @@ -78,7 +78,7 @@ class CRDParser(TopologyReaderBase): - Resnums - Segids - + .. note:: By default, atomtypes and masses will be guessed on Universe creation. diff --git a/package/MDAnalysis/topology/ExtendedPDBParser.py b/package/MDAnalysis/topology/ExtendedPDBParser.py index 6fa5bff616e..b41463403e1 100644 --- a/package/MDAnalysis/topology/ExtendedPDBParser.py +++ b/package/MDAnalysis/topology/ExtendedPDBParser.py @@ -77,7 +77,7 @@ class ExtendedPDBParser(PDBParser.PDBParser): - elements - bonds - formalcharges - + .. note:: By default, atomtypes and masses will be guessed on Universe creation. diff --git a/package/MDAnalysis/topology/GMSParser.py b/package/MDAnalysis/topology/GMSParser.py index fbd7a6f602d..2223cc42756 100644 --- a/package/MDAnalysis/topology/GMSParser.py +++ b/package/MDAnalysis/topology/GMSParser.py @@ -73,7 +73,7 @@ class GMSParser(TopologyReaderBase): - names - atomic charges - + .. note:: By default, atomtypes and masses will be guessed on Universe creation. diff --git a/package/MDAnalysis/topology/GROParser.py b/package/MDAnalysis/topology/GROParser.py index 15ffeceb2f3..ebb51e7cd02 100644 --- a/package/MDAnalysis/topology/GROParser.py +++ b/package/MDAnalysis/topology/GROParser.py @@ -66,7 +66,7 @@ class GROParser(TopologyReaderBase): - resnames - atomids - atomnames - + .. note:: By default, atomtypes and masses will be guessed on Universe creation. diff --git a/package/MDAnalysis/topology/LAMMPSParser.py b/package/MDAnalysis/topology/LAMMPSParser.py index 92e3709db1d..52a58f77291 100644 --- a/package/MDAnalysis/topology/LAMMPSParser.py +++ b/package/MDAnalysis/topology/LAMMPSParser.py @@ -29,8 +29,8 @@ .. note:: - By default, masses will be guessed on Universe creation if they are not read - from the input file. This may change in release 3.0. + By default, masses will be guessed on Universe creation if they are not + read from the input file. This may change in release 3.0. See :ref:`Guessers` for more information. .. _LAMMPS: http://lammps.sandia.gov/ diff --git a/package/MDAnalysis/topology/MOL2Parser.py b/package/MDAnalysis/topology/MOL2Parser.py index 7743ed04196..f5549858755 100644 --- a/package/MDAnalysis/topology/MOL2Parser.py +++ b/package/MDAnalysis/topology/MOL2Parser.py @@ -77,7 +77,7 @@ class MOL2Parser(TopologyReaderBase): - Bonds - Elements - + .. note:: By default, masses will be guessed on Universe creation. From 5b999a490075d4244be963d84531e49dc13a0231 Mon Sep 17 00:00:00 2001 From: Lily Wang <31115101+lilyminium@users.noreply.github.com> Date: Sun, 20 Oct 2024 10:42:57 +1100 Subject: [PATCH 6/6] Update default_guesser.py Co-authored-by: Irfan Alibay --- package/MDAnalysis/guesser/default_guesser.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/package/MDAnalysis/guesser/default_guesser.py b/package/MDAnalysis/guesser/default_guesser.py index 8f75ac0fa63..f49e75b24c6 100644 --- a/package/MDAnalysis/guesser/default_guesser.py +++ b/package/MDAnalysis/guesser/default_guesser.py @@ -314,6 +314,8 @@ def guess_atom_element(self, atomname): still not found, we iteratively continue to remove the last character or first character until we find a match. If ultimately no match is found, the first character of the stripped name is returned. + + If the input name is an empty string, an empty string is returned. The table comes from CHARMM and AMBER atom types, where the first character is not sufficient to determine the