Skip to content

Latest commit

 

History

History
259 lines (179 loc) · 14 KB

README.md

File metadata and controls

259 lines (179 loc) · 14 KB

  tellurium

Read the Docs GitHub version
Licence PyPI - Downloads Funding Funding PyPI version
DOI

Copyright 2014-2023 Kiri Choi, J Kyle Medley, Matthias König, Kaylene Stocking, Caroline Cannistra, Michal Galdzicki, Ciaran Welsh, Lucian Smith, Adel Heydarabadipour, and Herbert Sauro

What is it?

Tellurium is a comprehensive Python accessible SBML-compliant modeling platform for biochemical reaction systems.

Introduction

For installation instructions scroll down a few sections.

Tellurium is a python environment for reproducible dynamical modeling of biological networks. Tellurium provides the interface code to convert between standard formats and uses powerful libraries without requiring technical expertise, allowing teh user to focus on what’s important: building better models. Tellurium also provides first-class support for exchangeability via COMBINE archives and SBML, allowing you to share your models and simulations with many other tools.

Tellurium combines state-of-the-art scientific Python libraries, such as NumPy and SciPy, and includes special-purpose systems biology Python tools. Out of the box, Tellurium includes the high performance simulation engine libroadrunner, the model descrption language antimony, phrasedml, libsbml, and libsedml.

The Tellurium (and libroadrunner project) project is funded from the NIH/NIGMS (GM081070) and NIH/NIBIB U24EB028887.

Documentation

Usage Example

import tellurium as te

r = te.loada('''
      S1 -> S2; k1*S1
      S1 = 10; S2 = 0
      k1 = 0.1
''')

result = r.simulate(0, 40, 500) 
r.plot()

Installation Instructions

❗Attention to those using Python 2.7 : Python 2.7 reached EOL on January 1st, 2020. Support for Python 2.7 has been dropped, though previous releases will continue to be available.

Tellurium can be installed as a Python package, with a front-end (Notebook, IDE), or in a cloud environment (Google Colab):

A. Python Pip

B. IDE front-end based on Spyder

C. Notebook front-end

D. Google Colab

We recommend first-time users choose one of the front-ends, while developers looking to integrate Tellurium use the pip package. All python desktop IDE graphical front-ends should work. We know for certain that telluirum will work from Spyder, pyCharm and Visual Studio Code.

The IDE front-end provides a MATLAB like experience with a code editor and Python console. The notebook front-end provides a notebook interface similar to Jupyter, and features notebook cells for inline OMEX, a human-readable representation of COMBINE archives.

For any issues with installation and setup, please check FAQ or contact us.

Install via pip

PyPI version

If you have a version of Python in an environment you're comfortable with, you can add Tellurium with pip:

pip install tellurium

This will install on all platforms. For Colab see the end of this screen.

For those using Anaconda, we currently do not have a separate Anaconda version of Tellurium, so you'll need to install it via pip, as above.

❗For detailed instructions on how to setup Tellurium on Anaconda distributions, see this page.

For developers, the latest stable version from the repository can be installed via

pip install git+https://github.com/sys-bio/tellurium.git

Front-end installation

Windows


Approach 1: Spyder for Tellurium IDE

The Tellurium Spyder installers are tested with Windows 10 and 11, and come with a choice of Python versions.

❗Attention to those upgrading to Tellurium Spyder IDE from an older version : We strongly suggest you to completely remove the older version of Tellurium Spyder IDE prior to installing the latest version.

  1. Download Tellurium Spyder for Windows:
  2. Double-click the installer to start the installation
  3. Follow the instructions

If you wish to use a different version of Python, you'll need to install Tellurium from the windows command line by using the command: pip install tellurium

NOTE: Installation requires administrative rights. It is recommended to accept the default settings.

Approach 2: Thonny IDE for Python

Tellurium can be used with Thonny, a free, open-source IDE for Python that is designed for beginners.

  1. Download the latest version of Thonny for Windows
  2. Double-click the installer *.exe to start the installation
  3. Follow the instructions
  4. Launch Thonny
  5. Go to Tools > Manage packages...
  6. Type tellurium in the search box and press the "Search on PyPI" button
  7. Once the tellurium package is found in "Search results", click on it, and then press the "Install" button. Wait until the installation process is completed.

 

