diff --git a/docs/_static/img/advanced_network_planning.png b/docs/_static/img/advanced_network_planning.png new file mode 100644 index 0000000..30421d0 Binary files /dev/null and b/docs/_static/img/advanced_network_planning.png differ diff --git a/docs/_static/img/networks.png b/docs/_static/img/networks.png new file mode 100644 index 0000000..96c5df7 Binary files /dev/null and b/docs/_static/img/networks.png differ diff --git a/docs/guide.rst b/docs/guide.rst index ac37ea0..d2c92f6 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -1,4 +1,17 @@ Guide to Konnektor ===================== -More will be here soon! \ No newline at end of file +.. toctree:: + :maxdepth: 2 + :caption: Applications: + + guide/application_network_planning_fe_calculations + + +.. toctree:: + :maxdepth: 2 + :caption: Functionality: + + guide/network_planner + guide/node_clusterer + guide/edge_intermediator diff --git a/docs/guide/application_network_planning_fe_calculations.rst b/docs/guide/application_network_planning_fe_calculations.rst new file mode 100644 index 0000000..89708be --- /dev/null +++ b/docs/guide/application_network_planning_fe_calculations.rst @@ -0,0 +1,50 @@ +============================================================== +Network Plannnig for Free Energy Calculations in Drug Design +============================================================== + +In this section, we will explore a classical hands-on drug design example, +specifically the search for the best small molecule to inhibit a protein for drug development. +Typically, drug design project teams and computational chemists generate a large +number of molecule designs from which they must determine relevance. + +While experimental testing can evaluate various properties of these molecules, +it is can be more efficient to use computational methods to distinguish between +relevant and irrelevant candidates. +The computational chemist usually follows a workflow that starts with very fast +methods to filter out the obvious molecules (in the range of hundreds of thousands), +then progresses to more computationally expensive methods that are more accurate +but can only be applied to smaller sets of molecules (usually in the hundreds). + +Relative free energy calculation methods using alchemical MD simulations fall on +the more computationally expensive side of the spectrum. Therefore, making the calculations +efficient is crucial to avoid wasting time and computing resources. +But how can these calculations be made efficient? + +This is a multi-layered question, starting with methodological aspects such as +improving sampling speed or reducing timestep calculation time through parallel +approaches on GPUs. At a higher level, the required number of calculations can +also be adjusted. This is where Konnektor comes into play, helping you optimize this process. + +In general, there is a trade-off to consider in the calculation network +between efficiency regarding the number of edges and redundancy within the +network. Ideally, a minimal number of edges, such as in a Star Network or +Minimal Spanning Tree (MST) Network, would make calculations most efficient. +However, sometimes an edge calculation may fail due to poor edge selection, +leading to a disconnected network, which results in an incomplete molecule +ranking. + +These failures can arise from factors that were not accounted for during the +selection process, such as unforeseen issues or computational outages, like +a node crash. To address this, redundancy can help ensure immediate +resolution of disconnections. Additionally, redundancy can be utilized to +estimate simulation errors through cycle closure analysis, which can also +enhance the final results. + +More redundant networks include the Twin Star Network, Redundant MST +Network, N-Node Edges Network, and Cyclic Network. Notably, the Twin Star +Network and the Cyclic Network focus on constructing a set of cycles. + +So in applied cases we suggest the slightly more redundant networks in order to build up a robust network for the calculations. + +turorial: :doc:`/tutorial/building_networks`. +NetworkPlanner: :doc:`/guide/network_planner`. diff --git a/docs/guide/edge_intermediator.rst b/docs/guide/edge_intermediator.rst new file mode 100644 index 0000000..b07c1e8 --- /dev/null +++ b/docs/guide/edge_intermediator.rst @@ -0,0 +1,9 @@ +============================================================== +Edge Intermediate Generator +============================================================== + +To overcome large molecular differences, it can be helpful to create an +intermediate state between two molecules. Classes that perform this task +are called Intermediator in Konnektor. You can provide them with two +`Component`s, and they will attempt to construct intermediate states +between the two `Component`s. diff --git a/docs/guide/network_planner.rst b/docs/guide/network_planner.rst new file mode 100644 index 0000000..1a2d76f --- /dev/null +++ b/docs/guide/network_planner.rst @@ -0,0 +1,76 @@ +============================================================== +Network Planners +============================================================== +Building a drug candidate ranking is essentially a graph or network +construction problem. A connected network, with candidates as nodes, can +describe all the relationships among each candidate. The relationship +between two molecules corresponds to an edge in this network, which +translates to one Relative Binding Free Energy (RBFE) calculation. In +practice, computational chemists conduct numerous RBFE calculations to +construct networks that illustrate the relationships of all drug candidates +to one another. + +.. image:: ../_static/img/networks.png + +It's important to note that free energy is a thermodynamic state function, +making it path independent. This means that a network only needs to be +connected to provide insights into all relationships, provided all RBFE +calculations are of high quality. For example, if molecule A has a direct +relation x with molecule C, and they are connected through molecule B, +using relations y and z, then the sum of y + z will still yield x. + +So, what can we do with this? As mentioned, the free energy network should +be calculated efficiently. Keep in mind that computational chemists utilize +high-performance computing resources to perform RBFE calculations, which +can take several hours. Therefore, RBFE calculations are costly, and it is +typically avoided to conduct too many. + +This consideration directly impacts the design of the free energy network. +To orchestrate the calculations, a plan for which connections to compute is +generated before the simulations. This is where Konnektor comes into play. + +Konnektor is a package that assists in generating the free energy network +calculation plan. It implements multiple network layouts, each with its +own advantages and disadvantages. How is such a network plan generated? +In our RBFE calculation example, each edge can be represented as an +`AtomMapping`, indicating a common substructure between the two molecules +to be compared. This `AtomMapping` can then be scored using an +`AtomMappingScorer`, which indicates the expected difficulty of the +transformation in terms of convergence or accuracy. But you can also look at +this more abstract, as an `ComponentMapping` is describing any relation between two +`Component`s and the difficulty is estimated with a `ComponentMappingScorer`. + +A network planning algorithm `NetworkPlanner` can now use these scores along with graph +construction algorithms to identify the best calculation paths. + +Checkout the network tools to see what you can additionally do with networks. + +Network Generators +__________________ +Network Generators are planners that construct networks from a set of +components. They are usually the starting point for any network planning +efforts and come in a wide variety of layouts: + +The minimal number of edges for ranking can be achieved with the Star +Network and the Minimal Spanning Tree (MST) Network (N-1). More +redundant layouts include the Twin Star Network, Redundant MST Network, +N-Edge Node Network, and Cyclic Graph Network. + +The Maximal Network method generates all possible edges and is typically +used as an initial solution, which then gets reduced to a more efficent layout. +Additionally, there is the Heuristic Maximal Network, which aims to produce an +edge-reduced version of the Maximal Network. + +.. image:: ../_static/img/network_layouts.png + + +Network Concatenators +______________________ +NetworkConcatenators address the challenge of connecting two networks that +do not share any edges. This essentially involves solving a bipartite graph +matching problem. These planners generate edges between two unconnected, +non-overlapping networks to create a connected network. + +Currently, there are two Network Concatenators in Konnektor: the Maximal +Concatenator, which yields all possible edges, and the Minimal Spanning +Tree Concatenator, which utilizes the best-performing edge scores. diff --git a/docs/guide/node_clusterer.rst b/docs/guide/node_clusterer.rst new file mode 100644 index 0000000..fb67d27 --- /dev/null +++ b/docs/guide/node_clusterer.rst @@ -0,0 +1,12 @@ +============================================================== +Node Clusterer +============================================================== +To separate a collection of Components by a specific property, the +`Clusterer` classes can be utilized. They serve as powerful tools within +a workflow and are, for example, part of the Starry Sky Network. + +In Konnektor, the following clustering classes are currently available: + +* `ChargeClusterer` – separates molecules by net charge changes +* `ScaffoldClusterer` – separates molecules by shared scaffolds +* `DiversityClusterer` – uses fingerprints to cluster the different molecules. diff --git a/docs/install.rst b/docs/install.rst index 0e1fca7..25cac54 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -10,7 +10,7 @@ Konnektor will be packaged with OpenFE, soon. :) Konnektor can be installed via the package following package managers: ```shell -pip install konnnektor +mamba -c -conda-forge install konnektor ``` Developer Setup diff --git a/environment.yml b/environment.yml index 8a10e17..37e2349 100644 --- a/environment.yml +++ b/environment.yml @@ -31,4 +31,4 @@ dependencies: - pip: - dill - scikit-mol - - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@main \ No newline at end of file + - git+https://github.com/OpenFreeEnergy/ofe-sphinx-theme@a45f3edd5bc3e973c1a01b577c71efa1b62a65d6