DeepFrag is a machine learning model for fragment-based lead optimization. In this repository, you will find code to train the model and code to run inference using a pre-trained model.
DeepFrag is a machine learning model for fragment-based lead optimization. In
this repository, you will find code to train the model and code to run
inference using a pre-trained model.
# Citation
## Citation
If you use DeepFrag in your research, please cite as:
Green, H., Koes, D. R., & Durrant, J. D. (2021). DeepFrag: a deep convolutional neural network for fragment-based lead optimization. Chemical Science.
Green, H., Koes, D. R., & Durrant, J. D. (2021). DeepFrag: a deep
convolutional neural network for fragment-based lead optimization. Chemical
Science.
```tex
@article{green2021deepfrag,
...
...
@@ -19,68 +22,106 @@ Green, H., Koes, D. R., & Durrant, J. D. (2021). DeepFrag: a deep convolutional
}
```
# Usage
## Usage
There are three ways to use DeepFrag:
1.**DeepFrag Browser App**: We have released a free, open-source browser app for DeepFrag that requires no setup and does not transmit any structures to a remote server.
- View the online version at [durrantlab.pitt.edu/deepfrag](https://durrantlab.pitt.edu/deepfrag/)
- See the code at [git.durrantlab.pitt.edu/jdurrant/deepfrag-app](https://git.durrantlab.pitt.edu/jdurrant/deepfrag-app)
2.**DeepFrag CLI**: In this repository we have included a `deepfrag.py` script that can perform common prediction tasks using the API.
1.**DeepFrag Browser App**: We have released a free, open-source browser app
for DeepFrag that requires no setup and does not transmit any structures to
2.**DeepFrag CLI**: In this repository we have included a `deepfrag.py`
script that can perform common prediction tasks using the API.
- See the `DeepFrag CLI` section below
3.**DeepFrag API**: For custom tasks or fine-grained control over predictions, you can invoke the DeepFrag API directly and interface with the raw data structures and the PyTorch model. We have created an example Google Colab (Jupyter notebook) that demonstrates how to perform manual predictions.
- See the interactive [Colab](https://colab.research.google.com/drive/1XWin26iDXqZ2ioGtwDRuO4iRomGVpdte)
3.**DeepFrag API**: For custom tasks or fine-grained control over
predictions, you can invoke the DeepFrag API directly and interface with
the raw data structures and the PyTorch model. We have created an example
Google Colab (Jupyter notebook) that demonstrates how to perform manual
The DeepFrag CLI is invoked by running `python3 deepfrag.py` in this
repository. The CLI requires a pre-trained model and the fragment library to
run. You will be prompted to download both when you first run the CLI and
these will be saved in the `./.store` directory.
The DeepFrag CLI is invoked by running `python3 deepfrag.py` in this repository. The CLI requires a pre-trained model and the fragment library to run. You will be prompted to download both when you first run the CLI and these will be saved in the `./.store` directory.
### Structure (specify exactly one)
The input structures are specified using either a manual receptor and ligand
pdb or by specifying a pdb id and the ligand residue number.
## Structure (specify exactly one)
The input structures are specified using either a manual receptor and ligand pdb or by specifying a pdb id and the ligand residue number.
-`--receptor <rec.pdb> --ligand <lig.pdb>`
-`--pdb <pdbid> --resnum <resnum>`
## Connection Point (specify exactly one)
### Connection Point (specify exactly one)
DeepFrag will predict new fragments that connect to the _connection point_ via a single bond. You must specify the connection point atom using one of the following:
-`--cname <name>`: Specify the connection point by atom name (e.g. `C3`, `N5`, `O2`, ...).
-`--cx <x> --cy <y> --cz <z>`: Specify the connection point by atomic coordinate. DeepFrag will find the closest atom to this point.
DeepFrag will predict new fragments that connect to the _connection point_ via
a single bond. You must specify the connection point atom using one of the
following:
## Fragment Removal (optional) (specify exactly one)
-`--cname <name>`: Specify the connection point by atom name (e.g. `C3`,
`N5`, `O2`, ...).
-`--cx <x> --cy <y> --cz <z>`: Specify the connection point by atomic
coordinate. DeepFrag will find the closest atom to this point.
If you are using DeepFrag for fragment _replacement_, you must first remove the original fragment from the ligand structure. You can either do this by hand, e.g. editing the PDB, or DeepFrag can do this for you by specifying _which_ fragment should be removed.
### Fragment Removal (optional) (specify exactly one)
_Note: predicting fragments in place of hydrogen atoms (e.g. protons) does not require any fragment removal since hydrogen atoms are ignored by the model._
If you are using DeepFrag for fragment _replacement_, you must first remove
the original fragment from the ligand structure. You can either do this by
hand, e.g. editing the PDB, or DeepFrag can do this for you by specifying
_which_ fragment should be removed.
To remove a fragment, you specify a second atom that is contained in the fragment. Like the connection point, you can either use the atom name or the atom coordinate.
_Note: predicting fragments in place of hydrogen atoms (e.g. protons) does not
require any fragment removal since hydrogen atoms are ignored by the model._
-`--rname <name>`: Specify the connection point by atom name (e.g. `C3`, `N5`, `O2`, ...).
-`--rx <x> --ry <y> --rz <z>`: Specify the connection point by atomic coordinate. DeepFrag will find the closest atom to this point.
To remove a fragment, you specify a second atom that is contained in the
fragment. Like the connection point, you can either use the atom name or the
atom coordinate.
-`--rname <name>`: Specify the connection point by atom name (e.g. `C3`,
`N5`, `O2`, ...).
-`--rx <x> --ry <y> --rz <z>`: Specify the connection point by atomic
coordinate. DeepFrag will find the closest atom to this point.
## Output (optional)
### Output (optional)
By default, DeepFrag will print a list of fragment predictions to stdout similar to the [Browser App](https://durrantlab.pitt.edu/deepfrag/).
By default, DeepFrag will print a list of fragment predictions to stdout
similar to the [Browser App](https://durrantlab.pitt.edu/deepfrag/).
-`--out <out.csv>`: Save predictions in CSV format to `out.csv`. Each line contains the fragment rank, score and SMILES string.
-`--out <out.csv>`: Save predictions in CSV format to `out.csv`. Each line
contains the fragment rank, score and SMILES string.
## Miscellaneous (optional)
### Miscellaneous (optional)
-`--full`: Generate SMILES strings with the full ligand structure instead of just the fragment.
-`--cpu/--gpu`: DeepFrag will attempt to infer if a Cuda GPU is available and fallback to the CPU if it is not. You can set either the `--cpu` or `--gpu` flag to explicitly specify the target device.
-`--num_grids <num>`: Number of grid rotations to use. Using more will take longer but produce a more stable prediction. (Default: 4)
-`--top_k <k>`: Number of predictions to print in stdout. Use -1 to display all. (Default: 25)
-`--full`: Generate SMILES strings with the full ligand structure instead of
just the fragment.
-`--cpu/--gpu`: DeepFrag will attempt to infer if a Cuda GPU is available and
fallback to the CPU if it is not. You can set either the `--cpu` or `--gpu`
flag to explicitly specify the target device.
-`--num_grids <num>`: Number of grid rotations to use. Using more will take
longer but produce a more stable prediction. (Default: 4)
-`--top_k <k>`: Number of predictions to print in stdout. Use -1 to display
all. (Default: 25)
# Reproduce Results
## Reproduce Results
You can use the DeepFrag CLI to reproduce the highlighted results from the main manuscript:
You can use the DeepFrag CLI to reproduce the highlighted results from the
main manuscript:
## 1. Fragment replacement
### 1. Fragment replacement
To replace fragments, specify the connection point (`cname` or `cx/cy/cz`) and specify a second atom that is contained in the fragment (`rname` or `rx/ry/rz`).
To replace fragments, specify the connection point (`cname` or `cx/cy/cz`) and
specify a second atom that is contained in the fragment (`rname` or
For fragment addition, you only need to specify the atom connection point (`cname` or `cx/cy/cz`). In this case, DeepFrag will implicily replace a valent hydrogen.
For fragment addition, you only need to specify the atom connection point
(`cname` or `cx/cy/cz`). In this case, DeepFrag will implicitly replace a
valent hydrogen.
```bash
# Fig. 5: Ligands targeting the SARS-CoV-2 main protease (MPro)
To train a model, you can use the `train.py` utility script. You can specify model parameters as command line arguments or load parameters from a configuration args.json file.
To train a model, you can use the `train.py` utility script. You can specify
model parameters as command line arguments or load parameters from a
configuration args.json file.
```bash
python train.py \
...
...
@@ -189,15 +237,21 @@ python train.py \
--configuration=./configurations/args.json
```
`save_path` is a directory to save the best model. The directory will be created if it doesn't exist. If this is not provided, the model will not be saved.
`save_path` is a directory to save the best model. The directory will be
created if it doesn't exist. If this is not provided, the model will not be
saved.
`wandb_project` is an optional wandb project name. If provided, the run will be logged to wandb.
`wandb_project` is an optional wandb project name. If provided, the run will
be logged to wandb.
See below for available models and model-specific parameters:
# Leadopt Models
## Leadopt Models
In this repository, trainable models are subclasses of `model_conf.LeadoptModel`. This class encapsulates model configuration arguments and pytorch models and enables saving and loading multi-component models.
In this repository, trainable models are subclasses of
`model_conf.LeadoptModel`. This class encapsulates model configuration
arguments and pytorch models and enables saving and loading multi-component