Mac OS X


For Mac users there a a number of options. By far, the easiest is to use the self-cotbained Thonny Python IDE.

Approach 1: Thonny IDE for Python

Tellurium can be used with Thonny, a free, open-source IDE for Python that is designed for beginners.

  1. Download the latest version of Thonny for Mac OS X
  2. Double-click the installer *.pkg to start the installation
  3. Follow the instructions
  4. Launch Thonny from Spotlight or directly from your Applications folder
  5. Go to Tools > Manage packages...
  6. Type tellurium in the search box and press the "Search on PyPI" button
  7. Once the tellurium package is found in "Search results", click on it, and then press the "Install" button. Wait until the installation process is completed.

Approach 2: Spyder for Tellurium IDE

  1. Download the Anaconda distribution for Mac OS X..

  2. Follow the installer instructions.. The installer will install Spyder as part of the installation process. If you customize the installation, you will have a chance to select which packages to install - ensure Spyder is selected.

  3. When prompted, add Anaconda to your PATH (optional, but this will make the following steps easier).

  4. Open a Terminal and run the command:

conda install msgpack-python

Next, install Tellurium itself:

pip install tellurium

If this fails, try using the default absolute path to Anaconda, which will probably be something like:

/Users/<your-user>/opt/anaconda3/bin/pip install tellurium
  1. Launch the Anaconda Navigator via Launchpad. In Anaconda Navigator, run Spyder and then try import tellurium within the Spyder editor or console.

Approach 3: Spyder for Tellurium IDE (only for Mac OS X Legacy)

Currently, only a Legacy version of the Mac Spyder IDE is available.

  1. Download Tellurium IDE for Mac OS X 10.10 or later
  2. Double-click the .dmg file to open a new window
  3. Double-click the Spyder icon

For those who wish to use Tellurium with Spyder IDE on Mac OS X, we also suggest that you install through Anaconda by following the instructions on this page.

 

Linux (RedHat)


Linux (Debian)


For those who wish to use Tellurium with Spyder IDE on Linux, we also suggest that you install through Anaconda by following the instructions on this page.

❓Looking for old releases? You can find them here. To install an old release over a new release, you will need to manually wipe the data directory.

Google Colab

Tellurium can be used entirely in a browser using Google Colab. Ideally, it will work with the following steps (updated May 2023)

  1. run a cell with !pip install -q tellurium
  2. (Very important) Restart the runtime (From the menu: 'Runtime / Restart session')
  3. Test by typing import tellurium as te
  4. te.getVersionInfo() # Check for versions if you want to Try a model
  5. r = te.loada ('S1 -> S2; k1*S1; k1 = 0.1; S1 = 10'); r.simulate(); r.plot()

The Python version behind Colab changes periodically, so what worked one day may stop working the next, but the following Colab notebook worked when used at ICSB 2022: https://colab.research.google.com/drive/1wddLftHNhetbozZY29r2HRkzQLl1F_fs#scrollTo=l1bCgW46-adR and will hopefully be instructive.

Citing

If you use Tellurium in your research, we would appreciate following citations in any works you publish:

Medley et al. (2018). "Tellurium notebooks—An environment for reproducible dynamical modeling in systems biology." PLoS Computational Biology, 14(6), e1006220.

Choi et al. (2018). "Tellurium: An extensible python-based modeling environment for systems and synthetic biology." Biosystems, 171, 74-79.

Contact Us

For general questions, requesting help, or reporting bugs, feel free to use the GitHub issue tracker. You can also post to the Tellurium-discuss mailing list.

Legal

The source code for the Tellurium Python package is hosted at https://github.com/sys-bio/tellurium and is licensed under the Apache License, Version 2.0. Tellurium uses third-party dependencies which may be licensed under different terms. Consult the documentation for the respective third-party packages for more details.

TELLURIUM AND ALL SOFTWARE BUNDLED WITH TELLURIUM (HEREAFTER "THE SOFTWARE") IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THE SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.