TFClassPredict

Description

TFClassPredict predicts transcription factor binding sites (TFBSs) on the human genome according to their DNA-binding domain, encapsulated in 23 DBD-classes defined by the TFClass class-level hierarchy. By leveraging the DNABERT model, TFClassPredict achieves high predictive performance across all DBD-classes.

Installation

pysam and pyBigWig require system-level build tools. On Ubuntu/Debian, verify their installation before running pip install tfclass_predict:

sudo apt-get install build-essential libcurl4-openssl-dev libssl-dev \
    zlib1g-dev libbz2-dev liblzma-dev libncurses5-dev

The package can be installed via pip:

pip install tfclass_predict

Installation time: typically 1–3 minutes depending on your internet connection and system, as several large dependencies (tensorflow, pysam, pyBigWig) need to be compiled from source.

Required Data

To use TFClassPredict, at least one of the following data sources must be provided:

Option A – Precompiled hg38 Dataset (Recommended)

Using the precompiled dataset is strongly recommended as it drastically reduces runtime and works on virtually any system without requiring a GPU.

Download TFCP_precompiled

Option B – TFClassPredict Model + Reference Genome

For non-hg38 genomes, the full deep learning model can be run directly alongside the human reference genome (hg38) as an alternative approach.

Download HG38 from UCSC

Download TFCP_model

Note: All downloads must be unzipped before use. Pass the path to the TFCP_precompiled directory, or both the hg38.fa file and the TFCP_model directory, to the command-line tool or PredictionManager. The genome file should be indexed for faster processing, otherwise it will be created within the first run:

samtools faidx hg38.fa

Usage

Command-Line Interface

tfclass_predict [-h] [--genome GENOME] [--precompiled PRECOMPILED]
                [--model MODEL] [--detailed] [--no-normalize]
                [--gpus GPUS] [--cpus CPUS]
                bed_file output_dir

Positional Arguments

The bed file should contain chromosome names in the UCSC format (i.e. chr1). In case the precompiled model is used, alternative contigs need to be discarded beforehand.

Optional Arguments

If both --precompiled and --model are specified, the precompiled dataset takes precedence.

Examples

# Using the precompiled dataset (recommended)
tfclass_predict sample.bed results/ --precompiled path/to/TFCP_precompiled

# Using the model and reference genome
tfclass_predict sample.bed results/ --genome hg38.fa --model path/to/TFCP_model

# With multiple GPUs and CPUs
tfclass_predict sample.bed results/ --genome hg38.fa --model path/to/TFCP_model \
    --gpus 4 --cpus 8

# Save raw counts instead of normalized TFBPD scores
tfclass_predict sample.bed results/ --precompiled path/to/TFCP_precompiled --no-normalize

# Return per-window predictions
tfclass_predict sample.bed results/ --precompiled path/to/TFCP_precompiled --detailed

Python API

from tfclass_predict import PredictionManager

bed_file            = "path/to/experiment.bed"
genome_file         = "path/to/hg38.fa"
tfclass_model       = "path/to/TFCP_model"
tfclass_precompiled = "path/to/TFCP_precompiled"
res_dir             = "results/"

# ── Option A: precompiled dataset (recommended) ────────────────────────────
pm = PredictionManager(bed_file, res_dir, precompiled=tfclass_precompiled)
pm.predict()
pm.get_TFBPDs()           # compute normalized TFBPD scores
pm.save_results()         # saves <bed_file>_TFBPDs.csv

# save raw counts instead
pm.save_results(normalized=False)   # saves <bed_file>_DBDcounts.csv

# ── Option B: model + reference genome ────────────────────────────────────
pm = PredictionManager(
    bed_file,
    res_dir,
    genome_file = genome_file,
    tfcp_model  = tfclass_model,
    ngpus       = 1,
    ncpus       = 4,
)
pm.predict()
pm.get_TFBPDs()
pm.save_results()

# ── Detailed mode: per-window predictions ─────────────────────────────────
pm = PredictionManager(bed_file, res_dir, precompiled=tfclass_precompiled, detailed=True)
pm.predict()
pm.save_results(normalized=False)

Output Files

Both files include the original BED coordinates (chr, start, end) as the first three columns, followed by one column per DBD-class.

Tutorial and Further Documentation

Full API documentation including a tutorial is available at ReadTheDocs.

Performance Notes

• When using TFCP_model, predictions are automatically distributed across multiple GPUs via tf.distribute.MirroredStrategy if --gpus > 1.
• Setting --cpus > 1 enables parallel sequence tokenization and can significantly reduce preprocessing time for large BED files.
• The precompiled dataset does not require a GPU and is suitable for standard compute environments.

System Requirements

Precompiled Dataset - Minimum Requirements

Full Model - Minimum Requirements)

Software Dependencies