Metadata-Version: 2.4
Name: dsites
Version: 1.3.0
Summary: D-Sites: Hybrid TFBS predictor (PWM + DNA shape + RF)
Home-page: https://github.com/pankaj357/D-Sites
Author: Pankaj, Kanaka KK
Author-email: ft.pank@gmail.com
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.79
Requires-Dist: pandas>=1.3
Requires-Dist: numpy>=1.21
Requires-Dist: scikit-learn>=1.0
Requires-Dist: joblib>=1.1
Requires-Dist: matplotlib>=3.3
Requires-Dist: tqdm>=4.62
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# D-Sites: Hybrid TFBS Predictor for Bacterial Genomes

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A comprehensive computational tool for predicting transcription factor binding sites (TFBS) in bacterial genomes using hybrid PWM, DNA shape features, and Random Forest classification.

## 🚀 Quick Start

### Installation
```bash
git clone https://github.com/pankaj357/D-Sites.git
cd D-Sites
pip install .
```
This installs the `dsites` command-line tool and all required dependencies
(see `requirements.txt` for the exact pinned versions used for the published
benchmarks).

### Basic Prediction
#### Minimal Command
```bash
dsites --fasta <genome.fasta> \
       --gff <annotation.gff> \
       --motif <motif_file> \
       --gene <TF_name> \
       --genome_accession <accession_id>
```
#### Complete Example
```bash
dsites \
    --fasta <path_to_genome.fasta> \
    --gff <path_to_annotation.gff> \
    --motif <path_to_motif_file> \
    --gene <TF_NAME> \
    --genome_accession <GENOME_ACCESSION> \
    --output results \
    --n_trees 300 \
    --neg_ratio 5 \
    --prob_cutoff 0.5 \
    --pseudocount 0.5 \
    --pad 10 \
    --seed 42 \
    --batch 10000 \
    --up 300 \
    --down 50 \
    --auto_cutoff
```
If the TF/genome pair is not present in the bundled CollecTF export, provide
known binding sequences explicitly (plain text, one sequence per line):
```bash
dsites --fasta genome.fna --gff genomic.gff --motif motif.txt \
       --gene FNR --genome_accession NC_003197.2 \
       --known known_binding_sites.txt --output results
```

### Command Breakdown
#### Required Arguments
```bash
--fasta: Genome FASTA file path

--gff: Genome annotation file (GFF3 format, required for promoter-based
       scanning; optional with --full_genome)

--motif: TF motif file (JASPAR or MEME format)

--gene: Transcription factor name

--genome_accession: Genome accession ID, used to look up known sites in the
       bundled CollecTF dataset (scanning always covers ALL contigs in the FASTA)
```
#### Optional Arguments with Defaults
``` bash
--output results: Output directory (alias: --outdir)

--n_trees 300: Number of Random Forest trees

--neg_ratio 5: Negative:Positive ratio (honored exactly)

--min_negatives 0: Optional minimum number of negative examples

--pseudocount 0.5: Count-based PWM pseudocount, p = (count + pc) / (N + 4*pc)

--prob_cutoff 0.5: Probability cutoff

--pad 10: Window padding around known sites

--seed 42: Random seed (runs are fully deterministic for a fixed seed)

--batch 10000: Batch size for parallel scanning

--up 300: Upstream promoter size

--down 50: Downstream promoter size

--full_genome: Slide windows across entire contigs instead of promoter windows

--auto_cutoff: Automatically select probability cutoff via precision-recall curve
```

## 📈 Performance
Held-out evaluation (grouped 5-fold site-level cross-validation; thresholds selected from out-of-bag
predictions; FIMO compared on identical promoter windows at matched prediction counts — full workflow
in `evaluation/`):
- Recall of known promoter-localized sites: 75% (AmrZ), 76% (GlxR), 96% (CodY)
- Ranking quality comparable to FIMO overall; higher precision and recall than FIMO for CodY
  (0.154 vs 0.118 precision at N = 500)
- DNA-shape features improve ranking for every factor tested (ablation); largest gain for CodY
  (~2× PR-AUC vs PWM-only)
- A model trained on 97 E. coli FNR sites (RegulonDB 13.5) transfers to Salmonella Typhimurium LT2
  (cross-genome application)

## 📝 Citation
If you use D-Sites in your research, please cite:

Pankaj et al. *D-Sites: A hybrid machine-learning framework for prediction of transcription factor binding sites in bacterial genomes*. Evolutionary Bioinformatics (under review).

## 📄 License
MIT License - see LICENSE for details.

## 💬 Contact
For questions and support, contact:
- Pankaj: ft.pank@gmail.com
- Kanaka KK: kkokay07@gmail.com
