Merge pull request #47 from OpenFreeEnergy/update_docs

Update docs

README.md

@@ -27,6 +27,10 @@ From a thermodynamic perspective not all transformations are actually required t
 In fact you only need one conection per small molecules to the others in order to get the ranking, like for example in Star Networks or Minimal Spanning Tree (MST) Networks.
 However we found the very efficient networks to be sensitive to transformation failures, this can be solved with network building algorithms, that are slightly more redundant.
 
+Ontop of the described ligand network planners, Konnektor gives access to tools, that allow for example to concatenate networks or delete transformations of a network.
+Analysis of networks, like calculating graph scores, getting the connectivities of network nodes or calculating the network robustness are available too.
+Last we want to bring to your attention our Network visualization tools and the provided interactive network visualization widget for IPython like in Jupyter-Lab/Notebooks.
+
 Try our interactive demo: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/OpenFreeEnergy/konnektor/blob/main/examples/konnektor_example.ipynb#scrollTo=GU32PaMkzD7x)
 
 
@@ -63,10 +67,10 @@ This is achieved by combining the Tools and Network Generator Algorithms, to bui
 
 ```python3
 # Here we generate some input data.
-from openfe_benchmarks import benzenes
+from konnektor.data import get_benzene_ligands
 
 compounds = list(filter(lambda x: not x.name in ["lig_2", "lig_3", "lig_4", "lig_7"],
-                        benzenes.get_system().ligand_components))
+                        get_benzene_ligands()))
 
 # Pick your Favourite Network layout with favourite AtomMapper and Scorer
 from openfe.setup import KartografAtomMapper, lomap_scorers
@@ -81,7 +85,6 @@ network.name = "Cyclic Network"
 
 # Visualize the generated network
 from konnektor.visualization import draw_ligand_network
-
 fig = draw_ligand_network(network=network, title=network.name)
 
 fig.show()

docs/api.rst

@@ -6,5 +6,10 @@ API docs
    :maxdepth: 4
    :caption: API Contents:
 
+   api/konnektor.planners
+   api/konnektor.tools
    api/konnektor.analysis
+   api/konnektor.visualization
+   api/konnektor.utils
+   api/konnektor.data
 

docs/api/konnektor.analysis.rst

@@ -1,8 +1,8 @@
 ================================
-konnektor.network\_planner
+konnektor.network\_analysis
 ================================
 
-.. automodule:: konnektor.network_planners
+.. automodule:: konnektor.network_analysis.network_analysis
    :members:
    :undoc-members:
    :show-inheritance:

docs/api/konnektor.data.rst

@@ -0,0 +1,8 @@
+================================
+konnektor.data
+================================
+
+.. automodule:: konnektor.data
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/konnektor.planners.rst

@@ -0,0 +1,52 @@
+================================
+konnektor.network\_planner
+================================
+
+
+konnektor.network\_planners.generators
+-------------------------------------------------------
+
+.. automodule:: konnektor.network_planners.generators.maximal_network_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_planners.generators.heuristic_maximal_network_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_planners.generators.explicit_network_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_planners.generators.star_network_network_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_planners.generators.minimal_spanning_tree_network_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_planners.generators.cyclic_network_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_planners.generators.clustered_network_generator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+konnektor.network\_planners.concatenators
+-------------------------------------------------------
+
+.. automodule:: konnektor.network_planners.concatenators.mst_concatenator
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/konnektor.tools.rst

@@ -0,0 +1,35 @@
+================================
+konnektor.network\_tools
+================================
+
+konnektor.network\_tools.clustering
+-------------------------------------------------------
+
+.. automodule:: konnektor.network_tools.clustering.charge_clustering
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_tools.clustering.component_diversity_clustering
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+konnektor.network\_tools.network\_handling
+-------------------------------------------------------
+
+.. automodule:: konnektor.network_tools.network_handling.merge
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_tools.network_handling.concatenate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. automodule:: konnektor.network_tools.network_handling.delete
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/konnektor.utils.rst

@@ -0,0 +1,8 @@
+================================
+konnektor.utils
+================================
+
+.. automodule:: konnektor.utils.toy_data
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/api/konnektor.visualization.rst

@@ -0,0 +1,19 @@
+================================
+konnektor.visualization
+================================
+
+konnektor.network\_visualiztion.visualization
+-------------------------------------------------------
+
+.. automodule:: konnektor.visualization.visualization
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+konnektor.network\_visualiztion.widget
+-------------------------------------------------------
+
+.. automodule:: konnektor.visualization.widget
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/guide.rst

@@ -1,16 +1,4 @@
 Guide to Konnektor
 =====================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Applications:
-
-   guide/application_free_energies_system_representations
-
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Algorithms:
-
-   guide/mst_network_planner
-
+More will be here soon!

docs/index.rst

@@ -1,23 +1,20 @@
 Welcome to Konnektors's documentation!
 =========================================
-Kartograf is a packgage for atom mappings focussing on 3D geometries.
-This package can 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 sets of coordinates of molecules as input.
-Optionally those sets of coordinates can be aligned onto each other, checkout
-the ``atom_aligner`` module functions
-of Kartograf that offer a shape alignment implementation and an 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 fulfill 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 the 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.
 
-You can find our Preprint on `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://doi.org/10.26434/chemrxiv-2023-0n1pq>`_
+Konnektor is a package supporting you in planning your free calculations.
+It contains multiple algorithms and tools for network planning, that make setting up the calculation plans much easier.
+As an example imagen you are given a set of drug candidates that shall be ranked with relative binding free energies.
+In theory you could calculate all the possible network transformations, in order to get your ligand ranking (we call this a Maximal Network).
+However this leads to an explosion in time and compute cost, therefore we need more efficient ways on how to caluclate a drug candidate ranking.
+From a thermodynamic perspective not all transformations are actually required to retrieve a ranking.
+In fact you only need one conection per small molecules to the others in order to get the ranking, like for example in Star Networks or Minimal Spanning Tree (MST) Networks.
+However we found the very efficient networks to be sensitive to transformation failures, this can be solved with network building algorithms, that are slightly more redundant.
+
+Ontop of the described ligand network planners, Konnektor gives access to tools, that allow for example to concatenate networks or delete transformations of a network.
+Analysis of networks, like calculating graph scores, getting the connectivities of network nodes or calculating the network robustness are available too.
+Last we want to bring to your attention our Network visualization tools and the provided interactive network visualization widget for IPython like in Jupyter-Lab/Notebooks.
+
+Try our interactive demo: ![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)
 
 .. toctree::
    :maxdepth: 2

