README.md 2.99 KB
Newer Older
Jacob Durrant's avatar
Jacob Durrant committed
1 2
Dimorphite-DL 1.0
=================
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 13 14 15
Users can provide SMILES strings from the command line or via an .smi file.

Licensing
---------

jdurrant's avatar
jdurrant committed
16
Protonation is released under the Apache 2.0 license. See LICENCE.txt for
17 18 19 20 21 22
details.

Usage
-----

```
jdurrant's avatar
jdurrant committed
23
usage: dimorphite_dl.py [-h] [--min_ph MIN] [--max_ph MAX]
jdurrant's avatar
jdurrant committed
24 25 26
                        [--pka_precision PRE] [--smiles SMI]
                        [--smiles_file FILE] [--output_file FILE]
                        [--label_states] [--test]
27

Jacob Durrant's avatar
Jacob Durrant committed
28
Dimorphite 1.0: Creates models of appropriately protonated small moleucles.
Jacob Durrant's avatar
Jacob Durrant committed
29
Apache 2.0 License. Copyright 2018 Jacob D. Durrant.
30 31

optional arguments:
jdurrant's avatar
jdurrant committed
32 33 34 35 36 37 38 39 40 41 42
  -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)
43 44 45 46 47 48 49 50
```

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

Examples
--------

```
Jacob Durrant's avatar
Jacob Durrant committed
51 52 53 54 55
  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
56 57
```

58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88
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])
```

89 90 91 92
Authors and Contacts
--------------------

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