From 5549ef87a5014537fb21a4c4c031332f0328c92f Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 12 Jun 2026 15:12:19 +0200 Subject: [PATCH 1/6] Update README.md --- README.md | 133 ++++++++++++++++++++---------------------------------- 1 file changed, 49 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index a583417..52a7ff2 100644 --- a/README.md +++ b/README.md @@ -2,112 +2,77 @@ [![Documentation Status](https://readthedocs.org/projects/lomap/badge/?version=latest)](https://lomap.readthedocs.io/en/latest/?badge=latest) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8344248.svg)](https://doi.org/10.5281/zenodo.16898468) # Lomap -Alchemical free energy calculations hold increasing promise -as an aid to drug discovery efforts. However, applications of -these techniques in discovery projects have been relatively -rare, partly because of the difficulty of planning and setting up -calculations. The lead optimization mapper (LOMAP) was -introduced as an automated algorithm to plan efficient relative -free energy calculations between potential ligands within -a substantial set of compounds. The original LOMAP code was mainly -based on commercial APIs such as OpenEye and Schrodinger. The aim -of this project is to develop a new version of LOMAP based on freely -available APIs such as RDKit offering the scientific community a -free tool to plan in advance binding free energy calculations. - -## Prerequisites -* RDKit Release > 2021 -* NetworkX -* Matplotlib -* python > 3.8 - -Authors -------- - -See [AUTHORS.md](https://github.com/OpenFreeEnergy/Lomap/blob/main/AUTHORS.md) - +The Lead Optimization Mapper (LOMAP) is an automated algorithm for planning +efficient relative free energy calculation networks across a set of ligands, +built on freely available tools such as RDKit. +With the optional [`gufe`](https://github.com/OpenFreeEnergy/gufe) dependency installed, +it also integrates with the [Open Free Energy](https://openfree.energy) ecosystem. . ## Installation ### Latest Release -You can install using conda (or mamba). Note the package name is `lomap2`: -`conda install -c conda-forge lomap2` +From conda-forge (note the package name is `lomap2`): + +```bash +conda install -c conda-forge lomap2 +``` + +The modern mapping and network API (see below) additionally requires +[`gufe`](https://github.com/OpenFreeEnergy/gufe): + +```bash +conda install -c conda-forge gufe +``` ### Development Version Alternatively, you can install the development version of `lomap` directly from the `main` branch of this repository. -First install the package dependencies using conda (or mamba) in a virtual environment with: - ```bash conda env create -f environment.yaml conda activate lomap-env +pip install -e . ``` -Then install `lomap` locally with: - -`pip install -e .` - -Usage ------ -As a command line tool, LOMAP can be simply used as: -` -lomap test/basic/ -` +Quickstart +---------- -For a basic example run: -`python examples/example.py` - -For generating radial graphs with a hub, run: -`python examples/example_radial.py` - -If you would rather use the API directly, try: +This example loads two ligands from SDF files and plans a perturbation network between +them using LOMAP's default mapper and scorer. ```python -import lomap +import importlib.resources -# Generate the molecule database starting from a directory containing .mol2 files - -db_mol = lomap.DBMolecules("python string pointing to a directory with mol2 files", output=True) - -#More graphing options: -# Use the complete radial graph option. The ligand with the most structural similarity to all of the others will be picked as the 'lead compound' and used as the central compound. -db_mol = lomap.DBMolecules("python string pointing to a directory with mol2 files", output=True, radial=True) - -# Use a radial graph with a manually specified hub compound -db_mol = lomap.DBMolecules("python string pointing to a directory with mol2 files", output=True, radial=True, hub=filename.mol2) - -# Use a radial graph with a manually specified hub compound and fast graphing option -#the fast graphing option creates the initial graph by connecting the hub ligand with the possible surrounding ligands and adds surrounding edges based on the similarities across surrounding nodes -db_mol = lomap.DBMolecules("python string pointing to a directory with mol2 files", output=True, radial=True, hub=filename.mol2, fast=True) - -# Calculate the similarity matrix between the database molecules. Two molecules are generated -# related to the strict rule and loose rule - -strict, loose = db_mol.build_matrices() - -# Generate the NetworkX graph and output the results -nx_graph = db_mol.build_graph() - - -# Calculate the Maximum Common Subgraph (MCS) between -# the first two molecules in the molecule database -# ignoring hydrogens and depicting the mapping in a file - -MC = lomap.MCS.getMapping(db_mol[0].getMolecule(), db_mol[1].getMolecule(), hydrogens=False, fname='mcs.png') +import lomap +from gufe import SmallMoleculeComponent + +# Two example ligands ship with the package under lomap.tests.data +data = importlib.resources.files("lomap.tests.data") +ligands = [ + SmallMoleculeComponent.from_sdf_file(data / name) + for name in ["lig_41.sdf", "lig_74.sdf"] +] + +# Build a LigandNetwork using LOMAP's scoring and network-construction rules +network = lomap.generate_lomap_network( + ligands=ligands, + mappers=lomap.LomapAtomMapper(), + scorer=lomap.default_lomap_score, +) +print(f"{len(network.nodes)} ligands, {len(network.edges)} edges") +``` +## Deprecated APIs -# Alchemical transformation are usually performed between molecules with -# the same charges. However, it is possible to allow this transformation -# manually setting the electrostatic score for the whole set of molecules -# producing a connected graph. The electrostatic score must be in the -# range [0,1] +The legacy `DBMolecules` API and CLI are deprecated +and will be removed in the next major release; new code should use +`generate_lomap_network` instead. See +[issue #138](https://github.com/OpenFreeEnergy/Lomap/issues/138) and the +[legacy documentation](https://lomap.readthedocs.io/en/latest/legacy.html). +## Authors -db_mol = lomap.DBMolecules("python string pointing to a directory with mol2 files", output=True, ecrscore=0.1) -strict, loose = db_mol.build_matrices() -nx_graph = db_mol.build_graph() -``` +See [AUTHORS.md](https://github.com/OpenFreeEnergy/Lomap/blob/main/AUTHORS.md). ## History From 352abd2efceb259fe34530085f5a5bc9515f5786 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 12 Jun 2026 13:18:13 +0000 Subject: [PATCH 2/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 52a7ff2..3617b1a 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ # Lomap The Lead Optimization Mapper (LOMAP) is an automated algorithm for planning efficient relative free energy calculation networks across a set of ligands, -built on freely available tools such as RDKit. -With the optional [`gufe`](https://github.com/OpenFreeEnergy/gufe) dependency installed, +built on freely available tools such as RDKit. +With the optional [`gufe`](https://github.com/OpenFreeEnergy/gufe) dependency installed, it also integrates with the [Open Free Energy](https://openfree.energy) ecosystem. . ## Installation @@ -37,7 +37,7 @@ pip install -e . Quickstart ---------- -This example loads two ligands from SDF files and plans a perturbation network between +This example loads two ligands from SDF files and plans a perturbation network between them using LOMAP's default mapper and scorer. ```python From ac7b1b0ada6facc3e07168c451f9f6d3451910e5 Mon Sep 17 00:00:00 2001 From: Hannah Baumann <43765638+hannahbaumann@users.noreply.github.com> Date: Fri, 12 Jun 2026 16:58:24 +0200 Subject: [PATCH 3/6] Update README.md Co-authored-by: Josh Horton --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 3617b1a..091309d 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ Quickstart ---------- This example loads two ligands from SDF files and plans a perturbation network between -them using LOMAP's default mapper and scorer. +them using LOMAP's default atom mapper and scorer. ```python import importlib.resources From 58b77e18c21e4f84fb2439fa0225865ba7684945 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Fri, 12 Jun 2026 17:15:05 +0200 Subject: [PATCH 4/6] Address review comments --- README.md | 41 ++++++++++++++++++++++++++++++++++------- 1 file changed, 34 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 091309d..998d93e 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,14 @@ [![CI](https://github.com/OpenFreeEnergy/Lomap/actions/workflows/CI.yaml/badge.svg)](https://github.com/OpenFreeEnergy/Lomap/actions/workflows/CI.yaml) [![Documentation Status](https://readthedocs.org/projects/lomap/badge/?version=latest)](https://lomap.readthedocs.io/en/latest/?badge=latest) -[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.8344248.svg)](https://doi.org/10.5281/zenodo.16898468) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16898468.svg)](https://doi.org/10.5281/zenodo.16898468) # Lomap The Lead Optimization Mapper (LOMAP) is an automated algorithm for planning efficient relative free energy calculation networks across a set of ligands, -built on freely available tools such as RDKit. -With the optional [`gufe`](https://github.com/OpenFreeEnergy/gufe) dependency installed, -it also integrates with the [Open Free Energy](https://openfree.energy) ecosystem. . +built on freely available tools such as RDKit. +With the optional [`gufe`](https://github.com/OpenFreeEnergy/gufe) dependency installed, +it also integrates with the [Open Free Energy](https://openfree.energy) ecosystem. +The method is described in the original +[LOMAP publication](https://doi.org/10.1007/s10822-013-9678-y). ## Installation @@ -16,14 +18,39 @@ From conda-forge (note the package name is `lomap2`): ```bash conda install -c conda-forge lomap2 +# or, equivalently +mamba install -c conda-forge lomap2 ``` -The modern mapping and network API (see below) additionally requires -[`gufe`](https://github.com/OpenFreeEnergy/gufe): - +## Optional dependencies + +`lomap` has optional dependencies that extend its capabilities: + +### gufe + +The atom mapping, scoring, and network-planning API is provided through optional +[`gufe`](https://gufe.openfree.energy/en/latest/) bindings, which let `lomap` +interoperate seamlessly with the rest of the +[Open Free Energy ecosystem](https://openfree.energy/projects): + ```bash conda install -c conda-forge gufe ``` + +See the [gufe bindings API +documentation](https://lomap.readthedocs.io/en/latest/api.html#gufe-bindings-api) +for how to use them. + +### pygraphviz + +The `GraphGen` class can plot the network graph through its `draw()` method, +which requires [pygraphviz](https://pygraphviz.github.io/): + +```bash +conda install -c conda-forge pygraphviz +# or +python -m pip install pygraphviz +``` ### Development Version Alternatively, you can install the development version of `lomap` directly from the `main` branch of this repository. From 66cc0628abc1503069b41ef69e17a59d5f65aac6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 12 Jun 2026 15:26:22 +0000 Subject: [PATCH 5/6] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- README.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 998d93e..ad5d57b 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,8 @@ # Lomap The Lead Optimization Mapper (LOMAP) is an automated algorithm for planning efficient relative free energy calculation networks across a set of ligands, -built on freely available tools such as RDKit. -With the optional [`gufe`](https://github.com/OpenFreeEnergy/gufe) dependency installed, +built on freely available tools such as RDKit. +With the optional [`gufe`](https://github.com/OpenFreeEnergy/gufe) dependency installed, it also integrates with the [Open Free Energy](https://openfree.energy) ecosystem. The method is described in the original [LOMAP publication](https://doi.org/10.1007/s10822-013-9678-y). @@ -23,29 +23,29 @@ mamba install -c conda-forge lomap2 ``` ## Optional dependencies - + `lomap` has optional dependencies that extend its capabilities: - + ### gufe - + The atom mapping, scoring, and network-planning API is provided through optional [`gufe`](https://gufe.openfree.energy/en/latest/) bindings, which let `lomap` interoperate seamlessly with the rest of the [Open Free Energy ecosystem](https://openfree.energy/projects): - + ```bash conda install -c conda-forge gufe ``` - + See the [gufe bindings API documentation](https://lomap.readthedocs.io/en/latest/api.html#gufe-bindings-api) for how to use them. - + ### pygraphviz - + The `GraphGen` class can plot the network graph through its `draw()` method, which requires [pygraphviz](https://pygraphviz.github.io/): - + ```bash conda install -c conda-forge pygraphviz # or From 3384a8c661f3acc150b0d2a64639b5d1c2d3a6f0 Mon Sep 17 00:00:00 2001 From: hannahbaumann Date: Mon, 15 Jun 2026 11:26:17 +0200 Subject: [PATCH 6/6] Address review comments --- README.md | 70 +++++++++---------------------------------------------- 1 file changed, 11 insertions(+), 59 deletions(-) diff --git a/README.md b/README.md index 998d93e..e9a102a 100644 --- a/README.md +++ b/README.md @@ -12,62 +12,19 @@ The method is described in the original ## Installation -### Latest Release +`lomap` is available on conda-forge as the `lomap2` package. See the +[installation documentation](https://lomap.readthedocs.io/en/latest/installation.html) +for install instructions, including the development install and optional +dependencies (`gufe` and `pygraphviz`). -From conda-forge (note the package name is `lomap2`): +## Quickstart -```bash -conda install -c conda-forge lomap2 -# or, equivalently -mamba install -c conda-forge lomap2 -``` - -## Optional dependencies - -`lomap` has optional dependencies that extend its capabilities: - -### gufe - -The atom mapping, scoring, and network-planning API is provided through optional -[`gufe`](https://gufe.openfree.energy/en/latest/) bindings, which let `lomap` -interoperate seamlessly with the rest of the -[Open Free Energy ecosystem](https://openfree.energy/projects): - -```bash -conda install -c conda-forge gufe -``` - -See the [gufe bindings API -documentation](https://lomap.readthedocs.io/en/latest/api.html#gufe-bindings-api) -for how to use them. - -### pygraphviz - -The `GraphGen` class can plot the network graph through its `draw()` method, -which requires [pygraphviz](https://pygraphviz.github.io/): - -```bash -conda install -c conda-forge pygraphviz -# or -python -m pip install pygraphviz -``` - -### Development Version -Alternatively, you can install the development version of `lomap` directly from the `main` branch of this repository. - -```bash -conda env create -f environment.yaml -conda activate lomap-env -pip install -e . -``` - -Quickstart ----------- - -This example loads two ligands from SDF files and plans a perturbation network between -them using LOMAP's default atom mapper and scorer. +This example uses LOMAP's optional `gufe` bindings to load two example ligands +bundled with the package and plan a perturbation network between them with the +default mapper and scorer. ```python +# requires the optional `gufe` dependency (see Installation) import importlib.resources import lomap @@ -89,13 +46,8 @@ network = lomap.generate_lomap_network( print(f"{len(network.nodes)} ligands, {len(network.edges)} edges") ``` -## Deprecated APIs - -The legacy `DBMolecules` API and CLI are deprecated -and will be removed in the next major release; new code should use -`generate_lomap_network` instead. See -[issue #138](https://github.com/OpenFreeEnergy/Lomap/issues/138) and the -[legacy documentation](https://lomap.readthedocs.io/en/latest/legacy.html). +For proposing individual mappings, customising edge scores, and the full set of +network options, see the [documentation](https://lomap.readthedocs.io). ## Authors