Merge pull request #17 from OpenFreeEnergy/refactor

Refactor

.gitignore

@@ -94,4 +94,5 @@ dmypy.json
 src/kartograf/_version.py
 
 #IDE
-.idea
+.idea
+/src/kartograf/dev/

README.md

@@ -6,7 +6,8 @@
     </picture>
 </p>
 
-Kartograf: A 3D Atom Graph Mapper
+
+Kartograf: A Geometry-Based Atom Mapper
 ==================================
 
 [//]: # (Badges)
@@ -18,19 +19,28 @@ Kartograf: A 3D Atom Graph Mapper
 [![Pip Install](https://img.shields.io/badge/pip%20install-kartograf-d9c4b1)](https://pypi.org/project/kartograf/)
 [![Conda Install](https://img.shields.io/badge/Conda%20install---c%20conda--forge%20kartograf-009384)](https://anaconda.org/conda-forge/kartograf)
 
+Kartograf is a packgage for atom mappings focussing on 3D geometries.
+This package can be for example be used to generate hybrid topology systems, where an atom mapping is required to determine the core region of the approach.
+But of course there exist also other use cases for this package.
+The atom mapper takes two set of coordinates of molecules as input.
+Optionally those set of coordinates can be aligned onto each other, checkout the `atom_aligner` module functions 
+of Kartograf that offer a shape alignment implementation and a MCS-skeleton alignment.
+The `atom_mapper` can be used to generate the 3D geometry focused atom mapping, the algorithm is described in the related publication of Kartograf (see reference).
+Additionally, rule based filter functions can be provided to demap atoms, that do not fullfill the desired criteria, see `filters`.
+Several mapping scoring metrics are provided, that evaluate geometric properties of your mapping, from `atom_mapping_scorer`, which might be useful for checking quality of your mappings.
+Finally, there is a visualization function `display_mappings_3d` that can be used to check out the mappings with a jupyter notebook widget.
 
-Kartograf offers a geometric atom mapper approach, that allows to map a given set of ligand coordinates. (can be used for hybrid topology  RBFE calculations)
-This package can be used standalone, or from the OpenFE environment.
+You can find our Preprint on [ChemRxiv](https://doi.org/10.26434/chemrxiv-2023-0n1pq) 
 
-**More will be here soon!**
 
 ## Usage
 ```python3
 from rdkit import Chem
-from kartograf.atom_align import align_mol_shape
+from kartograf.atom_aligner import align_mol_shape
+from kartograf.atom_mapping_scorer import MappingRMSDScorer
 from kartograf import KartografAtomMapper, SmallMoleculeComponent
 
-#Preprocessing from Smiles - Here you can add your Input!
+# Preprocessing from Smiles - Here you can add your Input!
 # Generate Data: START
 smiles = ["c1ccccc1", "c1ccccc1(CO)"]
 rdmols = [Chem.MolFromSmiles(s) for s in smiles]
@@ -44,19 +54,25 @@ molA, molB = [SmallMoleculeComponent.from_rdkit(m) for m in rdmols]
 # Align the mols first - this might not needed, depends on input.
 a_molB = align_mol_shape(molB, ref_mol=molA)
 
-
 # Build Kartograf Atom Mapper
 mapper = KartografAtomMapper(atom_map_hydrogens=True)
 
 # Get Mapping
 kartograf_mapping = next(mapper.suggest_mappings(molA, a_molB))
 
+# Score Mapping
+rmsd_scorer = MappingRMSDScorer()
+score = rmsd_scorer(mapping=atom_mapping)
+print(f"RMSD Score: {score}")
+
 kartograf_mapping
 ```
 ![](docs/_static/img/alignment_benz_ol.png)
 
 ## Installation
-you can install Kartograf via the package manager of your choice:
+
+### Latest release
+Kartograf can be installed via the package following package managers:
 
 ```shell
 pip install kartograf
@@ -66,21 +82,30 @@ pip install kartograf
 conda install -c conda-forge kartograf
 ```
 
-Or use Kartograf from the OpenFE Environment (soon).
+Kartograf can be used via the OpenFE environment like:
 
-For Developing Kartograf, you might want to use this approach:
+```python
+from openfe.setup.atom_mapping import kartograf
+```
+
+### Developement version
+The developing setup of Kartograf works like this:
 
 ```shell
 git clone https://github.com/OpenFreeEnergy/kartograf.git
 
 cd kartograf
-conda env create -f environment.yml
+mamba env create -f environment.yml
 
-conda activate kartograf
-pip install .
+mamba activate kartograf
+pip install -e .
 
 ```
-## References
 
+## License
+This library is made available under the MIT open source license.
+
+## Authors
 
+The OpenFE development team.
 

docs/api.rst

@@ -7,5 +7,5 @@ API docs
    :caption: API Contents:
 
    api/atom_mapping
-   api/atom_align
+   api/atom_aligner
 

docs/api/atom_aligner.rst

@@ -0,0 +1,8 @@
+Atom Alignment
+-------------------------
+
+.. autoclass:: kartograf.atom_aligner.align_mol_skeletons
+	       :members:
+
+.. autoclass:: kartograf.atom_aligner.align_mol_shape
+	       :members:

docs/conf.py

@@ -53,8 +53,8 @@
 html_static_path = ['_static']
 html_theme = 'ofe_sphinx_theme'
 
-html_favicon = '_static/img/Kartograf_logo_boxed_dark.ico'
-html_logo = "_static/img/Kartograf_logo_light_transp.png"
+html_favicon = '_static/img/logo/Kartograf_logo_boxed_dark.ico'
+html_logo = "_static/img/logo/Kartograf_logo_light_transp.png"
 html_theme_options = {
     "logo": {
         "text": "Kartograf Documentation",

docs/guide/free_energies_system_representations.rst

@@ -7,6 +7,3 @@ Here is a small Taxonomy that tries to capture them and show benefits and disadv
 (More here soon)
 
 .. image:: ../_static/img/Topology_types.png
-
-References:
-Ries B, Rieder S, Rhiner C, Hünenberger PH, Riniker S. RestraintMaker: a graph-based approach to select distance restraints in free-energy calculations with dual topology. J Comput Aided Mol Des. 2022 Mar; doi: 10.1007/s10822-022-00445-6

pyproject.toml

@@ -12,7 +12,9 @@ authors=[
     {name="Benjamin Ries", email="benjamin-ries@outlook.com"},
     {name="David Swenson", email="dwhswenson@gmail.com"},
     {name="Irfan Alibay", email="irfan.alibay@gmail.com"},
+    {name="Hannah Baumann", email="hannah.baumann@omsf.io"},
     {name="Mike Henry", email="mike.henry@choderalab.org"},
+    {name="James Eastwood", email="james.eastwood@omsf.io"},
     {name="Richard J Gowers", email="richardjgowers@gmail.com"},
 ]
 dependencies = [

src/kartograf/__init__.py

@@ -1,5 +1,19 @@
-# This code is part of OpenFE and is licensed under the MIT license.
+# This code is part of kartograf and is licensed under the MIT license.
 # For details, see https://github.com/OpenFreeEnergy/kartograf
+
 from gufe import SmallMoleculeComponent, ProteinComponent
-from . import filters
 from .atom_mapper import KartografAtomMapper
+from .atom_aligner import (
+    align_mol_skeletons,
+    align_mol_shape,
+)
+from .atom_mapping_scorer import (
+    MappingRMSDScorer,
+    MappingVolumeRatioScorer,
+    MappingShapeOverlapScorer,
+    MappingShapeMismatchScorer,
+)
+
+from . import filters
+
+from .utils.mapping_visualization_widget import display_mappings_3d

src/kartograf/atom_align.py → src/kartograf/atom_aligner.py

@@ -1,3 +1,6 @@
+# This code is part of kartograf and is licensed under the MIT license.
+# For details, see https://github.com/OpenFreeEnergy/kartograf
+
 from copy import deepcopy
 
 from rdkit import Chem
@@ -9,17 +12,17 @@
 
 import logging
 
-log = logging.getLogger(__name__)
+logger = logging.getLogger(__name__)
 
 
-def align_mol_sceletons(
+def align_mol_skeletons(
     mol: SmallMoleculeComponent,
     ref_mol: SmallMoleculeComponent,
 ) -> SmallMoleculeComponent:
-    """
-        WORK IN PROGRESS!
+    """ Alignment based on MCS
         This i a Wrapper for rdkit - MCS align
-        Aligns very simply molecule to the reference molecule, based on the shared MCS.
+        Aligns very simply molecule to the reference molecule,
+        based on the shared MCS - skeleton.
 
     Parameters
     ----------
@@ -64,10 +67,12 @@ def align_mol_sceletons(
     mol._rdkit = mol2b
     return mol
 
-def align_mol_shape(mol:SmallMoleculeComponent, ref_mol:SmallMoleculeComponent)->Chem.Mol:
-    """
-        WORK IN PROGRESS!
-        This i a Wrapper for rdkit / OPEN3DAlign
+
+def align_mol_shape(
+    mol: SmallMoleculeComponent, ref_mol: SmallMoleculeComponent
+) -> Chem.Mol:
+    """ Alignment based on shape
+        This is a Wrapper for rdkit / OPEN3DAlign
         Aligns shape based two SmallMoleculeComponents.
 
     Parameters
@@ -86,9 +91,12 @@ def align_mol_shape(mol:SmallMoleculeComponent, ref_mol:SmallMoleculeComponent)-
 
     mol1b = ref_mol._rdkit
     mol2b = mol._rdkit
-    pyO3A = rdMolAlign.GetO3A(prbMol=mol2b, refMol=mol1b,)
+    pyO3A = rdMolAlign.GetO3A(
+        prbMol=mol2b,
+        refMol=mol1b,
+    )
     score = pyO3A.Align()
-    logging.debug("alignment score: "+str(score))
+    logging.debug(f"alignment score: {score}")
 
     mol._rdkit = mol2b
-    return mol
+    return mol