# 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.
:construction: This readme is still under construction. :construction:
## Installing simble
<!-- The easiest way to install simble is with pip:
```sh
pip install simble
``` -->
Clone this repo and install from local files:
```sh
# 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:
```sh
simble -o <path-to-folder>
```
To run a neutral-selection BCR simulation (using naive BCRs, heavy and light chains, and S5F mutation/substitution model):
```sh
simble --neutral [other args]
```
To run a uniformly neutral simulation (no selection, randomly generated starting nucleotide sequence, and uniform mutations/substitutions):
```sh
simble --uniform [other args]
```
To run a uniformly neutral simulation with a specified sequence length of 100:
```sh
simble --uniform --sequence-length 100 [other args]
```
To run with expected migration of one cell every 25 generations:
```sh
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:
```sh
simble -o ./current-results -n 5 --processes 2 --migration-rate 0.1 --samples 0 100 10
```
which is equivalent to
```sh
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:
```sh
# 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:
<table>
<tr>
<th>argument</th>
<th>abbr</th>
<th>default</th>
<th>description</th>
</tr>
<tr>
<td colspan=4> <b><i>Frequently used</i></b> </td>
</tr>
<tr>
<td>--output</td>
<td>-o</td>
<td>cwd/results</td>
<td>folder for results</td>
</tr>
<tr>
<td>--number</td>
<td>-n</td>
<td>1</td>
<td>number of clones to simulate</td>
</tr>
<tr>
<td>--processes</td>
<td>-p</td>
<td>1</td>
<td>number of processes (multiprocessing)</td>
</tr>
<tr>
<td>--neutral</td>
<td></td>
<td></td>
<td>if provided, runs a neutral simulation</td>
</tr>
<tr>
<td>--uniform</td>
<td></td>
<td></td>
<td>if provided, runs a uniform neutral simulation</td>
</tr>
<tr>
<td>--migration-rate</td>
<td></td>
<td>0</td>
<td>expected number of cells that leave the germinal center each generation</td>
</tr>
<tr>
<td>--samples</td>
<td>-s</td>
<td>[0 200 25]</td>
<td>start, stop, step, to specify sample times for germinal center</td>
</tr>
<tr>
<td colspan=4> <b><i>Sampling</i></b> </td>
</tr>
<tr>
<td>--other-samples</td>
<td></td>
<td>GC sample times</td>
<td>start, stop, step, to specify "Other" location sample times</td>
</tr>
<tr>
<td>--sample-size</td>
<td></td>
<td>50</td>
<td>specify sample size for 'GC' location</td>
</tr>
<tr>
<td>--sample-size-other</td>
<td></td>
<td>12</td>
<td>specify sample size for the 'Other' location</td>
</tr>
<tr>
<td colspan=4> <b><i>Model parameters</i></b> </td>
</tr>
<tr>
<td>--sequence-length</td>
<td></td>
<td>370</td>
<td>length of the sequence to simulate if uniform</td>
</tr>
<tr>
<td>--antigen</td>
<td>-a</td>
<td>1000</td>
<td>amount of antigen</td>
</tr>
<tr>
<td>--heavy-shm</td>
<td></td>
<td>0.0008908272571108565</td>
<td>expected number of heavy chain mutations each division per site</td>
</tr>
<tr>
<td>--light-shm</td>
<td></td>
<td>0.0004923076923076923</td>
<td>expected number of light chain mutations each division per site</td>
</tr>
<tr>
<td>--target-mutations-heavy</td>
<td></td>
<td>5</td>
<td>number of amino acid mutations the target heavy chain should have</td>
</tr>
<tr>
<td>--target-mutations-light</td>
<td></td>
<td>2</td>
<td>number of amino acid mutations the target light chain should have</td>
</tr>
<tr>
<td>--cdr-dist</td>
<td></td>
<td></td>
<td>cdr distribution (constant or exponential)</td>
</tr>
<tr>
<td>--cdr-var</td>
<td></td>
<td></td>
<td>cdr variable</td>
</tr>
<tr>
<td>--fwr-dist</td>
<td></td>
<td></td>
<td>fwr distribution (constant or exponential)</td>
</tr>
<tr>
<td>--fwr-var</td>
<td></td>
<td></td>
<td>fwr variable</td>
</tr>
<tr>
<td>--multiplier</td>
<td>-m</td>
<td>2</td>
<td>selection multiplier</td>
</tr>
<tr>
<td colspan=4> <b><i>Program settings</i></b> </td>
</tr>
<tr>
<td>--quiet</td>
<td>-q</td>
<td></td>
<td>if present, progress bar suppressed</td>
</tr>
<tr>
<td>--verbose</td>
<td>-v</td>
<td></td>
<td>if present, verbose information provided</td>
</tr>
<tr>
<td>--fasta</td>
<td></td>
<td></td>
<td>if present, also write a fasta file</td>
</tr>
<tr>
<td>--config</td>
<td></td>
<td></td>
<td>path to a config file (still in development)</td>
</tr>
<tr>
<td>--dev</td>
<td></td>
<td></td>
<td>if present, run in dev mode (not recommended)</td>
</tr>
<tr>
<td>--seed</td>
<td></td>
<td></td>
<td>an RNG seed to reproduce specific simulations</td>
</tr>
</table>
Thank you for using simble!
Raw data
{
"_id": null,
"home_page": null,
"name": "simble",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "B cell, B cell receptor, BCR, somatic hypermutation, SHM, germinal center, B cell differentiation, B cell development, repertoire, AIRR, immune system, adaptive immune system, immunology, biology",
"author": null,
"author_email": "Jessie Fielding <jessiejofielding@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/ae/c7/dad793ee11ee939fa9c5eafbde366343fb9cc0504f29dfe9a9cbe24c23a7/simble-0.0.2.tar.gz",
"platform": null,
"description": "# simble\n\nsimble is a BCR evolution simulator. It starts with a naive heavy and light chain pair,\nand models evolution and selection in the germinal center as well as migration out of \ngerminal center. simble also has customizable sampling.\n\n:construction: This readme is still under construction. :construction:\n\n\n## Installing simble\n\n<!-- The easiest way to install simble is with pip:\n\n```sh\npip install simble\n``` -->\n\nClone this repo and install from local files:\n\n```sh\n# clone the repo however you like, eg\ngit clone https://github.com/hoehnlab/simble\n\n# in the repo directory, install simble from local files\npip install .\n\n# run\npython3 -m simble -flags\n# or\nsimble -flags\n```\n\n\n## Quick Start\n\n>[!NOTE]\n>The default simulation runs with selection, with no migration, sampling every 25 generations for 200 generations. \n\nTo specify an output folder for default simulation:\n```sh\nsimble -o <path-to-folder>\n```\n\nTo run a neutral-selection BCR simulation (using naive BCRs, heavy and light chains, and S5F mutation/substitution model):\n```sh\nsimble --neutral [other args]\n```\n\nTo run a uniformly neutral simulation (no selection, randomly generated starting nucleotide sequence, and uniform mutations/substitutions):\n```sh\nsimble --uniform [other args]\n```\nTo run a uniformly neutral simulation with a specified sequence length of 100:\n```sh\nsimble --uniform --sequence-length 100 [other args]\n```\n\nTo run with expected migration of one cell every 25 generations:\n```sh\nsimble --migration-rate 0.04 [other args]\n```\n\nTo run 5 clones in parallel across 2 processes, with expected migration of one cell every 10 generations\nwith selection, and sampling every 10 generations for 100 generations:\n```sh\nsimble -o ./current-results -n 5 --processes 2 --migration-rate 0.1 --samples 0 100 10\n```\n\nwhich is equivalent to\n```sh\nsimble -o ./current-results -n 5 -p 2 --migration-rate 0.1 -s 0 100 10\n```\n\n>[!TIP]\n>Flags can be provided any order.\n\nFrequently used arguments:\n\n| argument | abbr | default | description |\n| -------- | ---------- | ------- | ------- |\n| --output | -o | cwd/results| folder for results |\n| --number | -n | 1 | number of clones to simulate |\n| --processes| -p | 1 | number of processes (multiprocessing) |\n| --neutral | | | if provided, runs a neutral simulation|\n| --uniform | | | if provided, runs a uniform neutral simulation |\n| --migration-rate| | 0 | expected number of cells that leave the germinal center each generation|\n| --samples | -s | [0 200 25] | start, stop, step, to specify sample times other than the default|\n| --quiet | -q | | don't display progress bar\n\n\n## Development\n\nClone the repo and install necessary packages, which can be found in pyproject.toml:\n\n```sh\n# clone the repo however you like, eg\ngit clone https://github.com/hoehnlab/simble\n\n# install requirements, up to date requirements can be found in pyproject.toml\npip install <requirement>\n\n# run\npython3 -m simble -flags\n```\n\n\n## All arguments\n\n\nAvailable arguments:\n\n<table>\n <tr>\n <th>argument</th>\n <th>abbr</th>\n <th>default</th>\n <th>description</th>\n </tr>\n <tr>\n <td colspan=4> <b><i>Frequently used</i></b> </td>\n </tr>\n <tr>\n <td>--output</td>\n <td>-o</td>\n <td>cwd/results</td>\n <td>folder for results</td>\n </tr>\n <tr>\n <td>--number</td>\n <td>-n</td>\n <td>1</td>\n <td>number of clones to simulate</td>\n </tr>\n <tr>\n <td>--processes</td>\n <td>-p</td>\n <td>1</td>\n <td>number of processes (multiprocessing)</td>\n </tr>\n <tr>\n <td>--neutral</td>\n <td></td>\n <td></td>\n <td>if provided, runs a neutral simulation</td>\n </tr>\n <tr>\n <td>--uniform</td>\n <td></td>\n <td></td>\n <td>if provided, runs a uniform neutral simulation</td>\n </tr>\n <tr>\n <td>--migration-rate</td>\n <td></td>\n <td>0</td>\n <td>expected number of cells that leave the germinal center each generation</td>\n </tr>\n <tr>\n <td>--samples</td>\n <td>-s</td>\n <td>[0 200 25]</td>\n <td>start, stop, step, to specify sample times for germinal center</td>\n </tr>\n <tr>\n <td colspan=4> <b><i>Sampling</i></b> </td>\n </tr>\n <tr>\n <td>--other-samples</td>\n <td></td>\n <td>GC sample times</td>\n <td>start, stop, step, to specify "Other" location sample times</td>\n </tr>\n <tr>\n <td>--sample-size</td>\n <td></td>\n <td>50</td>\n <td>specify sample size for 'GC' location</td>\n </tr>\n <tr>\n <td>--sample-size-other</td>\n <td></td>\n <td>12</td>\n <td>specify sample size for the 'Other' location</td>\n </tr>\n <tr>\n <td colspan=4> <b><i>Model parameters</i></b> </td>\n </tr>\n <tr>\n <td>--sequence-length</td>\n <td></td>\n <td>370</td>\n <td>length of the sequence to simulate if uniform</td>\n </tr>\n <tr>\n <td>--antigen</td>\n <td>-a</td>\n <td>1000</td>\n <td>amount of antigen</td>\n </tr>\n <tr>\n <td>--heavy-shm</td>\n <td></td>\n <td>0.0008908272571108565</td>\n <td>expected number of heavy chain mutations each division per site</td>\n </tr>\n <tr>\n <td>--light-shm</td>\n <td></td>\n <td>0.0004923076923076923</td>\n <td>expected number of light chain mutations each division per site</td>\n </tr>\n <tr>\n <td>--target-mutations-heavy</td>\n <td></td>\n <td>5</td>\n <td>number of amino acid mutations the target heavy chain should have</td>\n </tr>\n <tr>\n <td>--target-mutations-light</td>\n <td></td>\n <td>2</td>\n <td>number of amino acid mutations the target light chain should have</td>\n </tr>\n <tr>\n <td>--cdr-dist</td>\n <td></td>\n <td></td>\n <td>cdr distribution (constant or exponential)</td>\n </tr>\n <tr>\n <td>--cdr-var</td>\n <td></td>\n <td></td>\n <td>cdr variable</td>\n </tr>\n <tr>\n <td>--fwr-dist</td>\n <td></td>\n <td></td>\n <td>fwr distribution (constant or exponential)</td>\n </tr>\n <tr>\n <td>--fwr-var</td>\n <td></td>\n <td></td>\n <td>fwr variable</td>\n </tr>\n <tr>\n <td>--multiplier</td>\n <td>-m</td>\n <td>2</td>\n <td>selection multiplier</td>\n </tr>\n <tr>\n <td colspan=4> <b><i>Program settings</i></b> </td>\n </tr>\n <tr>\n <td>--quiet</td>\n <td>-q</td>\n <td></td>\n <td>if present, progress bar suppressed</td>\n </tr>\n <tr>\n <td>--verbose</td>\n <td>-v</td>\n <td></td>\n <td>if present, verbose information provided</td>\n </tr>\n <tr>\n <td>--fasta</td>\n <td></td>\n <td></td>\n <td>if present, also write a fasta file</td>\n </tr>\n <tr>\n <td>--config</td>\n <td></td>\n <td></td>\n <td>path to a config file (still in development)</td>\n </tr>\n <tr>\n <td>--dev</td>\n <td></td>\n <td></td>\n <td>if present, run in dev mode (not recommended)</td>\n </tr>\n <tr>\n <td>--seed</td>\n <td></td>\n <td></td>\n <td>an RNG seed to reproduce specific simulations</td>\n </tr>\n</table>\n\nThank you for using simble!\n",
"bugtrack_url": null,
"license": null,
"summary": "Simble is a simulation tool for B cell receptor (BCR) somatic hypermutation (SHM) and affinity maturation. Simble models B cells in the germinal center and their differentiation and migration to other tissues.",
"version": "0.0.2",
"project_urls": {
"Homepage": "https://github.com/hoehnlab/simble",
"Issues": "https://github.com/hoehnlab/simble/issues"
},
"split_keywords": [
"b cell",
" b cell receptor",
" bcr",
" somatic hypermutation",
" shm",
" germinal center",
" b cell differentiation",
" b cell development",
" repertoire",
" airr",
" immune system",
" adaptive immune system",
" immunology",
" biology"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "174b3702236184fd365779ffc7edde994a76d6e3b276a8fb869dcd71bd443c5a",
"md5": "4a71602a0683daa5f63d021f6f1db14c",
"sha256": "74ce946f8a3592e284832a34609851ff5913af2575d4d744c638406ac85b4df2"
},
"downloads": -1,
"filename": "simble-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4a71602a0683daa5f63d021f6f1db14c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12765165,
"upload_time": "2025-10-06T13:50:38",
"upload_time_iso_8601": "2025-10-06T13:50:38.614351Z",
"url": "https://files.pythonhosted.org/packages/17/4b/3702236184fd365779ffc7edde994a76d6e3b276a8fb869dcd71bd443c5a/simble-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "aec7dad793ee11ee939fa9c5eafbde366343fb9cc0504f29dfe9a9cbe24c23a7",
"md5": "6fe415459bebf0799c9d0410aaee6a37",
"sha256": "7a25d1b39dc6a6a34b7e41330aefe09c0766781b37c4ac824a9e178bcf0db119"
},
"downloads": -1,
"filename": "simble-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "6fe415459bebf0799c9d0410aaee6a37",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11512801,
"upload_time": "2025-10-06T13:50:41",
"upload_time_iso_8601": "2025-10-06T13:50:41.014696Z",
"url": "https://files.pythonhosted.org/packages/ae/c7/dad793ee11ee939fa9c5eafbde366343fb9cc0504f29dfe9a9cbe24c23a7/simble-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 13:50:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hoehnlab",
"github_project": "simble",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "simble"
}
JSON
