# KdPred

[![This project supports Python 3.12+](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://python.org/downloads)
[![GPLv3 License](https://img.shields.io/badge/License-GPL%20v3-yellow.svg)](https://opensource.org/licenses/)

## Overview

KdPred is an automated pipeline for deep mutational scanning and predicting protein-protein binding affinities (K_d) using structure prediction (ColabFold) and binding affinity prediction (Prodigy).

## Features

- **Efficient mutation sequence generation**: Create mutated protein sequences from mutation specifications
- **Structure prediction**: Automated structure prediction using ColabFold
- **Kd prediction**: Binding affinity prediction using Prodigy
- **Flexible mutation format**: Supports single mutations, multiple mutations, and saturation mutagenesis
- **Modular design**: Each step can be run independently or as part of a complete pipeline

## Installation

### Prerequisites

- Python 3.12 or higher
- [ColabFold](https://github.com/sokrypton/ColabFold) installed and available in PATH
- [Prodigy](https://github.com/haddocking/prodigy) installed.

**Note about PATH and shells:** If `colabfold_batch` is available in your interactive shell (for example after `conda activate`) but Python reports it as not found when running the pipeline, the issue is usually that PATH modifications live in shell init files and are not present in the Python process environment. Solutions:

- Provide the full executable path to ColabFold, for example `--colabfold-cmd /home/you/colabfold/bin/colabfold_batch` or `ColabFoldPredictor(colabfold_command='/full/path/colabfold_batch')`.
- Launch the script/notebook from the same shell where you activated the environment (e.g., run Python after `conda activate kd_py312`).
- Export the ColabFold bin directory into the environment that will run Python, for example:

```bash
export PATH="/Your_ColabFold_Location/colabfold-conda/bin:$PATH"
```

### Install KdPred

```bash
# activate your virtual environment
conda activate kd_py312
# Install from source after downloading/cloning the repository
pip install -e .

# Or install dependencies only
pip install kdpred
```

## Usage

### Basic Usage

Run the complete deep mutational scanning pipeline:

```bash
# suppose your virtual environment is named kd_py312
conda activate kd_py312
# navigate to the directory containing protein.txt and mutations.txt

kdtool \
    --protein-seq-fpath protein.txt \
    --mutation-config-fpath mutations.txt \
    --output-dir /full_path/results/ \
    --protein-name DEMO_PROTEIN \
    --colabfold-cmd colabfold_batch \
    --job-type gp_multiple
```
where the job type can be one of: `prodigy`, `gp_single`, or `gp_multiple`. The `prodigy` option uses only Prodigy for Kd prediction on provided structures, while `gp_single` and `gp_multiple` use ColabFold for structure prediction followed by Gaussian Process regression models for Kd predictions with prodigy features.

To get to know all available options, run:

```bash
kdtool --help
```

### Input Files

#### Protein Sequences (`--protein-seq-fpath`)

A text file with one protein sequence per line, one per chain:

```
MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEEFGLAPFLPDQIHFVHSMLLSSQESVQGDWLDSLLAQ
MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGAEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEEFGLAPFLPDQIHFVHSMLLSSQESVQGDWLDSLLAQ
```

#### Mutations (`--mutation-config-fpath`)

A text file with one mutation per line. Supports multiple formats:

**Single mutation:**
```
B.H.68.F
```

**Multiple mutations (comma-separated):**
```
B.H.68.F,A.K.42.R
```

**Saturation mutation (3 parts, will be expanded):**
```
B.H.68
```

**Comments (lines starting with # are ignored):**
```
# Single point mutation
B.H.68.F
# Saturation mutagenesis at position 68
B.H.68
```

### Mutation Format

Mutations follow the format: `Chain.Wildtype.Position.Mutant`

- **Chain**: Single uppercase letter (A, B, C, etc.)
- **Wildtype**: Single letter amino acid code
- **Position**: 1-based position in the sequence
- **Mutant**: Single letter amino acid code

Example: `B.H.68.F` means on chain B, replace Histidine (H) at position 68 with Phenylalanine (F).

### Advanced Usage

#### Custom residue list for saturation

```bash
kdtool scan \
    --protein-seq-fpath /full/path/protein.txt \
    --mutation-config-fpath /full/path/mutations.txt \
    --output-dir /full/path/results/ \
    --residue-list "A,C,D,E,F"
```
where "A, C, D, E, F" are the amino acids to use for saturation mutagenesis.

#### Custom ColabFold/Prodigy settings

```bash
kdtool scan \
    --protein-seq-fpath /full/path/protein.txt \
    --mutation-config-fpath /full/path/mutations.txt \
    --output-dir /full/path/results/ \
    --colabfold-cmd /full/path/colabfold_batch \
    --job-type gp_multiple \
    --num-recycles 3 \
    --num-models 5
```

## Programmatic Usage

You can also use KdPred as a Python library. The recommended entry point for the full pipeline is `deep_mutational_scanning_pipeline` in `kdpred.cli`:

```python
from pathlib import Path

from kdpred.cli import deep_mutational_scanning_pipeline as dms

df_results = dms(
    protein_seq_fpath=Path("protein.txt"),
    mutation_config_fpath=Path("mutations.txt"),
    output_dir=Path("/full/path/results"),
    protein_name="MyProtein",
    colabfold_cmd="colabfold_batch",  # or full path to colabfold_batch
    job_type="gp_multiple",           # "prodigy", "gp_single", or "gp_multiple"
)

print(df_results.head())
```

## Module Structure

- `kdpred.mutations`: Efficient mutation sequence generation
- `kdpred.structure`: ColabFold structure prediction
- `kdpred.kd_prediction`: Prodigy Kd prediction
- `kdpred.utils`: Utility functions for validation and file I/O
- `kdpred.cli`: Command-line interface


## Citation

If you use KdPred in your research, please cite:

```
@article{your2025kdpred,
  title={Paper Title Here},
  author={Name and Collaborators},
  journal={Journal Name},
  year={2026},
  publisher={Publisher}
}
```
