Merge branch 'main' into make_mapper_tokenizable

.github/workflows/ci.yaml

@@ -13,7 +13,7 @@ concurrency:
 
 defaults:
   run:
-    shell: bash -l {0}
+    shell: bash -leo pipefail {0}
 
 jobs:
   tests:
@@ -22,21 +22,30 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ['ubuntu', 'macos']
+        os: ['ubuntu',]
         python-version:
-          - 3.9
+          - "3.9"
+          - "3.10"
+          - "3.11"
+        include:
+          - os: 'macos'
+            python-version: "3.11" 
 
     steps:
-      - uses: actions/checkout@v2
-
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: actions/checkout@v4
+      - name: Get current date
+        id: date
+        run: echo "date=$(date +%Y-%m-%d)" >> "${GITHUB_OUTPUT}"
+      - uses: mamba-org/setup-micromamba@v1
         with:
-            auto-update-conda: true
-            use-mamba: true
-            python-version: ${{ matrix.python-version }}
-            miniforge-variant: Mambaforge
-            environment-file: environment.yml
-            activate-environment: kartograf
+          environment-file: environment.yml
+          environment-name: kartograf
+          cache-environment: true
+          cache-downloads: true
+          cache-environment-key: environment-${{ steps.date.outputs.date }}
+          cache-downloads-key: downloads-${{ steps.date.outputs.date }}
+          create-args: >-
+            python=${{ matrix.python-version }}
 
       - name: "Install"
         run: pip install --no-deps -e .
@@ -47,11 +56,19 @@ jobs:
           python -Ic "import kartograf"
       - name: "Environment Information"
         run: |
-          mamba info -a
-          mamba list
+          micromamba info 
+          micromamba list
       - name: "Run tests"
         run: |
-          pytest -n 2 -v --cov=kartograf --cov-report=xml
+          pytest -n auto -v --cov=kartograf --cov-report=xml
+      - name: "Test Notebooks"
+        run: |
+          # openfe is a dep for the notebooks example, but not the package
+          micromamba install openfe=0.15
+          # another dep I don't want to include in the env
+          pip install --no-deps git+https://github.com/OpenFreeEnergy/openfe-benchmarks.git
+          # Only need to test the notebook(s) in examples/
+          pytest -v --nbval-lax examples/
       - name: codecov
         if: ${{ github.repository == 'OpenFreeEnergy/kartograf' && github.event != 'schedule'}}
         uses: codecov/codecov-action@v3

README.md

@@ -33,7 +33,11 @@ Finally, there is a visualization function `display_mappings_3d` that can be use
 You can find our Preprint on [ChemRxiv](https://doi.org/10.26434/chemrxiv-2023-0n1pq) 
 
 
+Try our interactive demo: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/OpenFreeEnergy/kartograf/blob/main/examples/kartograf_example.ipynb)
+
+
 ## Usage
