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

---

Installation

DeepDETAILS can be installed via conda:

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

DeepDETAILS can also be installed via pip:

pip install DeepDETAILS

If you prefer to install DeepDETAILS using pip, please make sure you have bedGraphToBigWig and bedtools installed. DeepDETAILS use these tools to export the 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: Hyperparamters
│       ├── 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

Yao, L. et al. High-resolution reconstruction of cell-type specific transcriptional regulatory processes from bulk sequencing samples. Preprint at bioRxiv (2025).