Skip to main content

BETSE, the BioElectric Tissue Simulation Engine.

Project description

Linux Build Status Windows Build Status

BETSE

BETSE (BioElectric Tissue Simulation Engine) is an open-source cross-platform finite volume simulator for 2D computational multiphysics problems in the life sciences – including electrodiffusion, electro-osmosis, galvanotaxis, voltage-gated ion channels, gene regulatory networks, and biochemical reaction networks (e.g., metabolism). BETSE is associated with the Paul Allen Discovery Center at Tufts University and supported by a Paul Allen Discovery Center award from the Paul G. Allen Frontiers Group.

BETSE is portably implemented in pure Python 3, continuously stress-tested with GitLab-CI × Appveyor + py.test, and permissively distributed under the BSD 2-clause license.

BETSEE

BETSEE (BETSE Environment) is the official open-source cross-platform graphical user interface (GUI) for BETSE. BETSEE wraps the low-level command-line interface (CLI) bundled with BETSE in a high-level interactive modelling environment optimized for both new and advanced users alike.

Like BETSE, BETSEE is portably implemented in Python 3 and permissively distributed under the BSD 2-clause license. Unlike BETSE, BETSEE leverages the industry-standard PySide2-based Qt 5 application framework to deliver a modern scientific workflow.


Installation

BETSE currently supports Linux, macOS, and Windows out-of-the-box.

Simple

For new users, BETSE is portably installable as follows:

[1]The Windows Subsystem for Linux (WSL) and – hence BETSE itself – is only installable under Windows 10. Under older Windows versions, BETSE may be installed from a virtual Linux guest.
[2]Do not install the Python 2.7 variant of Anaconda. BETSE requires Python 3.x.
[3]If you prefer not to install Anaconda, BETSE dependencies are also manually installable via your platform-specific package manager (e.g., Homebrew on macOS, APT on Ubuntu Linux). Doing so is non-trivial and, where performed incorrectly, could produce a performance-crippled single-core installation of BETSE. Anaconda suffers no such issues and is guaranteed to produce a performance-optimized multicore installation of BETSE on all supported platforms. We strongly recommend Anaconda – even when you think you know better.
[4]

To open a POSIX-compatible terminal under:

  • Windows:
    1. Install Ubuntu Linux via the Windows Subsystem for Linux (WSL).
    2. Open an Ubuntu Linux terminal.
  • macOS:
    1. Open the Finder.
    2. Open the Applications folder.
    3. Open the Utilities folder.
    4. Open Terminal.app.
  • Ubuntu Linux:
    1. Type Ctrl+Alt+t.
[5]This command installs both the most recent stable release of BETSE and all mandatory and most optional dependencies of this release. Older stable releases are installable in a similar manner (e.g., conda install betse=0.7.0 for BETSE 0.7.0). All Anaconda packages are kindly hosted by the non-profit conda-forge organization.
[6]

This test command:

  1. Enables verbosity with the -v option, simplifying issue reporting in the event of an unexpected error.
  2. Creates a sample_sim/ subdirectory in the current directory, providing the default simulation for this release of BETSE. This includes all configuration files and resources referenced by these files.
  3. Runs all simulation phases (e.g., seed, initialization) of this simulation.

When finished, you may safely either:

  • Remove this subdirectory.
  • Rename this subdirectory (e.g., to my_sim/) to serve as a basis for subsequent simulations.
  • Preserve this subdirectory as is.

Advanced

