Mulish Donkey Algorithm

A computational framework for screening peptide–target interactions and estimating residence-related kinetic parameters.

Workflow

The repository contains two sequential stages:

Stage 1 — Donkey Algorithm

• Reads peptide docking results.
• Extracts sequence and structural interaction features.
• Estimates an activation-related term (ΔG‡).
• Calculates k_off, Residence Score, and Residence Time.
• Performs iterative bucking/survival analysis.

Stage 2 — Donkey QSAR

• Uses Stage 1 results as the training dataset.
• Trains length-stratified Random Forest regression models.
• Uses a global Random Forest model as a fallback/reference model.
• Predicts residence-related parameters for new peptide sequences.

Docking results + optional PDB structures
                  │
                  ▼
        donkey_algorithm.py
                  │
        ┌─────────┴─────────┐
        ▼                   ▼
 Feature extraction     Bucking analysis
        │                   │
        └─────────┬─────────┘
                  ▼
       donkey_full_results.csv
                  │
                  ▼
          donkey_qsar.py
                  │
                  ▼
      Random Forest QSAR
                  │
                  ▼
 Predicted Residence Score / k_off / Time

Installation

Python 3.10+ is recommended.

python -m venv .venv

Windows:

.venv\Scripts\activate

Install dependencies:

pip install -r requirements.txt

Stage 1: Donkey Algorithm

Run without PDB structures:

python src/donkey_algorithm.py --input path/to/peptide.csv

Run with peptide–ACE PDB structures:

python src/donkey_algorithm.py --input path/to/peptide.csv --pdb-dir path/to/pdb

Specify an output file:

python src/donkey_algorithm.py --input path/to/peptide.csv --pdb-dir path/to/pdb --output results/donkey_full_results.csv

PDB files are expected to follow:

<PEPTIDE>-ACE.pdb

If a matching PDB file is unavailable, the current implementation uses a sequence-based polar-residue proxy for the hydrogen-bond feature.

Stage 2: Donkey QSAR

Stage 2 requires the CSV produced by Stage 1 and an Excel file containing new peptide sequences.

python src/donkey_qsar.py --donkey-results results/donkey_full_results.csv --new-peptides examples/new_peptides.xlsx

Optional outputs:

python src/donkey_qsar.py   --donkey-results results/donkey_full_results.csv   --new-peptides examples/new_peptides.xlsx   --output-csv results/predicted_peptides.csv   --output-excel results/predicted_peptides.xlsx   --correlations results/statistical_correlations.xlsx

Input and output

Stage 1 produces donkey_full_results.csv, containing peptide descriptors, docking score, hydrogen-bond-related feature, activation-related term, k_off, Residence Score, Residence Time, and bucking survival step.

Stage 2 produces predicted Residence Score, k_off, and Residence Time values for new peptides, together with length-bin summaries and correlation analysis.

Scientific interpretation

The residence-related quantities produced by this implementation are computational estimates. They should not be presented as experimentally measured residence times or experimentally validated kinetic constants unless independent validation supports that interpretation.

The exact mathematical definitions, parameter values, and scientific interpretation should be reported together with the associated publication.

Reproducibility

For a reproducible analysis, report:

• repository version or release/tag;
• Python version;
• package versions;
• input dataset version;
• exact command used;
• model parameters and algorithm parameters.

Citation

Citation information for the associated manuscript will be added here after publication.

License

MIT License. See LICENSE.