README.md 4.63 KB
Newer Older
Elad Noor's avatar
Elad Noor committed
1 2 3
eQuilibrator-API
================
[![pipeline status](https://gitlab.com/elad.noor/equilibrator-api/badges/master/pipeline.svg)](https://gitlab.com/elad.noor/equilibrator-api/commits/master)
4
[![coverage report](https://gitlab.com/elad.noor/equilibrator-api/badges/master/coverage.svg)](https://gitlab.com/elad.noor/equilibrator-api/commits/master)
Elad Noor's avatar
Elad Noor committed
5 6
[![Join the chat at https://gitter.im/equilibrator-devs/equilibrator-api](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/equilibrator-devs/equilibrator-api?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

Elad Noor's avatar
Elad Noor committed
7

Elad Noor's avatar
Elad Noor committed
8 9 10
A command-line API with minimal dependencies for calculation of standard 
thermodynamic potentials of biochemical reactions using the data found on 
[eQuilibrator](http://equilibrator.weizmann.ac.il/).
11
Does not require any network connections.
Avi Flamholz's avatar
Avi Flamholz committed
12

eladnoor's avatar
eladnoor committed
13
## Current Features
Avi Flamholz's avatar
Avi Flamholz committed
14

15
* Example scripts for singleton and bulk calculations.
16
* Calculation of standard Gibbs potentials of reactions (together with confidence intervals).
Avi Flamholz's avatar
Avi Flamholz committed
17 18
* Calculation of standard reduction potentials of half-cells.

Elad Noor's avatar
Elad Noor committed
19 20 21
To access more advanced features, such as adding new compounds that are not
available in the KEGG database, try using our full-blown
[Component Contribution](https://github.com/eladnoor/component-contribution)
22 23
package.

eladnoor's avatar
eladnoor committed
24
## Cite us
25 26 27 28

If you plan to use results from equilibrator-api in a scientific publication,
please cite our paper:

Elad Noor's avatar
Elad Noor committed
29 30
Noor E, Haraldsdóttir HS, Milo R, Fleming RMT. Consistent estimation of Gibbs 
energy using component contributions. PLoS Comput Biol. 2013;9: e1003098.
31

eladnoor's avatar
eladnoor committed
32 33
## Installation

eladnoor's avatar
eladnoor committed
34
The easiest way to get eQuilibrator-API up and running is using virtualenv, PyPI, and Jupyter notebooks:
eladnoor's avatar
eladnoor committed
35
```
eladnoor's avatar
eladnoor committed
36 37
virtualenv -p python3 equilibrator
source equilibrator/bin/activate
38
pip install equilibrator-api
eladnoor's avatar
eladnoor committed
39
```
40 41
You can then either follow the examples below and write your own code, or start by opening the
provided jupyter notebook:
eladnoor's avatar
eladnoor committed
42 43

```
44 45 46 47 48 49
pip install jupyter
curl https://gitlab.com/elad.noor/equilibrator-api/raw/develop/scripts/equilibrator_cmd.ipynb > equilibrator_cmd.ipynb
jupyter notebook
``` 

Then select the notebook called `equilibrator_cmd.ipynb` and follow the examples in it.
eladnoor's avatar
eladnoor committed
50

eladnoor's avatar
eladnoor committed
51
## Example Usage
Avi Flamholz's avatar
Avi Flamholz committed
52

Elad Noor's avatar
Elad Noor committed
53 54
Import the API and create an instance. Creating the EquilibratorAPI class
instance reads all the data that is used to calculate thermodynamic potentials of reactions.
Avi Flamholz's avatar
Avi Flamholz committed
55 56

```python
57 58
from equilibrator_api import ComponentContribution, Reaction, Q_
eq_api = ComponentContribution(p_h=Q_("6.5"), ionic_strength=Q_('200 mM')) # set pH and I
Avi Flamholz's avatar
Avi Flamholz committed
59 60
```

Elad Noor's avatar
Elad Noor committed
61 62
You can parse a reaction from a KEGG-style reaction string. The example given
is ATP hydrolysis to ADP and inorganic phosphate.
Avi Flamholz's avatar
Avi Flamholz committed
63 64

```python
65
rxn_str = "kegg:C00002 + kegg:C00001 = kegg:C00008 + kegg:C00009"
Avi Flamholz's avatar
Avi Flamholz committed
66 67 68
rxn = Reaction.parse_formula(rxn_str)
```

Elad Noor's avatar
Elad Noor committed
69 70 71 72
We highly recommend that you check that the reaction is atomically balanced
(conserves atoms) and charge balanced (redox neutral). We've found that it's
easy to accidentally write unbalanced reactions in this KEGG-style format and
so we always check ourselves.
Avi Flamholz's avatar
Avi Flamholz committed
73 74

```python
75
if not rxn.is_balanced():
76
	print('%s is not balanced' % rxn)
Avi Flamholz's avatar
Avi Flamholz committed
77 78
```

Elad Noor's avatar
Elad Noor committed
79 80
Now we know that the reaction is "kosher" and we can safely proceed to
calculate the standard change in Gibbs potential due to this reaction.
Avi Flamholz's avatar
Avi Flamholz committed
81

Avi Flamholz's avatar
Avi Flamholz committed
82
```python
83 84
# You control the pH and ionic strength!
# ionic strength is in Molar units.
85
standard_dg_prime, uncertainty = eq_api.standard_dg_prime(rxn)
86
print(f"dG0' = {standard_dg_prime:.1f} \u00B1 {uncertainty:1.f}")
Avi Flamholz's avatar
Avi Flamholz committed
87
```
Avi Flamholz's avatar
Avi Flamholz committed
88

89
You can also calculate the [reversibility index](https://doi.org/10.1093/bioinformatics/bts317) for this reaction.
Avi Flamholz's avatar
Avi Flamholz committed
90 91

```python
92
ln_RI = eq_api.ln_reversibility_index(rxn)
93
print(f"ln(Reversibility Index) = {ln_RI:.1f}")
Avi Flamholz's avatar
Avi Flamholz committed
94 95
```

Elad Noor's avatar
Elad Noor committed
96 97 98 99 100
The reversibility index is a measure of the degree of the reversibility of the
reaction that is normalized for stoichiometry. If you are interested in
assigning reversibility to reactions we recommend this measure because 1:2
reactions are much "easier" to reverse than reactions with 1:1 or 2:2 reactions.
You can see the paper linked above for more information.
Avi Flamholz's avatar
Avi Flamholz committed
101

102
### Example of pathway analysis using Max-min Driving Force:
103
Download an example pathway, run Max-min Driving Force analysis and generate two result figures
104 105
```python
from equilibrator_api import Pathway
106
from urllib.request import urlopen
107
url = "https://gitlab.com/elad.noor/equilibrator-api/raw/develop/tests/test_unit/pathway.tsv"
108
pp = Pathway.from_sbtab(urlopen(url))
109
mdf_res = pp.calc_mdf()
eladnoor's avatar
eladnoor committed
110
print('MDF = %s' % mdf_res.mdf)
eladnoor's avatar
eladnoor committed
111
mdf_res.reaction_plot.show()
112
mdf_res.compound_plot.show()
113 114
```

eladnoor's avatar
eladnoor committed
115
## Dependencies:
116
- python >= 3.6
117 118
- equilibrator-cache (latest)
- component-contribution (latest)
eladnoor's avatar
eladnoor committed
119
- sbtab
120 121 122 123 124 125 126
- numpy
- scipy
- optlang
- pandas
- nltk
- pyparsing
- matplotlib
eladnoor's avatar
eladnoor committed
127 128
- quilt
- pint