scBOLT is a software framework for inferring Boolean networks from multi-condition single-cell transcriptomic data.
Its main goal is to transform complex transcriptomic observations into biologically meaningful Boolean abstractions and dynamical constraints suitable for exact logical model inference. This remains a major challenge in data-driven logical modeling, particularly for poorly characterized biological systems and non-canonical cellular processes.
scBOLT combines transcriptome-derived state abstractions, user-defined dynamical constraints, and prior regulatory knowledge to generate inference-ready logical models through a reproducible and modular workflow.
- multi-condition logical modeling
- transcriptome-driven constraint engineering
- scalable exact Boolean network inference
- multiple macrostate characterisation and binarization strategies
- reusable intermediate entry points
- reproducible execution and dependency management
scBOLT relies on the BoNesis framework for exact Boolean network synthesis.
scBOLT requires:
- GNU Make (>= 4.3)
- One Conda-compatible environment backend:
Alternatively, scBOLT can run through Docker. In that mode, the local scbolt
command keeps the same interface and delegates execution to the scBOLT Docker
image.
Install the required system dependencies:
apt-get install build-essentialClone and configure the project:
git clone https://github.com/bnediction/scbolt.git scbolt
cd scbolt
./installTo use Docker as the default runtime backend:
./install --backend=dockerThis writes ~/.config/scbolt/config.mk, pulls the configured scBOLT image if
needed, and keeps normal commands such as scbolt bn-submin unchanged.
Initialize a project in any working directory:
mkdir my_project
cd my_project
scbolt init params.mkVerify the installation:
make checkLaTeX is optional. When available, scBOLT uses it for figure text rendering.
Otherwise, figures are generated with Matplotlib's native text renderer and
plain axis labels such as UMAP1 and PC1.
apt-get install texlive dvipng texlive-latex-extra texlive-fonts-recommended cm-super texlive-extra-utilsThe following resources are only required when starting from raw sequencing data:
- Cell Ranger (optional alternative to STAR for alignment and counting)
- Reference genomes and RepeatMasker annotations are downloaded automatically for supported organisms when needed.
For long-term reproducibility in raw FASTQ mode, back up RESOURCES_DIR
together with the project. scBOLT does not redistribute large third-party
reference archives.
A minimal runnable example is available in quickstart/. It uses the built-in
Nestorowa hematopoiesis dataset from BoNesisTools and runs scBOLT without any
manual data download.
See quickstart/README.md for the commands.
Generated files are written under PROJECT_DIR with separate namespaces:
omics/: reference-level single-cell objects, plots, trajectories, and macrostates;bin/: Boolean abstractions of cells and macrostates;infer/: BoNesis specifications, selected genes, and inferred Boolean networks;logs/: command logs.
This avoids collisions with condition names such as bin, infer, or logs.
Display available modules:
scbolt helpDisplay command-specific help:
scbolt init --help
scbolt config help
scbolt check --help
scbolt progress --help
scbolt clean helpCreate, update, or remove the project configuration:
scbolt init <params.mk>
scbolt init --show
scbolt init --removeIf <params.mk> does not exist, scbolt init creates a minimal parameter file.
Run a module:
scbolt <module...>Display effective configuration:
scbolt configPreview execution without running:
scbolt dry-run <module>Validate dependencies and configuration:
scbolt check <module>Display workflow progress:
scbolt progress
scbolt progress --all
scbolt progress bn-subminClean cache and logs, optionally with selected module outputs:
scbolt clean
scbolt clean --all
scbolt clean macrostates bn-subminWithout modules, scbolt clean asks before removing cache and logs.
With --all, it asks before removing cache, logs, and all generated module outputs.
| Option | Description |
|---|---|
--params=<file> |
Select the parameter file. |
--references=<condition...> |
Restrict execution to selected references. |
--reset-target=<module...> |
Rebuild from these modules. |
--trust-target=<module...> |
Trust all outputs from selected modules. |
--trust-existing |
Trust every existing scBOLT DAG output. |
--old-file=<file> |
Trust one existing scBOLT DAG file. |
--logging=false |
Disable persistent logging. |
--help |
Display command-specific help when supported. |
--raw |
Display raw config listing. |
--<parameter>=<value> |
Override any Make parameter using dash-separated option names. |
--prior-knowledge=<resource> |
Use collectri, dorothea, or a custom regulatory network. |
--trust-existing only trusts known DAG outputs present when the command
starts; missing outputs are built normally. --reset-target always takes
priority and excludes the requested rebuild path from trust.
Make-style assignments such as PRIOR_KNOWLEDGE=dorothea remain supported.
Advanced documentation is available in: man/, including rebuild controls in
man/rebuilds.md.
Examples:
scbolt bn-submin
scbolt bn-submin --references=ctrl
scbolt check velocity
scbolt bn-submin --logging=false
scbolt bn-submin --max-clauses=12Internally, scBOLT uses GNU Make as its workflow engine. Advanced users can
still call make directly when needed.
scbolt bn-submin --macrostate-files=my_macrostates.h5adRequired AnnData fields:
layers:
log-norm
obs:
macrostate
condition (for multi-condition projects)
obsm:
X_umap, X_tsne, or X_se (matching REPRESENTATION)
scBOLT reads expression from the named layers and does not use adata.X as a
fallback for this entry point.
scbolt bn-submin --binarization-file=my_binarization.csvThis allows scBOLT to integrate with existing single-cell analysis workflows and external trajectory inference methods.
Please report any bugs or ask questions here or contact contributors directly.
No license currently.
The project is currently intended for internal research use.
- Théo Roncalli
- Loïc Paulevé
- Élisabeth Remy