Merge branch 'main' into optional_filter_ordering

docs/guide/application_free_energies_system_representations.rst

@@ -3,14 +3,14 @@ Application in Free Energy Calculations
 =======================================
 
 In recent literature, many ways have shown how a system can be represented
-during a free energy calculation. Here is a small Taxonomy that tries to
-capture them and show benefits and disadvantages (more you can find in
+during a free energy calculation. Here is a small taxonomy that tries to
+capture them and show benefits and disadvantages (more information can be found in
 [1]_ [2]_):
 
 .. image:: ../_static/img/Topology_types.png
 
-The hybrid topology approach and the single topology approach depend heavily
-on atom mappings, The mappings are used to find the shared core region of the
+The hybrid and single topology approaches depend heavily
+on atom mappings. The mappings are used to find the shared core region of the
 molecules, such that the atoms part of this region can be represented as one.
 The single topology approach tries to maximize the number of mapped
 atoms, where the hybrid topology approach only maps one shared region of
@@ -20,6 +20,8 @@ each other.
 The usage of Kartograf's atom mapper for this application can be found in the
 turorial: :doc:`/tutorial/mapping_tutorial`.
 
+References
+~~~~~~~~~~
 
 .. [1] Ries, B.; Rieder, S.; Rhiner, C.; Hünenberger, P. H.; Riniker, S. - RestraintMaker: a graph-based approach to select distance restraints in free-energy calculations with dual topology. J Comput Aided Mol Des 36, 175–192 (2022). https://doi.org/10.1007/s10822-022-00445-6.
 .. [2] Ries, B.; Alibay, I.; Swenson, D. W. H; Baumann, H. M.; Henry, M. M.; Eastwood, J. R. B.; Gowers, R. J. - Kartograf: An Accurate Geometry-Based Atom Mapper for Hybrid Topology Relative Free Energy Calculations, Chemrxiv (2023) https://10.26434/chemrxiv-2023-0n1pq

docs/guide/atom_mapping.rst

@@ -2,9 +2,8 @@
 Atom Mapping
 ===============================
 
-Atom mappings can have a large variety of different use cases. The general
-the goal of atom mapping is to find an assignment between two sets of atoms
-based on a certain motivation. A very common approach is to find an
+Atom mappings can have a large variety of different use cases. The general goal of atom mapping is to find an
+assignment between two sets of atoms based on a certain motivation. A very common approach is to find an
 assignment of atoms, between two molecules, which are considered similar/equal
 leading to an MCS estimation.
 
@@ -32,10 +31,11 @@ Approach:
 Atom Mapping Filters
 ---------------------
 
-Additionally, can rules be applied during Kartograf's mapping algorithm,
+Additionally, rules can be applied during Kartograf's mapping algorithm,
 such that for example hydrogens are only mapped on hydrogens or no ring
 breakage occurs. Such rules might be necessary in order to
-ensure sampling of physically relevant configurations or serve other purposes.
+ensure sampling of physically relevant configurations or serve other purposes. You can find more information and
+examples in the :ref:`mapping filters tutorial <custom-filter-label>`.
 
 
 

docs/guide/atom_mapping_scoring.rst

@@ -11,7 +11,7 @@ distance of 0 angstroms to each other.
 
 A less trivial example is the atom mapping case for molecule transformations
 like in hybrid topology free energy calculation approaches. In such a case
-the atom quality depends on the likelihood of the transformation to converge
+the mapping quality depends on the likelihood of the transformation to converge
 well and to give a reasonable free energy. This in a way would 
 require the true and calculated result of the calculation and lead to a henn
 egg problem. To tackle this problem usually simplistic approaches
@@ -25,10 +25,10 @@ those ligands.
 
 Additionally one can start adding parameter-specific scores, that depend on
 force fields or other method-related aspects. However this might
-theoretically improve the method outcome, it could minders the
+theoretically improve the method outcome, it could hinder the
 transferability of the scorer from one method to another (overfitting).
 
 In Katograf we added some functionality, that can be used as an aspect of an
-atom mapping scorer, like the Mapping RSMD Scorer, checking the displacement
-of atoms by the scorers or the Volume Ratio Scorer, checking the volume overlap
+atom mapping scorer, like the :class:`.MappingRMSDScorer`, checking the displacement
+of atoms by the scorers or the :class:`.MappingVolumeRatioScorer`, checking the volume overlap
 of the two molecules.

docs/tutorial/custom_filters.rst

@@ -1,14 +1,17 @@
+.. _custom-filter-label:
 
 Customize Atom Mapping Filter Rules
 -----------------------------------
-.. _custom-filter-label:
 
 Sometimes the default rule-based filters of Kartograf's atom mapper,
-which don't map ring size changes, ring breaks, or flexibility changes in
-rings, might not be enough for you. For example, you might want to
-additionally avoid element changes in your mapping. Then you can customize
-the filter rules and employ your own rules. The general signature of the
-Filters uses a molecule `molA` and a molecule `molB`, that were provided to generate a `mapping` linking individual atoms from `molA` to `molB`. In the function, the `mapping` is filtered by the implemented rule resulting in a returned 'filtered_mappig`::
+which don't map ``ring size changes``, ``ring breaks``, or ``flexibility changes in rings``, might not be enough for you.
+For example, you might want to additionally avoid element changes in your mapping. Then you can customize
+the filter rules and employ your own rules. The general signature of the filters uses two molecules ``molA`` and
+``molB``, that were provided to generate a ``mapping`` linking individual atoms from ``molA`` to ``molB``.
+In the function, the ``mapping`` should then be filtered by the implemented rule resulting in a returned
+``filtered_mapping``:
+
+.. code-block::
 
     def custom_filter(
         molA: Chem.Mol, molB: Chem.Mol, mapping: dict[int, int]
@@ -22,7 +25,9 @@ Filters uses a molecule `molA` and a molecule `molB`, that were provided to gene
 This signature allows you to build your own filter, with any feature you
 like, for example, the following definition defines the filter for the element
 changes, by filtering for the atomic number of the RDKit molecules and
-comparing them. The return value of a filter is the filtered dictionary::
+comparing them. The return value of a filter is the filtered dictionary:
+
+.. code-block::
 
     def filter_element_changes(
         molA: Chem.Mol, molB: Chem.Mol, mapping: dict[int, int]
@@ -41,7 +46,9 @@ comparing them. The return value of a filter is the filtered dictionary::
         return filtered_mapping
 
 After defining this filter, you only need to plug it into the atom mapper
-like this::
+like this:
+
+.. code-block::
 
     from kartograf import KartografAtomMapper
     # Build Kartograf Atom Mapper

docs/tutorial/fused_rings.rst

@@ -27,7 +27,7 @@ for this special case. First, lets start by creating our example molecules and a
 
 The first type of mapping keeps the common rings fixed and grows the second fused ring using dummy atoms.
 This approach would involve transforming fewer atoms but can lead to systematic errors in the calculated free energies [1]_.
-This is the default behaviour of the ``KartografAtomMapper``:
+This is the default behaviour of the :class:`.KartografAtomMapper`:
 
 .. code-block::
 

docs/tutorial/mapping_tutorial.rst

@@ -52,13 +52,13 @@ visualization of the mapping:
 
 Note that Kartograf does first solve the geometry problem, by finding  atoms
 close to each other for the mapping. Next, it will apply a set of default
-rules, that will remove mappings, that cause a so-called `ring-break`, a
-`ring-size change`, and a `ring-flexibility change`. This default behavior can
-be turned off and/or customized to personal needs (see:ref:`custom-filter-label`).
+rules, that will remove mappings, that cause a so-called ``ring-break``, a
+``ring-size change``, and a ``ring-flexibility change``. This default behavior can
+be turned off and/or customized to personal needs see :ref:`the filtering tutorial <custom-filter-label>`.
 
 Additionally, we could assess the quality of our mapping, there are several
 metrics in Kartograf that can be used to investigate the mapping. Here we are
-going to use the MappingRMSDScorer, which gives insight into how far the atoms
+going to use the :class:`.MappingRMSDScorer`, which gives insight into how far the atoms
 need to travel from one state to the other, if they are mapped onto each
 other::