For developers and advanced users, any version of BETSE – including the live repository and prior stable releases – is manually installable as follows:

  1. Install Python 3.x and all dependencies required by BETSE. Under:

    • Linux, install these dependencies via your distribution-specific package manager (e.g., APT under Debian-based distributions). Do not use pip.[7]
    • macOS, either:
      • (Recommended) Install the Python 3.x variant of Anaconda.
      • Or both:
        1. Install a third-party package manager (e.g., Homebrew, MacPorts). Apple does not provide a package manager out-of-the-box.
        2. Install these dependencies via that package manager. Do not use pip.[7]
    • Windows, install the Python 3.x variant of Anaconda.[8]
  2. Open a terminal.

  3. Download either:

    • The unstable BETSE repository as follows:

      1. Install Git.

      2. Clone the master branch of this repository.

        git clone https://gitlab.com/betse/betse.git
        
      3. Prepare for installation.

        cd betse
        
    • Any stable BETSE release, including the most recent, as follows:

      1. Visit our source tarball archive.

      2. Click the download icon to the right of the desired release and select Download tar.gz.

      3. Extract the downloaded tarball into the current directory.

        tar -xvzf betse-*.tar.gz
        
      4. (Optional) Remove this tarball.

        rm betse-*.tar.gz
        
      5. Prepare for installation.

        cd betse-*
        
  4. Install BETSE either:

    • (Recommended) Editably, installing a cross-platform symbolic link to the current BETSE codebase. Modifications to this code are applied immediately without requiring reinstallation.

      sudo python3 setup.py develop
      
    • Non-editably, installing a physical copy of the current BETSE codebase. Modifications to this code are ignored and thus require reinstallation.

      sudo python3 setup.py install
      
  5. (Optional) Test BETSE, running all modelling phases of a sample simulation from a new directory.

    cd /tmp && betse try
    
[7](1, 2) Do not install scientific dependencies (e.g., NumPy, SciPy) with either pip or easy_install; doing so typically degrades BETSE to single-core performance. To optimize BETSE across multiple cores, always install these dependencies with your platform-specific package manager (e.g., Homebrew, APT).
[8]Unlike Linux and macOS, Anaconda is (effectively) required under Windows. Due to Microsoft’s lack of support for POSIX-compliant toolchains, no reasonable alternatives for installing multicore-aware scientific dependencies exist.

Usage

BETSE installs the betse command, a low-level command line interface (CLI) designed for experienced users. The typical CLI-based workflow resembles:

  1. Create a default simulation configuration in a new my_sim/ subdirectory of the current directory.

    betse config my_sim/sim_config.yml
    
  2. [Optional] Edit the newly created sim_config.yml file with your favourite text editor.

  3. Create a pseudo-random cell cluster from this simulation configuration.

    betse seed my_sim/sim_config.yml
    
  4. [Optional] Plot this cell cluster.

    betse plot seed my_sim/sim_config.yml
    
  5. Initialize (i.e., calculate steady-state concentrations for) this cell cluster.

    betse init my_sim/sim_config.yml
    
  6. [Optional] Plot this initialized cell cluster.

    betse plot init my_sim/sim_config.yml
    
  7. Simulate this initialized cell cluster.

    betse sim my_sim/sim_config.yml
    
  8. [Optional] Plot this simulated cell cluster.

    betse plot sim my_sim/sim_config.yml
    

See the following external documents for detailed usage instructions – complete with explanatory examples, sample plots, and ample screenshots:

Alternately, our sister project BETSEE installs the betsee command, a high-level graphical user interface (GUI) designed for all users – regardless of prior experience or familiarity with the command line.

Introduction

BETSE simulates biorealistic electrochemical phenomena in gap junction-networked 2D cellular collectives. To predict bioelectric patterns and their spatio-temporal dynamics, BETSE:

  • Models ion channel and gap junction activity.
  • Tracks changes in ion concentration and net ionic charge.
  • Calculates endogenous voltages and currents.
  • Accepts simulation parameters, variables, and options as human-readable, well-commented configuration files in YAML format.
  • Exports simulation results to a variety of output formats, including:
    • Publication-quality:
      • Plots, charts, and animations driven by Matplotlib, the industry standard for open-source plot visualization.
      • Directed graphs (i.e., networks) driven by Graphviz, the industry standard for open-source graph visualization.
    • Internet-friendly compressed video driven by any of various popular open-source video encoders, including FFmpeg, Libav, and MEncoder.
    • Post-processable tabular data (e.g., comma-separated values (CSV)).
  • Imports bitmask images defining the shapes of:
    • Cell clusters.
    • Cell cluster regions localizing ion channel activity, typically signifying disparate types of adjacent tissue.

To assemble simple concepts into complex simulations, BETSE supplies a richly configurable, highly scalable biological toolset consisting of:

Ions

Simulations may enable arbitrary combinations of the principal ions implicated in bioelectrical signaling – including:

Ion Channels

Individual cells in simulations may enable arbitrary combinations of voltage-gated ion channels, each implementing the Hodgkin-Huxley (HH) formalism with experimentally-derived parameters sourced from reputable knowledge-based systems (e.g., Channelpedia). Explicitly supported channel types include:

