Metadata-Version: 2.4
Name: tfclass_predict
Version: 1.1.7
Summary: tfclass_predict allows to estimate transcription factor bindingsites in the TFClass hierarchy.
Author-email: Christian Ickes <christian.ickes@med.uni-goettingen.de>, Hazal Timucin <hazal.timucin@bioinf.med.uni-goettingen.de>
Project-URL: Homepage, https://gitlab.gwdg.de/MedBioinf/generegulation/tfclasspredict
Project-URL: Issues, https://gitlab.gwdg.de/MedBioinf/generegulation/tfclasspredict/-/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: Unix
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: transformers==4.46.3
Requires-Dist: tensorflow>=2.13.0
Requires-Dist: pysam
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyBigWig
Requires-Dist: tf-keras
Requires-Dist: tqdm
Requires-Dist: scikit-learn
Provides-Extra: dev
Requires-Dist: pytest>=8.2.2; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# TFClassPredict

![Python Version](https://img.shields.io/pypi/pyversions/tfclass_predict) ![TensorFlow](https://img.shields.io/badge/tensorflow-2.13.0-orange) ![License](https://img.shields.io/badge/license-MIT-green) [![PyPI](https://img.shields.io/pypi/v/tfclass_predict)](https://pypi.org/project/tfclass_predict/) [![Docs](https://img.shields.io/badge/docs-readthedocs-blue)](https://tfclasspredict.readthedocs.io/en/latest/)

## 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`:

``` bash
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:

``` bash
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](https://zenodo.org/records/21278467/files/TFCP_precompiled.zip?download=1)

------------------------------------------------------------------------

#### 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](http://hgdownload.soe.ucsc.edu/goldenPath/hg38/bigZips/hg38.fa.gz) from UCSC

[Download TFCP_model](https://zenodo.org/records/21278467/files/TFCP_model.zip?download=1)

------------------------------------------------------------------------

**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:

``` bash
samtools faidx hg38.fa
```

------------------------------------------------------------------------

## Usage

### Command-Line Interface

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

#### Positional Arguments

| Argument     | Description                                          |
|--------------|------------------------------------------------------|
| `bed_file`   | Path to BED file of ATAC-seq or other NGS experiment |
| `output_dir` | Path to output directory                             |

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

| Argument | Description |
|--------------------------------|----------------------------------------|
| `--genome GENOME` | Path to human genome reference (recommended: hg38) `.fa` |
| `--precompiled PRECOMPILED` | Path to precompiled hg38 predictions (unzipped folder) |
| `--model MODEL` | Path to TFClassPredict model archive (unzipped folder) |
| `--detailed` | Return per-window predictions instead of per-peak/region predictions |
| `--no-normalize` | Save raw DBD-class binding site counts instead of standardized TFBPD scores |
| `--gpus GPUS` | Number of GPUs to use in parallel (default: 1) |
| `--cpus CPUS` | Maximum number of CPUs to use in parallel (default: 1) |

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

#### Examples

``` bash
# 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

``` python
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

| File | Description |
|--------------------------|----------------------------------------------|
| `<name>_TFBPDs.csv` | Standardized TFBPD scores per region and DBD-class (default) |
| `<name>_DBDcounts.csv` | Raw DBD-class binding site counts per region |

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](https://tfclasspredict.readthedocs.io/en/latest/).

------------------------------------------------------------------------

## 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

| Component  | Requirement                   |
|------------|-------------------------------|
| **OS**     | Linux                         |
| **Python** | 3.9 – 3.11                    |
| **CPU**    | 4+ cores                      |
| **RAM**    | 8 GB                          |
| **Disk**   | \~20 GB (precompiled dataset) |
| **GPU**    | Not required                  |

### Full Model - Minimum Requirements)

| Component  | Requirement              |
|------------|--------------------------|
| **OS**     | Linux                    |
| **Python** | 3.9 – 3.11               |
| **CPU**    | 8+ cores                 |
| **RAM**    | 32+ GB                   |
| **Disk**   | \~15 GB (model + genome) |
| **GPU**    | Recommended              |

### Software Dependencies

| Package        | Version    |
|----------------|------------|
| `tensorflow`   | `>=2.13.0` |
| `transformers` | `4.46.3`   |
| `numpy`        |            |
| `pandas`       |            |
| `pysam`        |            |
| `pyBigWig`     |            |
| `scikit-learn` |            |
