Package: betse
BETSE(BioElectricTissueSimulationEngine) is an open-source cross-platformdiscrete exterior calculussimulator
for 2D computational multiphysics problems in the life sciences – includingelectrodiffusion,electro-osmosis,galvanotaxis,voltage-gated ion
channels,gene regulatory networks, andbiochemical reaction networks(e.g., metabolism).BETSE isportably implementedin purePython 3,continuously stress-testedviaGitHub Actions×tox×pytest×Codecov, andpermissively distributedunder theBSD 2-clause license.ContentsInstallationUsageSubcommandsTrySeed, Init, and SimOptionsDocumentationTutorialsScienceIonsIon ChannelsIon Pumps and ExchangersExtracellular SpaceBiological NetworksValidationCitationContactAuthorsFundingLicenseSee AlsoInstallationBETSE is universally installable with either:[Recommended]pip, the standard Python package manager:pip3 install betseAnaconda, a third-party Python package manager:conda config --add channels conda-forge
conda install betseSee ourinstallation instructionsfor details, including best
practices forLinux,macOS, andWindows usage,Git-based development, andDocker-based containerization.UsageBETSE installs thebetsecommand, a low-level command line interface (CLI)
ideal for advanced users.BETSEEinstalls thebetseecommand, a high-level graphical user interface
(GUI) ideal forallusers – regardless of prior experience or familiarity
with the command line.SubcommandsThebetsecommand accepts numeroussubcommands(i.e., passed arguments
indicating actions to be performed).TryThetrysubcommand creates a default simulation in the current directory
and runs all requisite and optional phases of this simulation:betse -v tryThis subcommand is typically run as an initialsmoke testverifying that
BETSE was installed properly and operates as advertised. Specifically, this
subcommand:Enables verbosity with the-voption, simplifying issue reporting in the
event of an unexpected error.Creates asample_sim/subdirectory in the current directory, providing
the default simulation for this release of BETSE. This includesallconfiguration 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., tomy_sim/) to serve as a basis for
subsequent simulations.Preserve this subdirectory as is.Seed, Init, and SimTheseed,init, andsimsubcommands run only the seed,
initialization, and simulation phases (respectively) for the passed simulation.
While the higher-leveltrysubcommand conveniently runsallsimulation
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 newmy_sim/subdirectory
of the current directory.betse config my_sim/sim_config.yml[Optional] Edit the newmy_sim/sim_config.ymlfile withyour
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.ymlInitialize (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.ymlSimulate 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.ymlOptionsBETSE provides a variety of command-line options and subcommands in addition to
those synopsized above. The standalonebetseandbetse--helpcommands
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 --helpDocumentationBETSE also provides external documentation optimized for offline reading –
complete with explanatory examples, sample plots, and ample screenshots:OfficialBETSE 1.0 documentation. (PDF format; 75 pages.)OfficialBETSE 0.4 documentation. (PDF format; 72 pages.)OfficialBETSE 0.3 documentation. (PDF format; 77 pages.)TutorialsBETSE provides a range ofhands-on tutorial materials,
including simulation files to run key published simulations, as well as aDeveloper’s Tutorialdemonstrating how to load and work
with BETSE modules, methods, and simulations in external code projects:OfficialBETSE Tutorial Simulation Packages. (YAML
format.)OfficialBETSE Developer’s Tutorial. (Jupyter
Notebook format.)ScienceBETSE simulates biorealistic electrochemical phenomena ingap junction-networked 2D cellular collectives. To predictbioelectric patternsand their spatio-temporal dynamics, BETSE:Modelsion channelandgap junctionactivity.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 inYAMLformat.Exports simulation results to a variety of output formats, including:Publication-quality:Plots, charts, and animations driven byMatplotlib, the industry
standard for open-source plot visualization.Directed graphs(i.e., networks) driven byGraphviz, the industry
standard for open-source graph visualization.Internet-friendly compressed video driven by any of various popular
open-source video encoders, includingFFmpeg,Libav, andMEncoder.Post-processable tabular data (e.g.,comma-separated values (CSV)).Imports bitmask images defining the shapes of:Cell clusters.Cell cluster regions localizingion channelactivity, 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:IonsSimulations 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 ChannelsIndividual cells in simulations may enable arbitrary combinations ofvoltage-gated ion channels, each implementing theHodgkin-Huxley (HH)
formalismwith experimentally-derived parameters sourced from reputableknowledge-based systems(e.g.,Channelpedia). Explicitly supported channel
types include:HCN1,HCN2, andHCN4.L-type Ca,T-type Ca, andP/Q-type Ca.Kir2.1.Kv1.1,Kv1.2,Kv1.5.Kv3.3, andKv3.4.Nav1.2,Nav1.3, andNav1.6.Leakandligand-gated channels, including:Calcium-gated K+channels.Custom ion channels parametrized by user-selected constants may be trivially
defined in the same manner (e.g., via aYAML-formatted configuration file).Ion Pumps and ExchangersFor fine-grained control over cell dynamics, notable ion pumps and exchangers
may also be selectively enabled – including:Ca2+-ATPase.H+/K+-ATPase.Na+/K+-ATPase.V-ATPase.Custom ion pumps and exchangers parametrized by user-selected constants may be
trivially defined in the same manner (e.g., via aYAML-formatted
configuration file).Extracellular SpaceCells form interconnected intracellular networks via voltage-sensitivegap
junction connectionsembedded within anextracellular
environment, maintained bytight junctionsat the cell cluster periphery.
Simulation of this environment enables exploration oflocal field
potentials,transepithelial potential, andephaptic couplingbetween
cells.Biological NetworksSimulation ofgene regulatoryandbiochemical
reaction networksat both the cellular and mitochondrial level supports deep
spatial analysis of otherwise intractable biological processes. Metabolism,
disease, aging, and othergeneticandepigeneticphenomena commonly associated with quasi-Big Dataare all
valid targets for exhaustive study with BETSE.To integrate these potent control systems with bioelectrical signaling, theactivity-modulated interaction betweengene productsand similar biochemicals is fully integrated withion channels,ion pumps, andgap junctions.ValidationBETSE is peer-reviewed software receiving continual evidence-based scrutiny.
Simulation output is reproducibly synchronized with experimental observations onmembrane permeability,resting potential, ion concentration, and similar
real-world biophysical quantities. Predictable outcomes have been demonstrated
for such well-known cases as:Transmembrane voltage changeson perturbations
to single cell membrane states and environmental ion concentrations.Transepithelial potential differences (TEPD).Bioelectrical signals at large-scale cellular wound sites.CitationBETSE is formally described in ourintroductory paper.
Third-party papers, theses, and other texts leveraging BETSE should ideally
cite the following:Alexis PietakandMichael 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.00055Subsequent papers expanding the BETSE architecture with additional theory,
experimental results, and comparative metrics include:Alexis PietakandMichael 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.0425Vaibhav P. Pai,Alexis Pietak, Valerie Willocq, Bin Ye, Nian-Qing Shi,
andMichael 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-5Javier 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.013Alexis PietakandMichael 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.008Alexis Pietak, Johanna Bischof, Joshua LaPalme, Junji Morokuma, andMichael Levin, 2019.Neural control of body-plan axis in regenerating planaria.PLOS Computational Biology.https://doi.org/10.1371/journal.pcbi.1006904[1](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.ContactTo contactDr. 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 ofDr. Pietak:[2]Username:alexis{dot}pietakHostname:gmail{dot}comTo report a software issue (e.g., bug, crash, or other unexpected behaviour)orrequest a new feature in BETSE, considersubmitting a new issueto ourissue tracker. Thanks in advance; it’s only through
generous user contributions that your user experience can continue to improve.[2]To protect Dr. Pietak’s e-mail address againstautomated 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.AuthorsBETSE comes courtesy a dedicated community ofauthorsandcontributors– without whom this project would be computationally impoverished,
biologically misaligned, and simply unusable.Thanks, all.FundingBETSE 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 thePaul Allen Discovery CenteratTufts Universityand supported
by aPaul Allen Discovery Center awardfrom thePaul G. Allen Frontiers
Group.LicenseBETSE is open-source softwarereleasedunder the permissiveBSD
2-clause license.The logo prominently displayed on thisproject pageis a flatNoun Projecticon entitled“Cow,”kindly releasedunder the permissiveBSD-compatibleCC BY 3.0 licensebyMaxim Kulikov.See AlsoFor 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.