docs/install.rst

@@ -5,14 +5,13 @@ Installation
 User Setup
 =============
 
-Kartograf will be packaged with OpenFE but we need more time for that. :)
-
-Alternatively, you can install Kartograf also as a standalone package via pip
-or soon conda:
-
-``pip install konnektor``
+Konnektor will be packaged with OpenFE, soon. :)
 
+Konnektor can be installed via the package following package managers:
 
+```shell
+pip install konnnektor
+```
 
 Developer Setup
 ================

docs/tutorial/building_networks.rst

@@ -1,2 +1,56 @@
-building networks
+Building Networks
 -----------------
+In this tutorial, it will be shown, how a `LigandNetwork` can be planned using Konnektor.
+Please be aware, that the openfe package is required in your python environment.
+You can easily install it with: `pip install openfe`.
+
+In the first step, we will create some small molecules, that we want to plan our `LigandNetwork` with and we will generate an `AtomMapper` and `AtomMappingScorer`.
+The `AtomMapper` will generate all possible alchemical transformations for the set of molecules, translating to the network edges.
+Next, the `AtomMappingScorer` will add the weights to the edges, by expressing on how difficult the transformation will be. This score is between 0, very hard to compute, and 1 for easy to compute::
+
+    # Build Small Molecules
+    from konnektor.data import get_benzene_ligands
+    compounds = list(filter(lambda x: not x.name in ["lig_2", "lig_3", "lig_4", "lig_7"],
+                            get_benzene_ligands()))
+
+    # Build Atom Mapper and AtomMappingScorer
+    from openfe.setup import KartografAtomMapper, lomap_scorers
+    mapper = KartografAtomMapper()
+    scorer = lomap_scorers.default_lomap_score
+
+After having the components setup, we can go and plan our network! Here we use the `CylicNetworkGenerator`.
+But of course you can use any `NetworkGenerator` from Konnektor in exactly the same way.::
+
+        # Plan the Network
+        from konnektor.network_planners import CyclicNetworkGenerator
+
+        networker = CyclicNetworkGenerator(mapper=mapper,
+                                           scorer=scorer,
+                                           n_processes=1)
+
+        network = networker.generate_ligand_network(compounds)
+
+In Order to visualize the Network Konnektor provides you several options.
+First, you can translate the network into a `matplotlib.pyplot.Figure` with the function `draw_ligand_network`.::
+
+        # Visualize the generated network
+        from konnektor.visualization import draw_ligand_network
+        fig = draw_ligand_network(network=network, title=network.name)
+
+        fig.show()
+
+This yields the following visualization:
+
+.. image:: ../_static/img/cyclic_graph_pyplot_fig.png
+
+As alternative, Konnektor offers an interactive IPython widget, that allows you interactivley to explore your network.::
+
+    # Visualize the generated network in a widget
+    from konnektor.visualization import draw_network_widget
+    widget = draw_network_widget(network=network)
+    widget
+
+This yields the following visualization:
+
+.. image:: ../_static/img/cyclic_graph_ipy_widget.png
+

