ChromBERT-tools: A versatile toolkit for context-specific regulatory representations of transcription regulators across different cell types

ChromBERT is a pre-trained foundation model designed to capture genome-wide co-association patterns of ~1,000 transcription regulators and to learn context-specific transcriptional regulatory networks (TRNs) ChromBERT.

ChromBERT-tools is a lightweight toolkit built upon ChromBERT that operationalizes context-specific regulatory representations for user data through modular command-line interfaces and Python APIs organized into three functional layers: representation generation, predictive modeling, and regulatory interpretation.

For users who prioritize computational efficiency, ChromBERT-tools also supports ChromBERT-Lite as an optional lightweight model. See ChromBERT-Lite model option for details.

A short video tutorial is available to introduce ChromBERT-tools, including installation and a representative example workflow.

Watch on: YouTube | Bilibili

---

1. Installation

ChromBERT-tools is implemented in Python and requires Python 3.9 or above. It uses FlashAttention 2 for efficient model computation. We provide two installation options.

Option 1: Install with an Apptainer image (recommended)

# Install Apptainer.
conda install -c conda-forge apptainer
# Pull the official image.
apptainer pull chrombert-tools.sif oras://docker.io/chenqianqian515/chrombert-tools:20260509
# Check installation.
apptainer exec /path/to/chrombert-tools.sif chrombert-tools -h

Optional: If apptainer pull fails, download the image from the Google Drive link instead: chrombert-tools

Optional: Update the Apptainer image

If you need to add new packages or update existing ones, edit edit_image.def and rebuild the image. Here we update ChromBERT-tools as an example:

git clone https://github.com/TongjiZhanglab/ChromBERT-tools.git
cd ChromBERT-tools
apptainer build <new_image_name>.sif edit_image.def

Option 2: Install from source

# Create and activate a conda environment.
conda create -n ChromBERT python=3.9 -y
conda activate ChromBERT
# Install PyTorch (< 2.4) with a CUDA version compatible with your system.
# Example for CUDA 12.1:
pip install torch==2.2.2 torchvision==0.17.2 torchaudio==2.2.2 --index-url https://download.pytorch.org/whl/cu121
# Install FlashAttention 2. 
pip install "flash-attn==2.4.*" --no-build-isolation
# Install bedtools
conda install -c conda-forge -c bioconda bedtools
# Install ChromBERT-tools and ChromBERT.
git clone https://github.com/TongjiZhanglab/ChromBERT-tools.git
cd ChromBERT-tools
pip install .
# Check installation.
chrombert-tools -h

Optional:

If building flash-attn fails, we recommend downloading a pre-built flash-attn wheel that matches your Python, PyTorch, CUDA, and Linux environment..

wget https://github.com/Dao-AILab/flash-attention/releases/download/v2.4.3.post1/flash_attn-2.4.3.post1+cu122torch2.2cxx11abiFALSE-cp39-cp39-linux_x86_64.whl
pip install /path/to/flash_attn-*.whl  # Replace this with your downloaded wheel file.

2. Download required resources

With the Apptainer image

# Download ChromBERT pre-trained model files to ~/.cache/chrombert/data.
apptainer exec /path/to/chrombert-tools.sif download-data --genome hg38 --resolution 1kb
# If Hugging Face is slow, specify a mirror endpoint.
apptainer exec /path/to/chrombert-tools.sif download-data --genome hg38 --resolution 1kb --hf-endpoint <Hugging Face endpoint>

With a source install

# Activate the conda environment above command.
conda activate ChromBERT
# Download required ChromBERT resources.
download-data --genome hg38 --resolution 1kb
# If Hugging Face is slow, specify a mirror endpoint.
download-data --genome hg38 --resolution 1kb --hf-endpoint <Hugging Face endpoint>

3. Usage

ChromBERT-tools supports two ways to run:

• Command-line interface (CLI) — run from a terminal (bash commands)
• Python API — call functions in Python code

For usage examples, see the Jupyter notebooks in examples/cli/ and examples/api/.

You can run the examples with Jupyter Notebook:

cd ChromBERT-tools/examples/
apptainer exec --nv /path/to/chrombert-tools.sif jupyter-notebook # start Jupyter Notebook with GPU support

For detailed usage, please check the documentation: chrombert-tools.readthedocs.io.

1) Generation of context-specific regulatory representations

Command	Description	Tutorials
embed_region	Extract embeddings for specified genomic regions or promoter-centered gene regions	CLI, API
embed_regulator	Extract regulator embeddings for specified regulators across specified genomic regions	CLI, API

2) Predictive modeling of context-specific regulatory representations

Command	Description	Tutorials
region_function_classification	Classify genomic regions into functional classes	CLI, API
region_activity_regression	Predict quantitative region activity, such as accessibility or activity fold change	CLI, API
gene_activity_regression	Predict gene expression or expression fold change from TSS-centered regulatory context	CLI, API

3) Interpretation of context-specific regulatory representations

Command	Description	Tutorials
interpret_region_region_interactions	Identify functionally similar genomic regions	CLI, API
interpret_regulator_regulator_interactions	Identify potentially cooperative regulators	CLI, API
interpret_regulator_effects_between_region_groups	Compare regulator effects between region groups	CLI, API

Integrated module workflow

We provide an integrated workflow that combines the above commands to infer cell-type-specific enhancer–promoter interactions: infer cell-type-specific enhancer–promoter interactions.

End-to-end application commands

Command	Description	Tutorials
predict_cell_type_master_regulators	Infer cell-type-specific key regulators	CLI
predict_transition_driver_regulators	Identify driver regulators in cell-state transitions	CLI
predict_regulator_context_cofactors	Identify context-specific cofactors	CLI
predict_tf_binding_regions	Predict TF-binding regions	CLI, API

4. ChromBERT-Lite model option

In our tests, ChromBERT-Lite reduced runtime by at least half across representative ChromBERT-tools tasks compared with the original ChromBERT model.

ChromBERT-Lite generally shows slightly lower performance, with noticeable decreases in a small number of tasks. Therefore, ChromBERT-Lite is not intended to replace the original ChromBERT model, which remains the recommended default for accuracy-oriented analyses. Instead, it is provided as an optional lightweight alternative for rapid exploration, large-scale screening, or resource-limited computing environments.

To use ChromBERT-Lite, you can specify the --lite flag when running ChromBERT-tools commands.

download-data --genome hg38 --resolution 1kb --lite # Download ChromBERT-Lite resources.
chrombert-tools <command> --genome hg38 --resolution 1kb --lite # Run ChromBERT-tools commands with ChromBERT-Lite.

Contact us

If you have any questions or suggestions, please feel free to contact us at 2211083@tongji.edu.cn.