+
 ```python3
 from rdkit import Chem
 from kartograf.atom_aligner import align_mol_shape
@@ -62,7 +66,7 @@ kartograf_mapping = next(mapper.suggest_mappings(molA, a_molB))
 
 # Score Mapping
 rmsd_scorer = MappingRMSDScorer()
-score = rmsd_scorer(mapping=atom_mapping)
+score = rmsd_scorer(mapping=kartograf_mapping)
 print(f"RMSD Score: {score}")
 
 kartograf_mapping
@@ -74,10 +78,14 @@ kartograf_mapping
 ### Latest release
 Kartograf can be installed via the package following package managers:
 
+#### `pip` (PyPI)
+
 ```shell
 pip install kartograf
 ```
 
+#### `conda` (conda-forge)
+
 ```shell
 conda install -c conda-forge kartograf
 ```

docs/api.rst

@@ -3,9 +3,13 @@ API docs
 
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
    :caption: API Contents:
 
-   api/atom_mapping
-   api/atom_aligner
+   api/kartograf.mappers
+   api/kartograf.filters
+   api/kartograf.scorers
+   api/kartograf.metrics
+   api/kartograf.aligners
+   api/kartograf.utils
 

docs/api/kartograf.aligners.rst

@@ -0,0 +1,8 @@
+================================
+kartograf.atom\_aligner
+================================
+
+.. automodule:: kartograf.atom_aligner
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/kartograf.filters.rst

@@ -0,0 +1,20 @@
+
+=====================
+kartograf.filters
+=====================
+
+kartograf.filters.element\_change
+----------------------------------------
+
+.. automodule:: kartograf.filters.element_change
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+kartograf.filters.ring\_changes
+--------------------------------------
+
+.. automodule:: kartograf.filters.ring_changes
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/kartograf.mappers.rst

@@ -0,0 +1,8 @@
+=================================
+kartograf.atom\_mapper
+=================================
+
+.. automodule:: kartograf.atom_mapper
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/kartograf.metrics.rst

@@ -0,0 +1,36 @@
+
+===========================
+kartograf.mapping\_metrics
+===========================
+
+kartograf.mapping\_metrics.metric\_mapping\_rmsd
+-------------------------------------------------------
+
+.. automodule:: kartograf.mapping_metrics.metric_mapping_rmsd
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+kartograf.mapping\_metrics.metric\_shape\_difference
+-----------------------------------------------------------
+
+.. automodule:: kartograf.mapping_metrics.metric_shape_difference
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+kartograf.mapping\_metrics.metric\_volume\_ratio
+-------------------------------------------------------
+
+.. automodule:: kartograf.mapping_metrics.metric_volume_ratio
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+kartograf.mapping\_metrics.metrics\_mapping\_comparisons
+---------------------------------------------------------------
+
+.. automodule:: kartograf.mapping_metrics.metrics_mapping_comparisons
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/kartograf.scorers.rst

@@ -0,0 +1,8 @@
+=================================
+kartograf.atom\_mapping\_scorer
+=================================
+
+.. automodule:: kartograf.atom_mapping_scorer
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/kartograf.utils.rst

@@ -0,0 +1,19 @@
+===============
+kartograf.utils
+===============
+
+kartograf.utils.mapping\_visualization\_widget
+-----------------------------------------------------
+
+.. automodule:: kartograf.utils.mapping_visualization_widget
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+kartograf.utils.optional\_imports
+----------------------------------------
+
+.. automodule:: kartograf.utils.optional_imports
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -52,7 +52,7 @@
 
 html_static_path = ['_static']
 html_theme = 'ofe_sphinx_theme'
-
+autoclass_content = 'both'
 html_favicon = '_static/img/logo/Kartograf_logo_boxed_dark.ico'
 html_logo = "_static/img/logo/Kartograf_logo_light_transp.png"
 html_theme_options = {

docs/guide.rst

@@ -1,15 +1,17 @@
 Guide to Kartograf
 =====================
 
-
 .. toctree::
    :maxdepth: 2
    :caption: Applications:
 
-   guide/free_energies_system_representations
+   guide/application_reindexing_problem
+   guide/application_free_energies_system_representations
+
 
 .. toctree::
    :maxdepth: 2
    :caption: Algorithms:
 
    guide/atom_mapping
+   guide/atom_mapping_scoring

docs/guide/application_free_energies_system_representations.rst

@@ -0,0 +1,26 @@
+=======================================
+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
+[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
+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
+the molecules and represents the remaining atom coordinates independent of
+each other.
+
+The usage of Kartograf's atom mapper for this application can be found in the
+turorial: :doc:`/tutorial/mapping_tutorial`.
+
+
+.. [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/application_reindexing_problem.rst

@@ -0,0 +1,16 @@
+=======================================
+Application for Reindexing Problem
+=======================================
+
+Atom indices are important properties of Molecules in any insilico approach.
+However it still sometimes happens, that there are pieces of code, that
+reindex the atoms of a molecule like in the following example:
+
+.. image:: ../_static/img/reindexing_problem_vis.png
+
+If the molecule has a given conformation, that stays unchanged, Kartograf's
+atom mapper can be used to address this problem very easily and precisely! 
+The result here would be the mapping from input to output molecule: `{1:7, 2:4, 3:3, 4:2, 5:1, 6:6, 7:5}`
+
+You can use the code from the mapping tutorial in order to solve this problem:
+:doc:`/tutorial/mapping_tutorial`.

docs/guide/atom_mapping.rst

@@ -1,16 +1,41 @@
+===============================
 Atom Mapping
 ===============================
-The Atom mapper in Kartograf is can be used for hybrid topology approaches in relative free energy calculations.
-The focus of this algorithm is, to use the given input coordinates and use them a given truth, that shall only be minimally modified.
-This allows users to give pre-modelled ligand alignments to the mapping algorithm and always getting a mapping of the molecules,
-that is not changing the input structures significantly.
 
-This approach is very robust, but critically depends on the input structures of course.
+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
+assignment of atoms, between two molecules, which are considered similar/equal
+leading to an MCS estimation.
 
-Additionally can rules be applied during the mapping algorithm, such that for example hydrogens are only mapped on hydrogens or no ring breakage happens in the mappped core.
+For finding such atom mappings multiple different approaches were described
+in the literature. One is to use 2D isomorphic graph problem-solving in order to
+estimate the MCS. Alternatively one can use the 3D geometry information of
+the atoms in order to find such a mapping, like Kartograf does with its atom
+mapper. Kartograf assumes that the input coordinates of the molecules are
+highly overlapping due to prior alignment or modeling approaches before the
+mapping stage is performed. This allows Kartograf to find very efficiently an
+atom mapping with a minimal atom displacement.
 
-(More here soon)
+In the case of classical atom mappings for hybrid topology free energy
+calculations, a core region of the molecules is required. That region is
+actually, a sub-space of the actual atom mapping and it ensures, that all
+mapped atoms are connected via covalent bonds in their original molecule, as
+this might lead to problems in the sampling during the simulations
+(communicating mapped regions).
 
 Approach:
 
 .. image:: ../_static/img/Kartograf_mapping_approach.png
+
+
+Atom Mapping Filters
+---------------------
+
+Additionally, can rules 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.
+
+
+