Custom ion channels parametrized by user-selected constants may be trivially defined in the same manner (e.g., via a YAML-formatted configuration file).

Ion Pumps and Exchangers

For fine-grained control over cell dynamics, notable ion pumps and exchangers may also be selectively enabled – including:

Custom ion pumps and exchangers parametrized by user-selected constants may be trivially defined in the same manner (e.g., via a YAML-formatted configuration file).

Extracellular Space

Cells form interconnected intracellular networks via voltage-sensitive gap junction connections embedded within an extracellular environment, maintained by tight junctions at the cell cluster periphery. Simulation of this environment enables exploration of local field potentials, transepithelial potential, and ephaptic coupling between cells.

Biological Networks

Simulation of gene regulatory and biochemical reaction networks at both the cellular and mitochondrial level supports deep spatial analysis of otherwise intractable biological processes. Metabolism, disease, aging, and other genetic and epigenetic phenomena commonly associated with quasi-Big Data are all valid targets for exhaustive study with BETSE.

To integrate these potent control systems with bioelectrical signaling, the activity-modulated interaction between gene products and similar biochemicals is fully integrated with ion channels, ion pumps, and gap junctions.

Validation

BETSE is peer-reviewed software receiving continual evidence-based scrutiny. Simulation output is reproducibly synchronized with experimental observations on membrane permeability, resting potential, ion concentration, and similar real-world biophysical quantities. Predictable outcomes have been demonstrated for such well-known cases as:

Citation

BETSE is formally described in our introductory paper. Third-party papers, theses, and other texts leveraging BETSE should ideally cite the following:

Alexis Pietak and Michael Levin, 2016. Exploring instructive physiological signaling with the bioelectric tissue simulation engine (BETSE). (Supplement). [9] Frontiers in Bioengineering and Biotechnology, 4(55). https://doi.org/10.3389/fbioe.2016.00055

Subsequent papers expanding the BETSE architecture with additional theory, experimental results, and comparative metrics include:

[9](1, 2, 3) This article’s supplement extends the cursory theory presented by this article with a rigorous treatment of the mathematics, formalisms, and abstractions required to fully reproduce this work. If theoretical questions remain after completing the main article, please consult this supplement.

Contact

To contact Dr. Pietak, the principal developer of the BETSE codebase and first or second author of all above papers, cordially direct correspondence to either:

To report a software issue (e.g., bug, crash, or other unexpected behaviour) or request a new feature in BETSE, consider submitting a new issue to our issue tracker. Thanks in advance; it’s only through generous user contributions that your user experience can continue to improve.

[10]

To protect Dr. Pietak’s e-mail address against automated harvesting, this address has been intentionally obfuscated. Reconstruct the original address by:

  • Replacing the {dot} substring with the . charecter.
  • Concatenating the username and hostname strings with the @ character.

For this reason, consider directing correspondence to the anonymous contact form at Organic Mechanics instead.

Authors

BETSE comes courtesy a dedicated community of authors and contributors – without whom this project would be computationally impoverished, biologically misaligned, and simply unusable.

Thanks, all.

See Also

For prospective users:

  • Installation, detailing BETSE’s installation with exhaustive platform-specific instructions.

For prospective contributors:

  • Development, detailing development of the BETSE codebase – philosophy, workflow, and otherwise.
  • Testing, detailing testing of the BETSE codebase – continuous integration, manual testing, and otherwise.
  • Freezing, detailing conversion of the BETSE codebase into redistributable platform-specific executable binaries.

License

BETSE is open-source software released under the permissive BSD 2-clause license.

The logo prominently displayed on this project page is a flat Noun Project icon entitled “Cow,” kindly released under the permissive BSD-compatible CC BY 3.0 license by Maxim Kulikov.

Project details


Release history Release notifications

This version
History Node

0.8.4

History Node

0.8.3

History Node

0.8.2

History Node

0.8.1

History Node

0.8.0

History Node

0.7.0

History Node

0.6.1

History Node

0.6.0

History Node

0.5.0

History Node

0.4.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
betse-0.8.4-py3-none-any.whl (2.5 MB) Copy SHA256 hash SHA256 Wheel py3 Jun 26, 2018
betse-0.8.4.tar.gz (1.7 MB) Copy SHA256 hash SHA256 Source None Jun 26, 2018

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page