# *ShEPhERD* Scoring Functions
This repository contains the code for **generating/optimizing conformers**, **extracting interaction profiles**, **aligning interaction profiles**, and **differentiably scoring 3D similarity**. It also contains modules to evaluate conformers generated with *ShEPhERD*<sup>1</sup> and other generative models.
The formulation of the interaction profile representation, scoring, alignment, and evaluations are found in our preprint [*ShEPhERD*: Diffusing shape, electrostatics, and pharmacophores for bioisosteric drug design](https://arxiv.org/abs/2411.04130). The diffusion model itself is found in a *separate* repository: [https://github.com/coleygroup/shepherd](https://github.com/coleygroup/shepherd).
<p align="center">
<img width="200" src="./logo.svg">
</p>
<sub><sup>1</sup> *ShEPhERD*: **S**hape, **E**lectrostatics, and **Ph**armacophores **E**xplicit **R**epresentation **D**iffusion</sub>
## Table of Contents
1. [File Structure](#file-structure)
2. [Requirements](#requirements)
3. [Installation](#installation)
4. [Usage](#how-to-use)
5. [Scoring and Alignment Examples](#scoring-and-alignment-examples)
6. [Evaluation Examples and Scripts](#evaluation-examples-and-scripts)
7. [Data](#data)
## File Structure
```
.
├── shepherd_score/
│ ├── alignment_utils/ # Alignment and rigid transformations tools
│ │ ├── pca.py
│ │ └── se3.py
│ ├── evaluations/ # Evaluation suite
│ │ ├── pdbs/
│ │ ├── utils/
│ │ │ ├── convert_data.py
│ │ │ └── interactions.py
│ │ ├── docking.py # Docking evaluations
│ │ └── evaluate/ # Generated conformer evaluation pipelines
│ │ ├── evals.py # Individual evaluation classes
│ │ ├── pipelines.py # Evaluation pipeline classes
│ │ └── _pipeline_eval_single.py # Internal pipeline evaluation functions
│ ├── pharm_utils/
│ │ ├── pharmacophore.py
│ │ ├── pharm_vec.py
│ │ └── smarts_featues.fdef # Pharmacophore definitions
│ ├── score/ # Scoring related functions and constants
│ │ ├── constants.py
│ │ ├── electrostatic_scoring.py
│ │ ├── gaussian_overlap.py
│ │ └── pharmacophore_scoring.py
│ ├── alignment.py
│ ├── conformer_generation.py # Conformer generation with rdkit and xtb
│ ├── container.py # Molecule and MoleculePair classes
│ ├── extract_profiles.py # Functions to extract interaction profiles
│ ├── generate_point_cloud.py
│ ├── objective.py # Objective function used for REINVENT
│ └── visualize.py # Visualization tools
├── scripts/ # Scripts for running evaluations
├── examples/ # Jupyter notebook tutorials/examples
├── tests/
├── environment.yml # Environment
└── README.md
```
## Requirements
An example environment can be found at `environment.yml`, however, this package should generally work where PyTorch, Open3D, RDKit, and xTB can be installed in an environment with Python >=3.8.
#### Minimum requirements for interaction profile extraction, scoring/alignment, and evaluations
```
python>=3.8
numpy>1.2,<2.0
pytorch>=1.12
mkl==2024.0 (use conda)
open3d>=0.18
rdkit>=2023.03 (newest available is recommended)
xtb>=6.6 (use conda)
scipy>=1.10
pandas>=2.0
```
<sup>Make sure that mkl is *not* 2024.1 since there is a known [issue](https://github.com/pytorch/pytorch/issues/123097) that prevents importing torch.</sup>
#### If you are coming from the *ShEPhERD* repository, you can use the same environment as described there and add the optional packages listed below, if needed.
#### Optional software necessary for docking evaluation
```
meeko
vina==1.2.5
```
You can pip install the python bindings for Autodock Vina for the python interface. However, this also requires an installation of the executable of Autodock Vina v1.2.5: [https://vina.scripps.edu/downloads/](https://vina.scripps.edu/downloads/) and the ADFR software suite: [https://ccsb.scripps.edu/adfr/implementation/](https://ccsb.scripps.edu/adfr/implementation/).
#### Other optional packages
```
jax==0.4.26
jaxlib==0.4.26+cuda12.cudnn89
optax==0.2.2
py3dmol>=2.1.0
biopython>=1.84
prolif>=2.0.3
mdanalysis>=2.2.0
scikit-learn>=1.3
```
## Installation
### via PyPI
`pip install shepherd-score`
### For local development (includes `examples/`, `tests/`, etc.)
1. Clone this repo
2. Navigate to this repo's top-level directory
3. Set up the environment following the instructions above
4. Run `pip install -e .` for developer install
## Usage
The package has base functions and convenience wrappers. Scoring can be done with either NumPy or Torch, but alignment requires Torch. There are also Jax implementations for both scoring and alignment of gaussian overlap, ESP similarity, and pharmacophore similarity.
**Update 8/20/25**: Applicable xTB functions and evaluation pipeline evaluations are now parallelizable through the `num_workers` argument in the `.evaluate` method.
### Base functions
#### Conformer generation
Useful conformer generation functions are found in the `shepherd_score.conformer_generation` module.
#### Interaction profile extraction
| Interaction profile | Function |
| :------- | :------- |
| shape | `shepherd_score.extract_profiles.get_molecular_surface()` |
| electrostatics | `shepherd_score.extract_profiles.get_electrostatic_potential()` |
| pharmacophores | `shepherd_score.extract_profiles.get_pharmacophores()` |
#### Scoring
```shepherd_score.score``` contains the base scoring functions with seperate modules for those dependent on PyTorch (`*.py`), NumPy (`*_np.py`), and Jax (`*_jax.py`).
| Similarity | Function |
| :------- | :------- |
| shape | `shepherd_score.score.gaussian_overlap.get_overlap()` |
| electrostatics | `shepherd_score.score.electrostatic_scoring.get_overlap_esp()` |
| pharmacophores | `shepherd_score.score.pharmacophore_scoring.get_overlap_pharm()` |
### Convenience wrappers
- `Molecule` class
- `shepherd_score.container.Molecule` accepts an RDKit `Mol` object (with an associated conformer) and generates user-specified interaction profiles
- `MoleculePair` class
- `shepherd_score.container.MoleculePair` operates on `Molecule` objects and prepares them for scoring and alignment
## Scoring and Alignment Examples
Full jupyter notebook tutorials/examples for extraction, scoring, and alignments are found in the [`examples`](./examples/) folder. Some minimal examples are below.
### Extraction
Extraction of interaction profiles.
```python
from shepherd_score.conformer_generation import embed_conformer_from_smiles
from shepherd_score.conformer_generation import charges_from_single_point_conformer_with_xtb
from shepherd_score.extract_profiles import get_atomic_vdw_radii, get_molecular_surface
from shepherd_score.extract_profiles import get_pharmacophores, get_electrostatic_potential
from shepherd_score.extract_profiles import get_electrostatic_potential
# Embed conformer with RDKit and partial charges from xTB
ref_mol = embed_conformer_from_smiles('Oc1ccc(CC=C)cc1', MMFF_optimize=True)
partial_charges = charges_from_single_point_conformer_with_xtb(ref_mol)
# Radii are needed for surface extraction
radii = get_atomic_vdw_radii(ref_mol)
# `surface` is an np.array with shape (200, 3)
surface = get_molecular_surface(ref_mol.GetConformer().GetPositions(), radii, num_points=200)
# Get electrostatic potential at each point on the surface
# `esp`: np.array (200,)
esp = get_electrostatic_potential(ref_mol, partial_charges, surface)
# Pharmacophores as arrays with averaged vectors
# pharm_types: np.array (P,)
# pharm_{pos/vecs}: np.array (P,3)
pharm_types, pharm_pos, pharm_vecs = get_pharmacophores(ref_mol, multi_vector=False)
```
### 3D similarity scoring
An example of scoring the similarity of two different molecules using 3D surface, ESP, and pharmacophore similarity metrics.
```python
from shepherd_score.score.constants import ALPHA
from shepherd_score.conformer_generation import embed_conformer_from_smiles
from shepherd_score.conformer_generation import optimize_conformer_with_xtb
from shepherd_score.container import Molecule, MoleculePair
# Embed a random conformer with RDKit
ref_mol_rdkit = embed_conformer_from_smiles('Oc1ccc(CC=C)cc1', MMFF_optimize=True)
fit_mol_rdkit = embed_conformer_from_smiles('O=CCc1ccccc1', MMFF_optimize=True)
# Local relaxation with xTB
ref_mol, _, ref_charges = optimize_conformer_with_xtb(ref_mol_rdkit)
fit_mol, _, fit_charges = optimize_conformer_with_xtb(fit_mol_rdkit)
# Extract interaction profiles
ref_molec = Molecule(ref_mol,
num_surf_points=200,
partial_charges=ref_charges,
pharm_multi_vector=False)
fit_molec = Molecule(fit_mol,
num_surf_points=200,
partial_charges=fit_charges,
pharm_multi_vector=False)
# Centers the two molecules' COM's to the origin
mp = MoleculePair(ref_molec, fit_molec, num_surf_points=200, do_center=True)
# Compute the similarity score for each interaction profile
shape_score = mp.score_with_surf(ALPHA(mp.num_surf_points))
esp_score = mp.score_with_esp(ALPHA(mp.num_surf_points), lam=0.3)
pharm_score = mp.score_with_pharm()
```
### Alignment
Next we show alignment using the same MoleculePair class.
```python
# Centers the two molecules' COM's to the origin
mp = MoleculePair(ref_molec, fit_molec, num_surf_points=200, do_center=True)
# Align fit_molec to ref_molec with your preferred objective function
# By default we use automatic differentiation via pytorch
surf_points_aligned = mp.align_with_surf(ALPHA(mp.num_surf_points),
num_repeats=50)
surf_points_esp_aligned = mp.align_with_esp(ALPHA(mp.num_surf_points),
lam=0.3,
num_repeats=50)
pharm_pos_aligned, pharm_vec_aligned = mp.align_with_pharm(num_repeats=50)
# Optimal scores and SE(3) transformation matrices are stored as attributes
mp.sim_aligned_{surf/esp/pharm}
mp.transform_{surf/esp/pharm}
# Get a copy of the optimally aligned fit Molecule object
transformed_fit_molec = mp.get_transformed_molecule(
se3_transform=mp.transform_{surf/esp/pharm}
)
```
## Evaluation Examples and Scripts
We implement three evaluations of generated 3D conformers. Evaluations can be done on an individual basis or in a pipeline. Here we show the most basic use case in the unconditional setting.
- `ConfEval`
- Checks validity, pre-/post-xTB relaxation
- Calculates 2D graph properties
- `ConsistencyEval`
- Inherits from `ConfEval` and evaluates the consistency of the molecule's jointly generated interaction profiles with the true interaction profiles using 3D similarity scoring functions
- `ConditionalEval`
- Inherits from `ConfEval` and evaluates the 3D similarity between generated molecules and the target molecule
**Note**: Evaluations can be run from any molecule's atomic numbers and positions with explicit hydrogens (i.e., straight from an xyz file).
### Examples
Full jupyter notebook tutorials/examples for evaluations are found in the [`examples`](./examples/) folder. Some minimal examples are below.
```python
from shepherd_score.evaluations.evalutate import ConfEval
from shepherd_score.evaluations.evalutate import UnconditionalEvalPipeline
# ConfEval evaluates the validity of a given molecule, optimizes it with xTB,
# and also computes various 2D graph properties
# `atom_array` np.ndarray (N,) atomic numbers of the molecule (with explicit H)
# `position_array` np.ndarray (N,3) atom coordinates for the molecule
conf_eval = ConfEval(atoms=atom_array, positions=position_array)
# Alternatively, if you have a list of molecules you want to test:
uncond_pipe = UnconditionalEvalPipeline(
generated_mols = [(a, p) for a, p in zip(atom_arrays, position_arrays)]
)
uncond_pipe.evaluate(num_workers=4)
# Properties are stored as attributes and can be converted into pandas df's
sample_df, global_series = uncond_pipe.to_pandas()
```
### Scripts
Scripts to evaluate *ShEPhERD*-generated samples can be found in the `scripts` directory.
## Data
We provide the data used for model training, benchmarking, and all *ShEPhERD*-generated samples reported in the paper at this [Dropbox link](https://www.dropbox.com/scl/fo/rgn33g9kwthnjt27bsc3m/ADGt-CplyEXSU7u5MKc0aTo?rlkey=fhi74vkktpoj1irl84ehnw95h&e=1&st=wn46d6o2&dl=0). There are comprehensive READMEs in the Dropbox describing the different folders.
## License
This project is licensed under the MIT License -- see [LICENSE](./LICENSE) file for details.
## Citation
If you use or adapt `shepherd_score` or [*ShEPhERD*](https://github.com/coleygroup/shepherd) in your work, please cite us:
```bibtex
@misc{adamsShEPhERD2024,
title = {{{ShEPhERD}}: {{Diffusing}} Shape, Electrostatics, and Pharmacophores for Bioisosteric Drug Design},
author = {Adams, Keir and Abeywardane, Kento and Fromer, Jenna and Coley, Connor W.},
year = {2024},
number = {arXiv:2411.04130},
eprint = {2411.04130},
publisher = {arXiv},
doi = {10.48550/arXiv.2411.04130},
archiveprefix = {arXiv}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/kentoabeywardane/shepherd-score",
"name": "shepherd-score",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.8",
"maintainer_email": null,
"keywords": "bioinformatics, molecular-modeling, 3d-scoring, drug-discovery, chemistry, bioisosteres",
"author": "Kento Abeywardane",
"author_email": "Kento Abeywardane <kento@mit.edu>",
"download_url": "https://files.pythonhosted.org/packages/0d/ff/3712aa3a5ddf9ee7ec71eeaa6dcc759188706da883fe0bb09bc0222c7adc/shepherd_score-1.1.0.tar.gz",
"platform": null,
"description": "# *ShEPhERD* Scoring Functions\nThis repository contains the code for **generating/optimizing conformers**, **extracting interaction profiles**, **aligning interaction profiles**, and **differentiably scoring 3D similarity**. It also contains modules to evaluate conformers generated with *ShEPhERD*<sup>1</sup> and other generative models.\n\nThe formulation of the interaction profile representation, scoring, alignment, and evaluations are found in our preprint [*ShEPhERD*: Diffusing shape, electrostatics, and pharmacophores for bioisosteric drug design](https://arxiv.org/abs/2411.04130). The diffusion model itself is found in a *separate* repository: [https://github.com/coleygroup/shepherd](https://github.com/coleygroup/shepherd).\n\n\n<p align=\"center\">\n <img width=\"200\" src=\"./logo.svg\">\n</p>\n\n<sub><sup>1</sup> *ShEPhERD*: **S**hape, **E**lectrostatics, and **Ph**armacophores **E**xplicit **R**epresentation **D**iffusion</sub>\n\n## Table of Contents\n1. [File Structure](#file-structure)\n2. [Requirements](#requirements)\n3. [Installation](#installation)\n4. [Usage](#how-to-use)\n5. [Scoring and Alignment Examples](#scoring-and-alignment-examples)\n6. [Evaluation Examples and Scripts](#evaluation-examples-and-scripts)\n7. [Data](#data)\n\n\n## File Structure\n```\n.\n\u251c\u2500\u2500 shepherd_score/\n\u2502 \u251c\u2500\u2500 alignment_utils/ # Alignment and rigid transformations tools\n\u2502 \u2502 \u251c\u2500\u2500 pca.py\n\u2502 \u2502 \u2514\u2500\u2500 se3.py\n\u2502 \u251c\u2500\u2500 evaluations/ # Evaluation suite\n\u2502 \u2502 \u251c\u2500\u2500 pdbs/\n\u2502 \u2502 \u251c\u2500\u2500 utils/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 convert_data.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 interactions.py\n\u2502 \u2502 \u251c\u2500\u2500 docking.py # Docking evaluations\n\u2502 \u2502 \u2514\u2500\u2500 evaluate/ # Generated conformer evaluation pipelines\n\u2502 \u2502 \u251c\u2500\u2500 evals.py # Individual evaluation classes\n\u2502 \u2502 \u251c\u2500\u2500 pipelines.py # Evaluation pipeline classes\n\u2502 \u2502 \u2514\u2500\u2500 _pipeline_eval_single.py # Internal pipeline evaluation functions\n\u2502 \u251c\u2500\u2500 pharm_utils/\n\u2502 \u2502 \u251c\u2500\u2500 pharmacophore.py\n\u2502 \u2502 \u251c\u2500\u2500 pharm_vec.py\n\u2502 \u2502 \u2514\u2500\u2500 smarts_featues.fdef # Pharmacophore definitions\n\u2502 \u251c\u2500\u2500 score/ # Scoring related functions and constants\n\u2502 \u2502 \u251c\u2500\u2500 constants.py\n\u2502 \u2502 \u251c\u2500\u2500 electrostatic_scoring.py\n\u2502 \u2502 \u251c\u2500\u2500 gaussian_overlap.py\n\u2502 \u2502 \u2514\u2500\u2500 pharmacophore_scoring.py\n\u2502 \u251c\u2500\u2500 alignment.py\n\u2502 \u251c\u2500\u2500 conformer_generation.py # Conformer generation with rdkit and xtb\n\u2502 \u251c\u2500\u2500 container.py # Molecule and MoleculePair classes\n\u2502 \u251c\u2500\u2500 extract_profiles.py # Functions to extract interaction profiles\n\u2502 \u251c\u2500\u2500 generate_point_cloud.py\n\u2502 \u251c\u2500\u2500 objective.py # Objective function used for REINVENT\n\u2502 \u2514\u2500\u2500 visualize.py # Visualization tools\n\u251c\u2500\u2500 scripts/ # Scripts for running evaluations\n\u251c\u2500\u2500 examples/ # Jupyter notebook tutorials/examples \n\u251c\u2500\u2500 tests/\n\u251c\u2500\u2500 environment.yml # Environment\n\u2514\u2500\u2500 README.md\n```\n\n\n## Requirements\nAn example environment can be found at `environment.yml`, however, this package should generally work where PyTorch, Open3D, RDKit, and xTB can be installed in an environment with Python >=3.8.\n\n#### Minimum requirements for interaction profile extraction, scoring/alignment, and evaluations\n```\npython>=3.8\nnumpy>1.2,<2.0\npytorch>=1.12\nmkl==2024.0 (use conda)\nopen3d>=0.18\nrdkit>=2023.03 (newest available is recommended)\nxtb>=6.6 (use conda)\nscipy>=1.10\npandas>=2.0\n```\n\n<sup>Make sure that mkl is *not* 2024.1 since there is a known [issue](https://github.com/pytorch/pytorch/issues/123097) that prevents importing torch.</sup>\n\n#### If you are coming from the *ShEPhERD* repository, you can use the same environment as described there and add the optional packages listed below, if needed.\n\n\n#### Optional software necessary for docking evaluation\n```\nmeeko\nvina==1.2.5\n```\nYou can pip install the python bindings for Autodock Vina for the python interface. However, this also requires an installation of the executable of Autodock Vina v1.2.5: [https://vina.scripps.edu/downloads/](https://vina.scripps.edu/downloads/) and the ADFR software suite: [https://ccsb.scripps.edu/adfr/implementation/](https://ccsb.scripps.edu/adfr/implementation/).\n\n#### Other optional packages\n```\njax==0.4.26\njaxlib==0.4.26+cuda12.cudnn89\noptax==0.2.2\npy3dmol>=2.1.0\nbiopython>=1.84\nprolif>=2.0.3\nmdanalysis>=2.2.0\nscikit-learn>=1.3\n```\n\n## Installation\n### via PyPI\n`pip install shepherd-score`\n\n### For local development (includes `examples/`, `tests/`, etc.)\n1. Clone this repo\n2. Navigate to this repo's top-level directory\n3. Set up the environment following the instructions above\n4. Run `pip install -e .` for developer install\n\n## Usage\nThe package has base functions and convenience wrappers. Scoring can be done with either NumPy or Torch, but alignment requires Torch. There are also Jax implementations for both scoring and alignment of gaussian overlap, ESP similarity, and pharmacophore similarity.\n\n**Update 8/20/25**: Applicable xTB functions and evaluation pipeline evaluations are now parallelizable through the `num_workers` argument in the `.evaluate` method.\n\n### Base functions\n#### Conformer generation\nUseful conformer generation functions are found in the `shepherd_score.conformer_generation` module.\n\n#### Interaction profile extraction\n| Interaction profile | Function |\n| :------- | :------- |\n| shape | `shepherd_score.extract_profiles.get_molecular_surface()` |\n| electrostatics | `shepherd_score.extract_profiles.get_electrostatic_potential()` |\n| pharmacophores | `shepherd_score.extract_profiles.get_pharmacophores()` |\n\n#### Scoring\n```shepherd_score.score``` contains the base scoring functions with seperate modules for those dependent on PyTorch (`*.py`), NumPy (`*_np.py`), and Jax (`*_jax.py`).\n\n| Similarity | Function |\n| :------- | :------- |\n| shape | `shepherd_score.score.gaussian_overlap.get_overlap()` |\n| electrostatics | `shepherd_score.score.electrostatic_scoring.get_overlap_esp()` |\n| pharmacophores | `shepherd_score.score.pharmacophore_scoring.get_overlap_pharm()` |\n\n### Convenience wrappers\n- `Molecule` class\n - `shepherd_score.container.Molecule` accepts an RDKit `Mol` object (with an associated conformer) and generates user-specified interaction profiles\n- `MoleculePair` class\n - `shepherd_score.container.MoleculePair` operates on `Molecule` objects and prepares them for scoring and alignment\n\n\n## Scoring and Alignment Examples\n\nFull jupyter notebook tutorials/examples for extraction, scoring, and alignments are found in the [`examples`](./examples/) folder. Some minimal examples are below.\n\n### Extraction\nExtraction of interaction profiles.\n\n```python\nfrom shepherd_score.conformer_generation import embed_conformer_from_smiles\nfrom shepherd_score.conformer_generation import charges_from_single_point_conformer_with_xtb\nfrom shepherd_score.extract_profiles import get_atomic_vdw_radii, get_molecular_surface\nfrom shepherd_score.extract_profiles import get_pharmacophores, get_electrostatic_potential\nfrom shepherd_score.extract_profiles import get_electrostatic_potential\n\n# Embed conformer with RDKit and partial charges from xTB\nref_mol = embed_conformer_from_smiles('Oc1ccc(CC=C)cc1', MMFF_optimize=True)\npartial_charges = charges_from_single_point_conformer_with_xtb(ref_mol)\n\n# Radii are needed for surface extraction\nradii = get_atomic_vdw_radii(ref_mol)\n# `surface` is an np.array with shape (200, 3)\nsurface = get_molecular_surface(ref_mol.GetConformer().GetPositions(), radii, num_points=200)\n\n# Get electrostatic potential at each point on the surface\n# `esp`: np.array (200,)\nesp = get_electrostatic_potential(ref_mol, partial_charges, surface)\n\n# Pharmacophores as arrays with averaged vectors\n# pharm_types: np.array (P,)\n# pharm_{pos/vecs}: np.array (P,3)\npharm_types, pharm_pos, pharm_vecs = get_pharmacophores(ref_mol, multi_vector=False)\n```\n\n### 3D similarity scoring\nAn example of scoring the similarity of two different molecules using 3D surface, ESP, and pharmacophore similarity metrics.\n\n```python\nfrom shepherd_score.score.constants import ALPHA\nfrom shepherd_score.conformer_generation import embed_conformer_from_smiles\nfrom shepherd_score.conformer_generation import optimize_conformer_with_xtb\nfrom shepherd_score.container import Molecule, MoleculePair\n\n# Embed a random conformer with RDKit\nref_mol_rdkit = embed_conformer_from_smiles('Oc1ccc(CC=C)cc1', MMFF_optimize=True)\nfit_mol_rdkit = embed_conformer_from_smiles('O=CCc1ccccc1', MMFF_optimize=True)\n# Local relaxation with xTB\nref_mol, _, ref_charges = optimize_conformer_with_xtb(ref_mol_rdkit)\nfit_mol, _, fit_charges = optimize_conformer_with_xtb(fit_mol_rdkit)\n\n# Extract interaction profiles\nref_molec = Molecule(ref_mol,\n num_surf_points=200,\n partial_charges=ref_charges,\n pharm_multi_vector=False)\nfit_molec = Molecule(fit_mol,\n num_surf_points=200,\n partial_charges=fit_charges,\n pharm_multi_vector=False)\n\n# Centers the two molecules' COM's to the origin\nmp = MoleculePair(ref_molec, fit_molec, num_surf_points=200, do_center=True)\n\n# Compute the similarity score for each interaction profile\nshape_score = mp.score_with_surf(ALPHA(mp.num_surf_points))\nesp_score = mp.score_with_esp(ALPHA(mp.num_surf_points), lam=0.3)\npharm_score = mp.score_with_pharm()\n```\n\n### Alignment\nNext we show alignment using the same MoleculePair class.\n\n```python\n# Centers the two molecules' COM's to the origin\nmp = MoleculePair(ref_molec, fit_molec, num_surf_points=200, do_center=True)\n\n# Align fit_molec to ref_molec with your preferred objective function\n# By default we use automatic differentiation via pytorch\nsurf_points_aligned = mp.align_with_surf(ALPHA(mp.num_surf_points),\n num_repeats=50)\nsurf_points_esp_aligned = mp.align_with_esp(ALPHA(mp.num_surf_points),\n lam=0.3,\n num_repeats=50)\npharm_pos_aligned, pharm_vec_aligned = mp.align_with_pharm(num_repeats=50)\n\n# Optimal scores and SE(3) transformation matrices are stored as attributes\nmp.sim_aligned_{surf/esp/pharm}\nmp.transform_{surf/esp/pharm}\n\n# Get a copy of the optimally aligned fit Molecule object\ntransformed_fit_molec = mp.get_transformed_molecule(\n se3_transform=mp.transform_{surf/esp/pharm}\n)\n```\n\n## Evaluation Examples and Scripts\n\nWe implement three evaluations of generated 3D conformers. Evaluations can be done on an individual basis or in a pipeline. Here we show the most basic use case in the unconditional setting.\n\n\n- `ConfEval`\n - Checks validity, pre-/post-xTB relaxation\n - Calculates 2D graph properties\n- `ConsistencyEval`\n - Inherits from `ConfEval` and evaluates the consistency of the molecule's jointly generated interaction profiles with the true interaction profiles using 3D similarity scoring functions\n- `ConditionalEval`\n - Inherits from `ConfEval` and evaluates the 3D similarity between generated molecules and the target molecule\n\n**Note**: Evaluations can be run from any molecule's atomic numbers and positions with explicit hydrogens (i.e., straight from an xyz file).\n\n### Examples\n\nFull jupyter notebook tutorials/examples for evaluations are found in the [`examples`](./examples/) folder. Some minimal examples are below.\n\n```python\nfrom shepherd_score.evaluations.evalutate import ConfEval\nfrom shepherd_score.evaluations.evalutate import UnconditionalEvalPipeline\n\n# ConfEval evaluates the validity of a given molecule, optimizes it with xTB,\n# and also computes various 2D graph properties\n# `atom_array` np.ndarray (N,) atomic numbers of the molecule (with explicit H)\n# `position_array` np.ndarray (N,3) atom coordinates for the molecule\nconf_eval = ConfEval(atoms=atom_array, positions=position_array)\n\n# Alternatively, if you have a list of molecules you want to test:\nuncond_pipe = UnconditionalEvalPipeline(\n generated_mols = [(a, p) for a, p in zip(atom_arrays, position_arrays)]\n)\nuncond_pipe.evaluate(num_workers=4)\n\n# Properties are stored as attributes and can be converted into pandas df's\nsample_df, global_series = uncond_pipe.to_pandas()\n```\n\n### Scripts\nScripts to evaluate *ShEPhERD*-generated samples can be found in the `scripts` directory.\n\n## Data\nWe provide the data used for model training, benchmarking, and all *ShEPhERD*-generated samples reported in the paper at this [Dropbox link](https://www.dropbox.com/scl/fo/rgn33g9kwthnjt27bsc3m/ADGt-CplyEXSU7u5MKc0aTo?rlkey=fhi74vkktpoj1irl84ehnw95h&e=1&st=wn46d6o2&dl=0). There are comprehensive READMEs in the Dropbox describing the different folders.\n\n## License\n\nThis project is licensed under the MIT License -- see [LICENSE](./LICENSE) file for details.\n\n## Citation\nIf you use or adapt `shepherd_score` or [*ShEPhERD*](https://github.com/coleygroup/shepherd) in your work, please cite us:\n\n```bibtex\n@misc{adamsShEPhERD2024,\n title = {{{ShEPhERD}}: {{Diffusing}} Shape, Electrostatics, and Pharmacophores for Bioisosteric Drug Design},\n author = {Adams, Keir and Abeywardane, Kento and Fromer, Jenna and Coley, Connor W.},\n year = {2024},\n number = {arXiv:2411.04130},\n eprint = {2411.04130},\n publisher = {arXiv},\n doi = {10.48550/arXiv.2411.04130},\n archiveprefix = {arXiv}\n}\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "3D scoring functions used for evaluation of ShEPhERD",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/kentoabeywardane/shepherd-score/issues",
"Documentation": "https://github.com/kentoabeywardane/shepherd-score",
"Homepage": "https://github.com/kentoabeywardane/shepherd-score",
"Repository": "https://github.com/kentoabeywardane/shepherd-score"
},
"split_keywords": [
"bioinformatics",
" molecular-modeling",
" 3d-scoring",
" drug-discovery",
" chemistry",
" bioisosteres"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6d3299fa21989cf46493bd3acdf2116269e8542a3a95b310beeec1f493dd5a76",
"md5": "2503624c83afc3e05589e3ab8072f0b6",
"sha256": "1450762f84704f09fb468bbe4a70c4a472d9604d54c75b16940ae34ebdad9f85"
},
"downloads": -1,
"filename": "shepherd_score-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2503624c83afc3e05589e3ab8072f0b6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.8",
"size": 621562,
"upload_time": "2025-08-20T22:10:19",
"upload_time_iso_8601": "2025-08-20T22:10:19.239560Z",
"url": "https://files.pythonhosted.org/packages/6d/32/99fa21989cf46493bd3acdf2116269e8542a3a95b310beeec1f493dd5a76/shepherd_score-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0dff3712aa3a5ddf9ee7ec71eeaa6dcc759188706da883fe0bb09bc0222c7adc",
"md5": "1eb1b9389b67c5f6af16a1565727892f",
"sha256": "48077e9a2e4779c7a43a31044de8c5015f7edfddd8f8f276a78cea625a1e3845"
},
"downloads": -1,
"filename": "shepherd_score-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1eb1b9389b67c5f6af16a1565727892f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.8",
"size": 663882,
"upload_time": "2025-08-20T22:10:20",
"upload_time_iso_8601": "2025-08-20T22:10:20.785152Z",
"url": "https://files.pythonhosted.org/packages/0d/ff/3712aa3a5ddf9ee7ec71eeaa6dcc759188706da883fe0bb09bc0222c7adc/shepherd_score-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-20 22:10:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kentoabeywardane",
"github_project": "shepherd-score",
"github_not_found": true,
"lcname": "shepherd-score"
}
JSON
