README.md 3.46 KB
Newer Older
Jacob Durrant's avatar
Jacob Durrant committed
1
Dimorphite-DL 1.1
Jacob Durrant's avatar
Jacob Durrant committed
2
=================
pjropp's avatar
pjropp committed
3

4 5
What is it?
-----------
pjropp's avatar
pjropp committed
6

jdurrant's avatar
jdurrant committed
7 8 9
Dimorphite-DL adds hydrogen atoms to molecular representations, as appropriate
for a user-specified pH range. It is a fast, accurate, accessible, and modular
open-source program for enumerating small-molecule ionization states.
pjropp's avatar
pjropp committed
10

11 12
Users can provide SMILES strings from the command line or via an .smi file.

Jacob Durrant's avatar
Jacob Durrant committed
13 14 15 16 17 18 19 20 21
Citation
--------

If you use Dimorphite-DL in your research, please cite:

Ropp PJ, Kaminsky JC, Yablonski S, Durrant JD (2019) Dimorphite-DL: An
open-source program for enumerating the ionization states of drug-like small
molecules. J Cheminform 11:14. doi:10.1186/s13321-019-0336-9.

22 23 24
Licensing
---------

jdurrant's avatar
jdurrant committed
25
Protonation is released under the Apache 2.0 license. See LICENCE.txt for
26 27 28 29 30 31
details.

Usage
-----

```
jdurrant's avatar
jdurrant committed
32
usage: dimorphite_dl.py [-h] [--min_ph MIN] [--max_ph MAX]
jdurrant's avatar
jdurrant committed
33 34 35
                        [--pka_precision PRE] [--smiles SMI]
                        [--smiles_file FILE] [--output_file FILE]
                        [--label_states] [--test]
36

Jacob Durrant's avatar
Jacob Durrant committed
37
Dimorphite 1.1: Creates models of appropriately protonated small moleucles.
Jacob Durrant's avatar
Jacob Durrant committed
38
Apache 2.0 License. Copyright 2018 Jacob D. Durrant.
39 40

optional arguments:
jdurrant's avatar
jdurrant committed
41 42 43 44 45 46 47 48 49 50 51
  -h, --help           show this help message and exit
  --min_ph MIN         minimum pH to consider (default: 6.4)
  --max_ph MAX         maximum pH to consider (default: 8.4)
  --pka_precision PRE  pKa precision factor (number of standard devations,
                       default: 1.0)
  --smiles SMI         SMILES string to protonate
  --smiles_file FILE   file that contains SMILES strings to protonate
  --output_file FILE   output file to write protonated SMILES (optional)
  --label_states       label protonated SMILES with target state (i.e.,
                       "DEPROTONATED", "PROTONATED", or "BOTH").
  --test               run unit tests (for debugging)
52 53 54 55 56 57 58 59
```

The default pH range is 6.4 to 8.4, considered biologically relevant pH.

Examples
--------

```
Jacob Durrant's avatar
Jacob Durrant committed
60 61 62 63 64
  python dimorphite_dl.py --smiles_file sample_molecules.smi
  python dimorphite_dl.py --smiles "CCC(=O)O" --min_ph -3.0 --max_ph -2.0
  python dimorphite_dl.py --smiles "CCCN" --min_ph -3.0 --max_ph -2.0 --output_file output.smi
  python dimorphite_dl.py --smiles_file sample_molecules.smi --pka_precision 2.0 --label_states
  python dimorphite_dl.py --test
65 66
```

67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97
Advanced Usage
--------------

It is also possible to access Dimorphite-DL from another Python script, rather
than from the command line. Here's an example:

```python
from rdkit import Chem
import dimorphite_dl

# Using the dimorphite_dl.run() function, you can run Dimorphite-DL exactly as
# you would from the command line. Here's an example:
dimorphite_dl.run(
   smiles="CCCN",
   min_ph=-3.0,
   max_ph=-2.0,
   output_file="output.smi"
)
print("Output of first test saved to output.smi...")

# Using the dimorphite_dl.run_with_mol_list() function, you can also pass a
# list of RDKit Mol objects. The first argument is always the list.
mols = [Chem.MolFromSmiles(s) for s in ["C[C@](F)(Br)CC(O)=O", "CCCCCN"]]
protonated_mols = dimorphite_dl.run_with_mol_list(
    mols,
    min_ph=5.0,
    max_ph=9.0,
)
print([Chem.MolToSmiles(m) for m in protonated_mols])
```

98 99 100 101 102 103 104
Caveats
-------

Dimorphite-DL deprotonates indoles and pyrroles around pH 14.5. But these
substructures can also be protonated around pH -3.5. Dimorphite does not
perform the protonation.

105 106 107 108
Authors and Contacts
--------------------

See the `CONTRIBUTORS.md` file for a full list of contributors. Please contact
jdurrant's avatar
jdurrant committed
109
Jacob Durrant (durrantj@pitt.edu) with any questions.