The BioElectric Tissue Simulation Engine (BETSE) is a discrete exterior calculus simulator for 2D computational multiphysics problems in the life sciences -- including (electro)diffusion, (electro)osmosis, galvanotaxis, voltage-gated ion channels, gene regulatory networks, and biochemical reaction networks.
Project description
BETSE (BioElectric Tissue Simulation Engine) is an open-source cross-platform discrete exterior calculus 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 portably implemented in pure Python 3, continuously stress-tested via GitHub Actions × tox × pytest × Codecov, and permissively distributed under the BSD 2-clause license.
Installation
BETSE is universally installable with either:
[Recommended] pip, the standard Python package manager:
pip install betse
Anaconda, a third-party Python package manager:
conda config --add channels conda-forge conda install betse
See our installation instructions for details, including best practices for Linux, macOS, and Windows usage, Git-based development, and Docker-based containerization.
Usage
BETSE installs the betse command, a low-level command line interface (CLI) ideal for advanced users.
BETSEE installs the betsee command, a high-level graphical user interface (GUI) ideal for all users – regardless of prior experience or familiarity with the command line.
Subcommands
The betse command accepts numerous subcommands (i.e., passed arguments indicating actions to be performed).
Try
The try subcommand creates a default simulation in the current directory and runs all requisite and optional phases of this simulation:
betse -v try
This subcommand is typically run as an initial smoke test verifying that BETSE was installed properly and operates as advertised. Specifically, this subcommand:
Enables verbosity with the -v option, simplifying issue reporting in the event of an unexpected error.
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.
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.
Seed, Init, and Sim
The seed, init, and sim subcommands run only the seed, initialization, and simulation phases (respectively) for the passed simulation. While the higher-level try subcommand conveniently runs all simulation phases, it’s often preferable to run only a single phase – particularly when experimenting with computationally expensive simulations.
A typical CLI-based workflow calls these subcommands in order:
Create a default simulation configuration in a new my_sim/ subdirectory of the current directory.
betse config my_sim/sim_config.yml
[Optional] Edit the new my_sim/sim_config.yml file with your favourite text editor.
Seed (i.e., create) a pseudo-random cell cluster from this configuration.
betse seed my_sim/sim_config.yml
[Optional] Export all enabled plots, animations, and comma-separated value (CSV) files from this seed.
betse plot seed my_sim/sim_config.yml
Initialize (i.e., calculate steady-state concentrations for) this seeded cluster.
betse init my_sim/sim_config.yml
[Optional] Export all enabled plots, animations, and comma-separated value (CSV) files from this initialization.
betse plot init my_sim/sim_config.yml
Simulate this initialized cluster.
betse sim my_sim/sim_config.yml
[Optional] Export all enabled plots, animations, and comma-separated value (CSV) files from this simulation.
betse plot sim my_sim/sim_config.yml
Options
BETSE provides a variety of command-line options and subcommands in addition to those synopsized above. The standalone betse and betse --help commands describe these options and subcommands as follows:
usage: betse [-h] [-v] [-V] [--log-file LOG_FILENAME]
[--log-level {all,debug,info,warning,error,critical,none}]
[--profile-type {none,call,size}]
[--profile-file PROFILE_FILENAME]
[--matplotlib-backend MATPLOTLIB_BACKEND_NAME] [--headless]
{config,seed,init,sim,sim-grn,plot,info,try} ...
The BioElectric Tissue Simulation Engine (BETSE) is a discrete exterior
calculus simulator for 2D computational multiphysics problems in the life
sciences -- including (electro)diffusion, (electro)osmosis, galvanotaxis,
voltage-gated ion channels, gene regulatory networks, and biochemical reaction
networks.
optional arguments:
-h, --help show this help message and exit
-v, --verbose print and log all messages verbosely
-V, --version print program version and exit
--log-file LOG_FILENAME
file to log to (defaults to
minimum level of messages to log to "--log-file"
(defaults to "info") [overridden by "--verbose"]
--profile-type {none,call,size}
type of profiling to perform (defaults to "none"):
* "none", disabling profiling
* "call", profiling callables (functions, methods)
* "size", profiling object sizes (requires "pympler")
--profile-file PROFILE_FILENAME
file to profile to unless "--profile-type=none"
(defaults to "/home/leycec/.betse/betse.prof")
--matplotlib-backend MATPLOTLIB_BACKEND_NAME
name of matplotlib backend to use (see: "betse info")
--headless enable headless mode (display no plots or animations)
[forces "--matplotlib-backend=agg"]
subcommands:
Exactly one of the following subcommands must be passed:
{config,seed,init,sim,sim-grn,plot,info,try}
config create a default config file for BETSE simulations
seed seed a new cell cluster for a config file
init initialize a seeded cell cluster for a config file
sim simulate an initialized cell cluster for a config file
sim-grn simulate a gene regulatory network for a config file
plot plot an initialized or simulated simulation
info print metadata synopsizing BETSE and current system
try create, init, simulate, and plot a sample simulation
subcommand help:
For help with a specific subcommand, pass the "-h" or "--help" option to that
subcommand. For example, for help with the "config" subcommand, run:
betse config --help
Documentation
BETSE also provides external documentation optimized for offline reading – complete with explanatory examples, sample plots, and ample screenshots:
Official BETSE 1.0 documentation. (PDF format; 75 pages.)
Official BETSE 0.4 documentation. (PDF format; 72 pages.)
Official BETSE 0.3 documentation. (PDF format; 77 pages.)
Tutorials
BETSE provides a range of hands-on tutorial materials, including simulation files to run key published simulations, as well as a Developer’s Tutorial demonstrating how to load and work with BETSE modules, methods, and simulations in external code projects:
Official BETSE Tutorial Simulation Packages. (YAML format.)
Official BETSE Developer’s Tutorial. (Jupyter Notebook format.)
Science
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:
Sodium (Na+).
Potassium (K+).
Chloride (Cl-).
Calcium (Ca2+).
Hydrogen (H+).
Anionic proteins (P-).
Bicarbonate (HCO-3).
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:
L-type Ca, T-type Ca, and P/Q-type Ca.
Leak and ligand-gated channels, including:
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:
Transmembrane voltage changes on perturbations to single cell membrane states and environmental ion concentrations.
Bioelectrical signals at large-scale cellular wound sites.
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). [1] 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:
Alexis Pietak and Michael Levin, 2017. Bioelectric gene and reaction networks: computational modelling of genetic, biochemical and bioelectrical dynamics in pattern regulation. (Supplement). [1] Journal of The Royal Society Interface, 14(134), p.20170425. https://doi.org/10.1098/rsif.2017.0425
Vaibhav P. Pai, Alexis Pietak, Valerie Willocq, Bin Ye, Nian-Qing Shi, and Michael Levin, 2018. HCN2 rescues brain defects by enforcing endogenous voltage pre-patterns. (Supplement). [1] Nature Communications. 9(1), p.998. https://doi.org/10.1038/s41467-018-03334-5
Javier Cervera, Alexis Pietak, Michael Levin, and Salvador Mafe, 2018. Bioelectrical coupling in multicellular domains regulated by gap junctions: A conceptual approach. Bioelectrochemistry. 128, pp.45—61. https://doi.org/10.1016/j.bioelechem.2018.04.013
Alexis Pietak and Michael Levin, 2018. Bioelectrical control of positional information in development and regeneration: A review of conceptual and computational advances. Progress in Biophysics and Molecular Biology. https://doi.org/10.1016/j.pbiomolbio.2018.03.008
Alexis Pietak, Johanna Bischof, Joshua LaPalme, Junji Morokuma, and Michael Levin, 2019. Neural control of body-plan axis in regenerating planaria. PLOS Computational Biology. https://doi.org/10.1371/journal.pcbi.1006904
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 the personal e-mail account of Dr. Pietak: [2]
Username: alexis {dot} pietak
Hostname: gmail {dot} com
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.
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.
Funding
BETSE is currently independently financed as a volunteer open-source project. Prior grant funding sources include (in chronological order):
For the five-year period spanning 2015—2019, BETSE was graciously 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.
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.
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.