dlem-jax 0.1.0

Tool to build, train, and use the differentiable Loop Extrusion Model (dLEM)

Documentation

Documentation

dLEM

---

Downloads
Documentation
License
CI

---

Differentiable Loop Extrusion Model

This package provides functions to train, predict, and evaluate a Differentiable Loop Extrusion Model (DLEM) on HiC/Micro-C experiments. Take chromatin conformation data in (m)cool format and calculate L and R cohesin rate parameters.

Installation

Requires Python 3.11–3.13

pip install git+https://github.com/chikinalab/dLEM.git

Refer to the Installation section in the documentation for more information and how to contribute.

Quickstart

dLEM

dLEM: differentiable Loop Extrusion Model

Usage:

$ dlem [OPTIONS] DNA_INTS OUTPUT_LOCATION

Arguments:

• DNA_INTS: Chromatin input dataset in the form of a .(m)cool file [required]
• OUTPUT_LOCATION: Location of output directory, will be created if not existing [required]

Options:

• --device [gpu|cpu|tpu]: Select computation device: gpu, cpu, or tpu [default: cpu]
• -r, --region TEXT: Train on a specific chromosomal region (ex: chr16:51906425-55560999)
• -b, --bed TEXT: Plot and output tsv for all regions in BED file, 3 columns , ex:
• --chromosomes COMMA_LIST_PARSER: Comma-separated list of chromosomes to train on (e.g., 'chr1,chr2,chr3')
• --all: Run dLEM across all chromosomes in input cool file
• -l, --resolution INTEGER: Resolution to pull .cool file from .mcool file, must exist
• --start-diag INTEGER: Diagonal offset where updates start during training [default: 5]
• --train-rows INTEGER: Number of diagonals to use during training dLEM [default: 170]
• --steps INTEGER: Number of steps for training [default: 10]
• -w, --window-size INTEGER: Column window size for slowdown fitting [default: 3000]
• -s, --window-step INTEGER: Step between slowdown-fitting windows [default: 200]
• -d, --decay-extent INTEGER: Number of band rows to use when fitting slowdown [default: 500]
• -i, --iterations INTEGER: Number of iterations to fit the model over [default: 300]
• -lr, --lr FLOAT: Change speed of parameter tuning, useful if loss is too fast/slow or model not converging [default: 0.01]
• -pm, --prediction-mode [mse|corr|final]: Which parameter set to use for predictions [default: mse]
• -esm, --early-stop-metric [mse|corr|none]: Metric for early stopping [default: mse]
• --debug: Enable debug mode
• -pr, --prediction-rows INTEGER: Number of diagonals to predict with using dLEM model [default: 700]
• -c, --output-cool: Output the prediction as a .cool file
• -t, --output-tracks: Output the parameters as genomic tracks in BED and BigWig format
• --norm: Normalize the predicted band. When set geometric mean is used, otherwise no normalization
• -p, --plot: Plot fits to compare to input
• --install-completion: Install completion for the current shell.
• --show-completion: Show completion for the current shell, to copy it or customize the installation.
• --help: Show this message and exit.

Refer to the Quickstart (CLI) and CLI Reference sections in the documentation for more details.

Docker usage

docker run ghcr.io/dborgesr/dlem:latest

Contributing

git clone https://github.com/chikinalab/dLEM.git

Using local pixi

pixi install -e

Using Docker

docker-compose build

docker-compose up --watch

Citing

If you use dLEM or any of its language bindings in your research, please cite the following publication:

Tina Subic, Tŭgrul Balcı, Kristina Perevoshchikova, Geoffrey Fudenberg, Maria Chikina, Mechanistic Genome Folding at Scale through the Differentiable Loop Extrusion Model Biorxiv, https://www.biorxiv.org/content/10.1101/2025.10.17.682904v1

BibTex

@article{dlem,
    author = {Tina Subic, Tŭgrul Balcı, Kristina Perevoshchikova, Geoffrey Fudenberg, Maria Chikina},
    title = "{dlem: diffrentiable loop extrusion model for chromatin looping data}",
    journal = {Biorxiv},
    volume = {40},
    number = {7},
    pages = {btae408},
    year = {2024},
    month = {06},
    issn = {1367-4811},
    doi = {10.1101/2025.10.17.682904},
    url = {https://doi.org/10.1101/2025.10.17.682904},
    eprint = {https://www.biorxiv.org/content/10.1101/2025.10.17.682904v1.full.pdf},
}