Appendix A — Installing the tools

A.1 No installation: BNG Playground

BNG Playground runs BioNetGen in a web browser. Paste any model from this book into its editor and click Run. It is the quickest way to try a model, and it works on any computer.

A.2 Visual Studio Code

  1. Install Visual Studio Code.
  2. In the Extensions panel, search for BioNetGen and install it.
  3. Open a .bngl file and click the run button in the editor toolbar. Results are written to a time-stamped folder and the main output (.gdat) opens in a plot viewer.

The extension needs Python and Perl. It installs PyBioNetGen, which contains BioNetGen itself, when first used. macOS and Linux include Perl. On Windows, install Strawberry Perl.

To keep results out of your working folders, set bngl.general.result_folder in VS Code’s settings to an absolute path, for example a BNG-results folder in your project.

A.3 Python

The book’s Python code uses two BioNetGen packages and the standard scientific packages:

  • bngsim: fast ODE, stochastic, and network-free simulation of BioNetGen models, run in-process from Python.
  • PyBioNetGen: supplies BioNetGen, which bngsim uses to turn a .bngl file into a reaction network.
  • numpy, pandas, and matplotlib for analysis and plotting, and jupyter for notebooks.

Install them with

pip install bngsim bionetgen numpy pandas matplotlib jupyter

Every model and figure in the book runs through this route. BNG Playground and the VS Code extension run most models, but they may not support every feature used in later chapters, such as network-free simulation through bngsim. If a model fails in one of them, run it from Python.

A.4 The book’s models and code

The models are in the book’s repository on GitHub. Download it, either as a ZIP file from the repository page or with git:

git clone https://github.com/RuleWorld/bionetgen-book.git
cd bionetgen-book

Paths such as models/ch01/stat_step1_binding.bngl in the book are relative to this folder. Check the installation by running Python from the folder and simulating the first model of Chapter 1:

import bngsim
model = bngsim.Model.from_bngl("models/ch01/stat_step1_binding.bngl")
sim = bngsim.Simulator(model, method="ode")
model.reset()
result = sim.run(t_span=(0, 20), n_points=101)
print(result.observables["LR"][-1])   # about 0.989

The chapters also use a few helper functions, for example to display model files and generated networks, from scripts/bookutils.py. Each chapter imports them in a hidden cell at the start. To run a chapter’s code yourself, start Python in the repository folder and run

import sys
sys.path.insert(0, "scripts")
from bookutils import *

A.5 Reproducing the book

To reproduce every figure and number, create the environment used to build the book, which also installs Quarto and Graphviz, the program that lays out the contact maps and rule diagrams:

conda env create -f environment.yml
conda activate bionetgen-book
quarto render

Stochastic simulations in the book set their random seeds, so they give the same results with the same software versions. This version of the book was built with the following versions:

package version
Python 3.12.15
bngsim 0.16.0
bionetgen 0.8.7
numpy 2.5.4
pandas 3.0.6
matplotlib 3.11.2