From 26b75b27784dad351026d8ee006d80bfb8de2c4a Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Mon, 18 Nov 2024 13:49:04 +0000 Subject: [PATCH 1/4] docs links and highlights clean up, minor text changes --- ...n_free_energies_system_representations.rst | 8 ++++--- docs/guide/atom_mapping.rst | 10 ++++---- docs/guide/atom_mapping_scoring.rst | 8 +++---- docs/tutorial/custom_filters.rst | 23 ++++++++++++------- docs/tutorial/fused_rings.rst | 2 +- docs/tutorial/mapping_tutorial.rst | 8 +++---- 6 files changed, 34 insertions(+), 25 deletions(-) diff --git a/docs/guide/application_free_energies_system_representations.rst b/docs/guide/application_free_energies_system_representations.rst index 837e8ca..83ed942 100644 --- a/docs/guide/application_free_energies_system_representations.rst +++ b/docs/guide/application_free_energies_system_representations.rst @@ -4,13 +4,13 @@ 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 +capture them and show benefits and disadvantages (more 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 approach 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 diff --git a/docs/guide/atom_mapping.rst b/docs/guide/atom_mapping.rst index 4a6ab42..59b7a18 100644 --- a/docs/guide/atom_mapping.rst +++ b/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 `. diff --git a/docs/guide/atom_mapping_scoring.rst b/docs/guide/atom_mapping_scoring.rst index 676d0c1..1ca2c4f 100644 --- a/docs/guide/atom_mapping_scoring.rst +++ b/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. diff --git a/docs/tutorial/custom_filters.rst b/docs/tutorial/custom_filters.rst index 1800acd..6f39ae3 100644 --- a/docs/tutorial/custom_filters.rst +++ b/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 diff --git a/docs/tutorial/fused_rings.rst b/docs/tutorial/fused_rings.rst index 7dfd6b5..f379be6 100644 --- a/docs/tutorial/fused_rings.rst +++ b/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:: diff --git a/docs/tutorial/mapping_tutorial.rst b/docs/tutorial/mapping_tutorial.rst index a48be60..cb0b0a9 100644 --- a/docs/tutorial/mapping_tutorial.rst +++ b/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 `. 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:: From 84a674af29ff40b2756863b943786975b68b4731 Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Wed, 20 Nov 2024 09:15:43 +0000 Subject: [PATCH 2/4] Update docs/guide/application_free_energies_system_representations.rst Co-authored-by: Irfan Alibay --- docs/guide/application_free_energies_system_representations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/application_free_energies_system_representations.rst b/docs/guide/application_free_energies_system_representations.rst index 83ed942..e03dd09 100644 --- a/docs/guide/application_free_energies_system_representations.rst +++ b/docs/guide/application_free_energies_system_representations.rst @@ -3,7 +3,7 @@ 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 +during a free energy calculation. Here is a small taxonomy that tries to capture them and show benefits and disadvantages (more can be found in [1]_ [2]_): From eccb1ea398b9f18502a6b78b9d488cb177f13e35 Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Wed, 20 Nov 2024 09:15:53 +0000 Subject: [PATCH 3/4] Update docs/guide/application_free_energies_system_representations.rst Co-authored-by: Irfan Alibay --- docs/guide/application_free_energies_system_representations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/application_free_energies_system_representations.rst b/docs/guide/application_free_energies_system_representations.rst index e03dd09..ff6ab18 100644 --- a/docs/guide/application_free_energies_system_representations.rst +++ b/docs/guide/application_free_energies_system_representations.rst @@ -4,7 +4,7 @@ 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 can be found in +capture them and show benefits and disadvantages (more information can be found in [1]_ [2]_): .. image:: ../_static/img/Topology_types.png From 013e8f63e0121899e218ef0dea6d68d40b9eaadc Mon Sep 17 00:00:00 2001 From: Josh Horton Date: Wed, 20 Nov 2024 09:16:00 +0000 Subject: [PATCH 4/4] Update docs/guide/application_free_energies_system_representations.rst Co-authored-by: Irfan Alibay --- docs/guide/application_free_energies_system_representations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/application_free_energies_system_representations.rst b/docs/guide/application_free_energies_system_representations.rst index ff6ab18..db60fd9 100644 --- a/docs/guide/application_free_energies_system_representations.rst +++ b/docs/guide/application_free_energies_system_representations.rst @@ -9,7 +9,7 @@ capture them and show benefits and disadvantages (more information can be found .. image:: ../_static/img/Topology_types.png -The hybrid and single topology approach depend heavily +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