README.md 4.41 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 34 35 36 37 38
## Installation

The easiest way to get eQuilibrator-API up an running is using PyPI:
```
pip install equilibrator-api
```

Elad Noor's avatar
Elad Noor committed
39 40
Alternatively, you could install from source. Make sure you have [git-lfs](https://git-lfs.github.com/)
installed before cloning the repository:
eladnoor's avatar
eladnoor committed
41 42 43 44 45 46
```
git clone https://gitlab.com/elad.noor/equilibrator-api.git
cd equilibrator-api
python setup.py install
```

eladnoor's avatar
eladnoor committed
47
## Example Usage
Avi Flamholz's avatar
Avi Flamholz committed
48

Elad Noor's avatar
Elad Noor committed
49 50
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
51 52

```python
53 54
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
55 56
```

Elad Noor's avatar
Elad Noor committed
57 58
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
59 60

```python
61
rxn_str = "KEGG:C00002 + KEGG:C00001 = KEGG:C00008 + KEGG:C00009"
Avi Flamholz's avatar
Avi Flamholz committed
62 63 64
rxn = Reaction.parse_formula(rxn_str)
```

Elad Noor's avatar
Elad Noor committed
65 66 67 68
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
69 70

```python
71
if not rxn.is_balanced():
72
	print('%s is not balanced' % rxn)
Avi Flamholz's avatar
Avi Flamholz committed
73 74
```

Elad Noor's avatar
Elad Noor committed
75 76
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
77

Avi Flamholz's avatar
Avi Flamholz committed
78
```python
79 80
# You control the pH and ionic strength!
# ionic strength is in Molar units.
81
standard_dg_prime, uncertainty = eq_api.standard_dg_prime(rxn)
82
print("dG0' = %s \u00B1 %s\n" % (standard_dg_prime, uncertainty))
Avi Flamholz's avatar
Avi Flamholz committed
83
```
Avi Flamholz's avatar
Avi Flamholz committed
84

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

```python
88
ln_RI = eq_api.ln_reversibility_index(rxn)
89
print('ln(Reversibility Index) = %s\n' % ln_RI)
Avi Flamholz's avatar
Avi Flamholz committed
90 91
```

Elad Noor's avatar
Elad Noor committed
92 93 94 95 96
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
97

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

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