src/konnektor/__init__.py

@@ -11,8 +11,9 @@
                                StarrySkyNetworkGenerator,
                                MstConcatenator,
                                )
-from .network_tools import concatenate, merge, append_node, \
-    delete_transformation, delete_component
+
+from .network_tools import merge_networks, concatenate_networks, \
+    append_component, delete_component, delete_transformation
 
 from . import network_analysis
 from .visualization import draw_ligand_network

src/konnektor/network_planners/generators/clustered_network_generator.py

@@ -19,7 +19,7 @@
 from .cyclic_network_generator import CyclicNetworkGenerator
 from .star_network_generator import StarNetworkGenerator
 from ..concatenators import MstConcatenator
-from ...network_tools import append_node, concatenate_networks
+from ...network_tools import append_component, concatenate_networks
 from ...network_tools.clustering._abstract_clusterer import _AbstractClusterer
 
 log = logging.getLogger()
@@ -163,9 +163,9 @@ def generate_ligand_network(self,
                 progress = lambda x: x
 
             for mol in progress(self.clusters[-1]):
-                concat_network = append_node(network=concat_network,
-                                             component=mol,
-                                             concatenator=self.concatenator)
+                concat_network = append_component(network=concat_network,
+                                                  component=mol,
+                                                  concatenator=self.concatenator)
 
         return concat_network
 

src/konnektor/network_tools/__init__.py

@@ -1,6 +1,6 @@
 from .clustering.charge_clustering import ChargeClusterer
 from .clustering.component_diversity_clustering import \
     ComponentsDiversityClusterer
-from .concatenate import concatenate_networks, append_node
-from .merge import merge_two_networks
-from .misc import delete_transformation, delete_component
+
+from .network_handling import merge_networks, concatenate_networks, \
+    append_component, delete_component, delete_transformation

src/konnektor/network_tools/network_handling/__init__.py

@@ -0,0 +1,6 @@
+# This code is part of OpenFE and is licensed under the MIT license.
+# For details, see https://github.com/OpenFreeEnergy/konnektor
+
+from .concatenate import concatenate_networks, append_component
+from .delete import delete_transformation, delete_component
+from .merge import merge_networks, merge_two_networks