DeepDETAILS: Deep-learning-based DEconvolution of Tissue profiles with Accurate Interpretation of Locus-specific Signals

Installation

Recommended: install with conda/mamba so binary dependencies (bedtools, bedGraphToBigWig) are installed automatically:

conda install -c bioconda -c conda-forge "pytorch=2.6.0=cuda*" deepdetails

Alternatively, install with pip (you must provide the binaries yourself):

pip install DeepDETAILS

If you install via pip, make sure bedGraphToBigWig and bedtools are on your PATH. DeepDETAILS uses these tools when exporting deconvolved results to bigWig files.

Get started

Step 1: Prepare datasets for deconvolution

DeepDETAILS requires the following input files:

• Strand-specific signals for the bulk library (bigWig format)
• Region of interests (e.g. peaks) in the bulk library (bed format)
• Aligned fragments from the reference sc/snATAC-seq (bed-like tabular format, required columns: chrom, chromStart, chromEnd, barcode, and readSupport). Example
• Cell type annotation for each cell barcode (tabular format, required columns: barcode and cell type annotation).
• Reference genome sequence (fasta format).
• Chromosome size.

deepdetails prep-data \
    --bulk-pl bulk.pl.bw \
    --bulk-mn bulk.mn.bw \
    --regions bulk.peaks.bed \
    --fragments fragments.tsv.gz \
    --barcodes barcodes.tsv \
    --accessible-regions atac_peaks.bed \
    --save-to ./dataset \
    --genome-fa GRCh38_no_alt_analysis_set_GCA_000001405.15.fasta \
    --chrom-size chrNameLength.txt

Step 2: Deconvolution

After building the dataset folder, you can run the deconvolution process (requires GPU):

deepdetails deconv \
    --dataset ./dataset \
    --save-to . \
    --study-name sample-a

The outputs from a successful deconvolution process look like the following:

.
├── sample-a
│   └── 250212144109: The folder containing deconvolution results (name changes according to the time).
│       ├── epoch=0-step=2538.ckpt: Trained model
│       ├── hparams.yaml: Hyperparameters
│       ├── metrics.csv: Training log
...
│       └── preview972.0.131072.0000.s21250212144109.png: Preview genome browser views
├── sample-a.counts.csv.gz: Deconvolved read counts (1-kb resolution) for each cell type
└── sample-a.predictions.h5: Deconvolved signal (1-bp resolution) for each cell type

Step 3: Visualize the results (optional)

This step exports deconvolved signal tracks (bigWig) to visualize the signals in each cell type, and it's optional. You need to locate the exported predictions from the previous step by looking for files like sample-name.predictions.h5. After you get the file, you can run the following command:

deepdetails build-bw \
    -p sample-name.predictions.h5 \
    --save-to . \
    --chrom-size chrNameLength.txt

You should be able to see deconvolved signal tracks for each cell type (named like cell_type.pl.bw / cell_type.mn.bw) in the output directory after the command finishes.

Step 4: Visualize sequence attributions (optional)

This step exports sequence attribution tracks from trained DeepDETAILS models (using Input X Gradient):

deepdetails attr \
  -m sample-a/250212144109/epoch=0-step=2538.ckpt \
  --dataset ./dataset \
  --chrom-size chrNameLength.txt

Reference

If you find DeepDETAILS helpful, please cite:

Yao, L. et al. High-resolution reconstruction of cell-type-specific transcriptional regulatory processes from bulk sequencing samples. Nat Biotechnol 1–12 (2026) doi:10.1038/s41587-026-03218-w.