DNA-Diffusion: Training a Diffusion Model on 200bp Regulatory Elements
🧬 Generative modeling of regulatory DNA sequences with diffusion probabilistic models 💨
At a glance
- What is it?
- DNA-Diffusion generates 200bp cell type-specific synthetic regulatory elements with a diffusion probabilistic model. The repository is a training and sampling pipeline built around uv, Hydra configs, and a HuggingFace checkpoint, and its practical constraints are as important as its outputs.
- Who is it for?
- Adopt DNA-Diffusion if you already work with chromatin accessibility data and want a runnable diffusion baseline for 200bp regulatory element generation, especially if you can start from the HuggingFace checkpoint rather than training from scratch. Do not adopt it if you need a tool that works on arbitrary sequence lengths, non-human cell types, or a documented API surface beyond the training and sampling scripts.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap DNA-Diffusion fills: generating regulatory elements, not scoring them
Most sequence models in regulatory genomics are discriminative. They take a sequence and predict an assay signal, a chromatin state, or a transcription factor binding probability. DNA-Diffusion inverts that. According to the README, it is a diffusion-based model for generation of 200bp cell type-specific synthetic regulatory elements. The output is a sequence, not a score. That distinction matters for anyone doing design work: enhancer design, synthetic promoter libraries, or in silico saturation mutagenesis where you need plausible starting material rather than a classifier's opinion of existing material. The target user is a computational biologist or ML engineer who is comfortable with PyTorch training loops and Hydra-style config overrides, and who has access to a GPU. The README states the preferred operating system is Linux with a recent GPU, giving an A100 as the example. The project is not aimed at bench scientists who want a web interface, and nothing in the repository suggests one exists.
How the diffusion mechanism maps onto a four-letter alphabet
The repository describes the model as a diffusion probabilistic model, and the training and sampling scripts are the clearest evidence of the architecture. Training runs for a minimum of 2000 epochs per the default config, and the training script saves checkpoints for the lowest 2 validation loss values into the checkpoints/ directory. Sampling then runs the reverse process, with a guidance scale parameter that the README says is tunable within sample.py and defaults to 1.0. Guidance scale is the main knob that separates unconditional-like generation from cell type-conditioned generation, which is consistent with the claim of cell type-specific output. Cell type conditioning is exposed as a sampling parameter, so the model is conditioned rather than purely unconditional. The README does not document the noise schedule, the number of diffusion steps, the denoiser architecture, or how discrete nucleotide tokens are handled during the forward and reverse processes. Those details live in the code and the linked documentation site, not in the README, and I cannot confirm them from the supplied material.
Getting from clone to a generated sequence
The README gives a concrete path. Install uv first, then clone and sync:
git clone https://github.com/pinellolab/DNA-Diffusion.git cd DNA-Diffusion uv sync
That creates a .venv and installs from uv.lock. To sample from the published weights rather than train your own, run uv run sample_hf.py. The default generates 1000 sequences per cell type. For a quick check, the README's own example is uv run sample_hf.py sampling.number_of_samples=1 sampling.sample_batch_size=1. To restrict output to one cell type: uv run sample_hf.py data.cell_types=K562 sampling.number_of_samples=1 sampling.sample_batch_size=1. Multiple cell types go in as a comma separated string or a list, for example 'data.cell_types="K562,GM12878"'. Guidance scale is overridden the same way: uv run sample_hf.py sampling.guidance_scale=7.0. Training is uv run train.py against configs/train/default.yaml, with a debug config available as uv run train.py -cn train_debug that uses a single sequence. If you train your own model, you must edit checkpoint_path in configs/sampling/default.yaml, which defaults to checkpoints/model.safetensors. Both pt and safetensors formats are supported.
The data pipeline is the part that will surprise you
The repository ships a small subset of the DHS Index dataset at data/K562_hESCT0_HepG2_GM12878_12k_sequences_per_group.txt, which is enough to reproduce the documented training run. Recreating the full dataset is a separate step: uv run data/master_dataset_and_filter.py downloads the source data and writes data/master_dataset.ftr with roughly 3.59 million sequences plus data/filtered_dataset.txt containing the same subset as the shipped file. That number is the one to plan around. The default training config runs a minimum of 2000 epochs, and the README does not state wall-clock time, GPU memory, or batch size for that run. Anyone budgeting a from-scratch training job has to derive those from the config files and the actual data, because the README does not provide them. The debug config exists precisely because iterating on the full pipeline is slow, which is a reasonable signal about the cost.
What the project does not tell you, and where it will not fit
Three limitations are visible in the material. First, output length is fixed at 200bp. There is no documented option for variable-length generation, so anything requiring full promoters, multi-kilobase enhancer clusters, or scaffold sequences is out of scope. Second, the cell type conditioning is tied to the cell types present in the training data. The README names K562, GM12878, HepG2 and hESCT0 in the shipped subset filename, and sampling is restricted to cell types in the dataset. Generating for a cell type absent from training is not a documented capability. Third, the license is NOASSERTION. GitHub could not map the repository's license file to a recognized SPDX identifier, so the terms of reuse for the code and the weights are not something this review can state. Anyone planning to ship generated sequences in a commercial pipeline needs to read the actual LICENSE file and the HuggingFace model card rather than assume permissive terms. Separately, the README does not describe any evaluation of generated sequences against held-out real sequences, so the quality bar is something you have to set yourself.
Where DNA-Diffusion sits next to Enformer-style models
The natural comparison is a sequence-to-function model such as Enformer or a similar supervised predictor. Those models are trained to map a DNA sequence to expression or assay tracks, and they are used to score candidate sequences you already have. DNA-Diffusion does the opposite: it produces candidate sequences and leaves scoring to whatever model you pair it with. The difference in workflow is substantial. With a predictor, you generate candidates by mutation or by search and rank them. With DNA-Diffusion, you sample from a learned distribution over regulatory elements and then filter. The two are complementary rather than competing, and the README does not claim DNA-Diffusion replaces a predictor. A second comparison point is a generative model trained on k-mer statistics or a language model over DNA. Those approaches typically generate sequences without an explicit diffusion process, and they do not offer a guidance scale as a conditioning knob. The guidance scale parameter in sample.py is the clearest practical difference: it gives a continuous dial between diversity and cell type adherence, which is not something a k-mer sampler exposes.
Maintenance, versions and what the release history suggests
The repository is not archived, and the last push is dated 2026-09-02. Releases run v0.1.0 (2025-06-29), v0.1.1 (2025-07-01), and v0.0.3 (2025-05-05) before them. The package is published to PyPI as dnadiffusion. Version numbering is still in the 0.x range, which is worth reading as a statement about API stability: config keys such as sampling.guidance_scale and sampling.cell_type are the interface, and a 0.x project can rename them. The dependency surface is pinned through uv.lock, so an upgrade means re-resolving that lock file and re-testing the training and sampling scripts. The repository enforces a build workflow and reports code coverage, which suggests the maintainers run CI, but neither of those says anything about model quality. On licensing, the NOASSERTION label means the terms of use are not automatically determined by tooling. That is a fact about the repository metadata, not legal advice. If you need to redistribute the weights or the generated sequences, read the LICENSE file and the HuggingFace model page directly.
Editorial conclusion
Adopt DNA-Diffusion if you already work with chromatin accessibility data and want a runnable diffusion baseline for 200bp regulatory element generation, especially if you can start from the HuggingFace checkpoint rather than training from scratch. Do not adopt it if you need a tool that works on arbitrary sequence lengths, non-human cell types, or a documented API surface beyond the training and sampling scripts. Before committing, verify the checkpoint path in configs/sampling/default.yaml matches wherever you store the weights, and check what the NOASSERTION license actually permits for your use.
Community notes