eQuilibrator overview

A command-line API with minimal dependencies for calculation of standard thermodynamic potentials of biochemical reactions using the data found on eQuilibrator. It can be used without a network connection.

Current Features

  • Example scripts for singleton and bulk calculations.

  • Calculation of standard Gibbs potentials of reactions (together with confidence intervals).

  • Calculation of standard reduction potentials of half-cells.

To access more advanced features, such as adding new compounds that are not among the 500,000 currently in the MetaNetX database, try using our Component Contribution package.

Cite us

If you plan to use results from equilibrator-api in a scientific publication, please cite our paper: Consistent Estimation of Gibbs Energy Using Component Contributions 2

Installation

Step 1

The easiest way to get eQuilibrator-API up and running is using virtualenv, PyPI, and Jupyter notebooks

virtualenv -p python3 equilibrator
source equilibrator/bin/activate
pip install equilibrator-api jupyter

If you are using a Windows environment, we recommend using conda instead of pip:

conda install -c conda-forge equilibrator-api

Step 2

Then run this command to initialize eQuilibrator:

python3 -c "from equilibrator_api import ComponentContribution; cc = ComponentContribution()"

Note, that this can take minutes or even up to an hour, since about 1.3 GBytes of data need to be downloaded from a remote website (Zenodo). If this command fails, try improving the speed of your connection (e.g. disabling your VPN, or using a LAN cable to connect to your router) and running it again.

IMPORTANT: If you don’t complete this command and try running ComponentContribution from a Jupyter notebook, it will fail and you will see the following error message:

RetryError: RetryError[<Future at *********** state=finished raised RuntimeError>]

Step 3 (optional)

Now, you are good to go. In case you want to see an example of how to use eQuilibrator-API in the form of a Jupyter notebook, run the following commands:

curl https://gitlab.com/equilibrator/equilibrator-api/-/raw/develop/scripts/equilibrator_cmd.ipynb > equilibrator_cmd.ipynb
jupyter notebook

and select the notebook called equilibrator_cmd.ipynb and follow the examples in it.

Example Usage

Import the API and create an instance. Creating the ComponentContribution class instance reads all the data that is used to calculate thermodynamic potentials of reactions. It is normal for it to take 10-20 seconds to execute.

from equilibrator_api import ComponentContribution, Q_
cc = ComponentContribution()

  • IMPORTANT NOTE - versions 0.3.2+ on PyPI introduces support for Magnesium ion concentration (pMg). Almost all Gibbs energy estimates are affected, and therefore current estimates are not backward-compatible. To revert to the previous estimates, initialize using: cc = ComponentContribution.legacy() instead of the default constructor.

You can parse a reaction formula that uses compound accessions from different databases (KEGG, ChEBI, MetaNetX, BiGG, and a few others). The following example is ATP hydrolysis to ADP and inorganic phosphate, using KEGG compound IDs:

rxn = cc.parse_reaction_formula("kegg:C00002 + kegg:C00001 = kegg:C00008 + kegg:C00009")

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 format (e.g. forgetting to balance water is a common mistake) and so we always check ourselves.

if not rxn.is_balanced():
print('%s is not balanced' % rxn)

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.

cc.p_h = Q_(6.5)  # set pH
cc.ionic_strength = Q_("200 mM")  # set I

print(f"ΔG0 = {cc.standard_dg(rxn)}")
print(f"ΔG'0 = {cc.standard_dg_prime(rxn)}")
print(f"ΔG'm = {cc.physiological_dg_prime(rxn)}")

You can also calculate the reversibility index for this reaction.

print(f"ln(Reversibility Index) = {cc.ln_reversibility_index(rxn)}")

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 our paper for more information 1.

Pathway analysis tools have been ported to a new project

Running Max-min Driving Force (MDF) or Enzyme Cost Minimization (ECM) anslyses is no longer part of equilibrator-api and has been ported to a separate project names equilibrator-pathway. Note, that the pathway configuration file format used in previous versions of equilibrator-api (prior to 0.2.7) is not longer supported. You can find code and configuration file examples in the new repository.

Further examples for reaction parsing

We support several compound databases, not just KEGG. One can mix between several sources in the same reaction, e.g.:

rxn = cc.parse_reaction_formula("kegg:C00002 + CHEBI:15377 = metanetx.chemical:MNXM7 + bigg.metabolite:pi")

Or, you can use compound names instead of identifiers. However, it is discouraged to use in batch, since we only pick the closest hit in our database, and that can often be the wrong compound. Always verify that the reaction is balanced, and preferably also that the InChIKeys are correct:

rxn = cc.search_reaction("beta-D-glucose = glucose")
print(rxn)

In this case, the matcher arbitrarily chooses alpha-D-glucose as the first hit for the name glucose. Therefore, it is always better to use the most specific synonym to avoid mis-annotations.

Dependencies

  • python >= 3.6

  • equilibrator-cache

  • component-contribution

  • numpy

  • scipy

  • pandas

  • python-Levenshtein-wheels

  • pint

  • path

  • appdirs

  • diskcache

  • httpx

  • tenacity

  • periodictable

  • uncertainties

  • pyzenodo3

  • python-slugify

  • cobra (optional)

1

Elad Noor, Arren Bar-Even, Avi Flamholz, Yaniv Lubling, Dan Davidi, and Ron Milo. An integrated open framework for thermodynamics of reactions that combines accuracy and coverage. Bioinformatics, 28(15):2037–2044, August 2012. URL: https://academic.oup.com/bioinformatics/article/28/15/2037/237811 (visited on 2018-06-20), doi:10.1093/bioinformatics/bts317.

2

Elad Noor, Hulda S. Haraldsdóttir, Ron Milo, and Ronan M. T. Fleming. Consistent Estimation of Gibbs Energy Using Component Contributions. PLOS Computational Biology, 9(7):e1003098, July 2013. URL: http://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1003098 (visited on 2017-12-13), doi:10.1371/journal.pcbi.1003098.