simble

simble is a BCR evolution simulator. It starts with a naive heavy and light chain pair, and models evolution and selection in the germinal center as well as migration out of germinal center. simble also has customizable sampling.

🌐 simble website

To cite the SimBLE package in publications, please use:

Fielding J, Wu S, Melton H, Du Plessis L, Fisk N, Hoehn K (2025). "TyCHE enables time-resolved lineage tracing of heterogeneously-evolving populations." bioRxiv 2025.10.21.683591 doi:10.1101/2025.10.21.683591 https://doi.org/10.1101/2025.10.21.683591

Documentation

For full, up-to-date documentation, information, and tutorials, please visit simble.readthedocs.io.

Installing simble

Clone this repo and install from local files:

# clone the repo however you like, eg
git clone https://github.com/hoehnlab/simble

# in the repo directory, install simble from local files
pip install .

# run
python3 -m simble -flags
# or
simble -flags

Quick Start

Note

The default simulation runs with selection, with no migration, sampling every 25 generations for 200 generations.

To specify an output folder for default simulation:

simble -o <path-to-folder>

To run a neutral-selection BCR simulation (using naive BCRs, heavy and light chains, and S5F mutation/substitution model):

simble --neutral [other args]

To run a uniformly neutral simulation (no selection, randomly generated starting nucleotide sequence, and uniform mutations/substitutions):

simble --uniform [other args]

To run a uniformly neutral simulation with a specified sequence length of 100:

simble --uniform --sequence-length 100 [other args]

To run with expected migration of one cell every 25 generations:

simble --migration-rate 0.04 [other args]

To run 5 clones in parallel across 2 processes, with expected migration of one cell every 10 generations with selection, and sampling every 10 generations for 100 generations:

simble -o ./current-results -n 5 --processes 2 --migration-rate 0.1 --samples 0 100 10

which is equivalent to

simble -o ./current-results -n 5 -p 2 --migration-rate 0.1 -s 0 100 10

Tip

Flags can be provided any order.

Frequently used arguments:

argument	abbr	default	description
--output	-o	cwd/results	folder for results
--number	-n	1	number of clones to simulate
--processes	-p	1	number of processes (multiprocessing)
--neutral			if provided, runs a neutral simulation
--uniform			if provided, runs a uniform neutral simulation
--migration-rate		0	expected number of cells that leave the germinal center each generation
--samples	-s	[0 200 25]	start, stop, step, to specify sample times other than the default
--quiet	-q		don't display progress bar

Development

Clone the repo and install necessary packages, which can be found in pyproject.toml:

# clone the repo however you like, eg
git clone https://github.com/hoehnlab/simble

# install requirements, up to date requirements can be found in pyproject.toml
pip install <requirement>

# run
python3 -m simble -flags

All arguments

Available arguments:

argument	abbr	default	description
Frequently used
--output	-o	cwd/results	folder for results
--number	-n	1	number of clones to simulate
--processes	-p	1	number of processes (multiprocessing)
--neutral			if provided, runs a neutral simulation
--uniform			if provided, runs a uniform neutral simulation
--migration-rate		0	expected number of cells that leave the germinal center each generation
--samples	-s	[0 200 25]	start, stop, step, to specify sample times for germinal center
Sampling
--other-samples		GC sample times	start, stop, step, to specify "Other" location sample times
--sample-size		50	specify sample size for 'GC' location
--sample-size-other		12	specify sample size for the 'Other' location
Model parameters
--sequence-length		370	length of the sequence to simulate if uniform
--antigen	-a	1000	amount of antigen
--heavy-shm		0.0008908272571108565	expected number of heavy chain mutations each division per site
--light-shm		0.0004923076923076923	expected number of light chain mutations each division per site
--target-mutations-heavy		5	number of amino acid mutations the target heavy chain should have
--target-mutations-light		2	number of amino acid mutations the target light chain should have
--cdr-dist			cdr distribution (constant or exponential)
--cdr-var			cdr variable
--fwr-dist			fwr distribution (constant or exponential)
--fwr-var			fwr variable
--multiplier	-m	2	selection multiplier
Program settings
--quiet	-q		if present, progress bar suppressed
--verbose	-v		if present, verbose information provided
--fasta			if present, also write a fasta file
--config			path to a config file (still in development)
--dev			if present, run in dev mode (not recommended)
--seed			an RNG seed to reproduce specific simulations

Thank you for using simble!