README.md

---
license: gpl-3.0
language:
- en
- zh
tags:
- OneScience
- life-science
- enzyme
- enzyme-kinetics
- UniKP
frameworks: PyTorch
---

<p align="center">
  <strong><span style="font-size: 30px;">UniKP</span></strong>
</p>

# Model Introduction

UniKP is a unified framework for predicting enzyme kinetic parameters based on pretrained language models. Given a protein sequence and substrate structure, it can predict the enzyme turnover number $k_{cat}$, Michaelis constant $K_m$, and catalytic efficiency $k_{cat}/K_m$. UniKP uses a protein language model to extract enzyme sequence representations and combines them with substrate representations generated by a molecular language model to predict kinetic parameters.

Paper:

> **UniKP: a unified framework for the prediction of enzyme kinetic parameters**  
> https://doi.org/10.1038/s41467-023-44113-1

# Model Description

UniKP takes the enzyme protein sequence and substrate SMILES as two separate inputs. On the protein side, ProtT5-XL-UniRef50 is used to extract sequence representations, while on the substrate side, a SMILES Transformer is used to generate molecular representations. The two feature representations are concatenated and then fed into trained regression models to predict $k_{cat}$, $K_m$, and $k_{cat}/K_m$, respectively.

# Use Cases

| Scenario | Description |
| --- | --- |
| Enzyme turnover number prediction | Predict $k_{cat}$ from a protein sequence and substrate SMILES |
| Michaelis constant prediction | Predict $K_m$ for an enzyme-substrate system |
| Catalytic efficiency prediction | Predict $k_{cat}/K_m$ |
| Enzyme discovery and screening | Predict and rank kinetic parameters for candidate enzyme sequences |
| Enzyme directed evolution | Compare predicted kinetic parameters of wild-type and mutant candidates |
| Environmental factor analysis | Use EF-UniKP-related implementations to investigate the effects of temperature and pH on $k_{cat}$ |

# Usage

## 1. Using OneCode

You can use the OneCode online environment for intelligent one-click AI4S programming:

[Try intelligent one-click AI4S programming](https://web-2069360198568017922-iaaj.ksai.scnet.cn:58043/home)

## 2. Manual Installation and Usage

**Hardware Requirements**

- ProtT5-XL-UniRef50 is relatively large, so GPU/DCU acceleration is recommended for protein representation extraction.
- A CPU can be used for a small number of short sequences, but it will be significantly slower than an accelerator.
- For batch prediction or long-sequence tasks, it is recommended to reduce the batch size and adjust it according to the available device memory.

### Environment Setup

#### DCU Environment

```bash
# Activate DTK and CONDA first
conda create -n onescience311 python=3.11 -y
conda activate onescience311

pip install onescience[bio] \
  -i http://mirrors.onescience.ai:3141/pypi/simple/ \
  --trusted-host mirrors.onescience.ai
```

#### Environment Notes
- If you encounter missing dependencies or version incompatibilities during execution, refer to the dependency versions specified in `requirements.txt` and install or adjust the corresponding packages as needed.

### Model Weights

Complete UniKP inference requires three types of model resources:

1. ProtT5-XL-UniRef50;
2. UniKP regression models for $k_{cat}$, $K_m$, and $k_{cat}/K_m$;
3. The vocabulary and pretrained weights of the SMILES Transformer.

#### 1) ProtT5-XL-UniRef50

ProtT5-XL-UniRef50 needs to be downloaded separately:

```text
https://zenodo.org/records/4644188
```

It is recommended to place it as follows:

```text
UniKP/
└── weight/
    └── prot_t5_xl_uniref50/
```

The current code will first try to use:

```python
T5Tokenizer.from_pretrained("weight/prot_t5_xl_uniref50")
T5EncoderModel.from_pretrained("weight/prot_t5_xl_uniref50")
```

If `weight/prot_t5_xl_uniref50` does not exist, the code will fall back to `"prot_t5_xl_uniref50"`. You can also adjust `scripts/project_paths.py` according to the actual local path.

#### 2) UniKP Regression Models

The official README provides download links for the models corresponding to the three tasks:

```text
https://huggingface.co/HanselYu/UniKP/tree/main
```

Typical files include:

```text
UniKP for kcat.pkl
UniKP for Km.pkl
UniKP for kcat_Km.pkl
```

- These files are included in `weight/UniKP_model`.

## 3. Quick Start

### Download the Model Package

```bash
hf download OneScience-Group/UniKP --local-dir ./UniKP
cd UniKP-main
```

- UniKP additionally depends on **ProtT5-XL-UniRef50** and the three types of **UniKP regression model weights**. Please prepare the required models according to the "Model Weights" section before proceeding.
- The SMILES Transformer-related code is located in `model/`. Before running, make sure that `weight/vocab.pkl` and `weight/trfm_12_23000.pkl` exist.

### Quick Verification

Check whether ProtT5 can be loaded locally:

```bash
python - <<'PY'
from transformers import T5Tokenizer, T5EncoderModel
path = "./weight/prot_t5_xl_uniref50"
T5Tokenizer.from_pretrained(path, do_lower_case=False)
T5EncoderModel.from_pretrained(path)
print("ProtT5 load OK")
PY
```

Check the regression model and SMILES Transformer resources:

```bash
ls -lh weight/UniKP_model/
ls -lh weight/vocab.pkl weight/trfm_12_23000.pkl
```
If all of the above checks pass, you can continue with the single-sample inference script:

```bash
python scripts/demo_kcat.py
```

# Example Data

The core inputs for UniKP inference are:

```text
Protein amino acid sequence
+
Substrate SMILES
```

Example:

| Input | Example |
| --- | --- |
| Protein sequence | `MSELMKLSAV...MAQR` |
| Substrate SMILES | `CC(O)O` |

The corresponding output can be:

```text
kcat
Km
kcat / Km
```

# Inference Examples

## Single-Sample kcat Prediction

Run the following command from the UniKP root directory:

```bash
python scripts/demo_kcat.py
```

This script reads an example protein sequence and substrate SMILES, extracts their representations using ProtT5-XL-UniRef50 and the SMILES Transformer, respectively, concatenates the representations, and then loads `weight/UniKP_model/UniKP for kcat.pkl` to perform kcat prediction.

The prediction result is printed to the terminal and saved as:

```text
UniKP_kcat_prediction.xlsx
```

By default, `demo_kcat.py` loads the kcat regression model:

```python
with open("weight/UniKP_model/UniKP for kcat.pkl", "rb") as f:
    model = pickle.load(f)
```

To predict **Km**, replace the model path above with:

```python
with open("weight/UniKP_model/UniKP for Km.pkl", "rb") as f:
    model = pickle.load(f)
```

To predict **kcat/Km**, replace it with:

```python
with open("weight/UniKP_model/UniKP for kcat_Km.pkl", "rb") as f:
    model = pickle.load(f)
```

Except for the regression model, the protein representation extraction, SMILES representation extraction, feature concatenation, and prediction workflow remain unchanged. The model outputs are in `log10` space, and the script converts them back to the actual kinetic parameter values using `10 ** x`.

## Batch Prediction

The repository provides separate batch prediction scripts for kcat, Km, and kcat/Km:

```bash
python scripts/UniKP_kcat.py
python scripts/UniKP_Km.py
python scripts/UniKP_kcat_Km.py
```

The three scripts read the corresponding task data files and load the matching UniKP regression models to perform batch prediction on multiple protein sequences and substrate entries.

Before running, make sure that the data files for the corresponding task are located in `conf/datasets/`.


# Output Description

UniKP outputs the predicted values of the corresponding enzyme kinetic parameters.

| Parameter | Unit Used in the Official Example |
| --- | --- |
| $k_{cat}$ | s⁻¹ |
| $K_m$ | mM |
| $k_{cat}/K_m$ | s⁻¹·mM⁻¹ |

The internal predictions of the UniKP regression models are in `log10` space, so the output of `model.predict()` cannot be treated directly as the actual kinetic parameter values. Use:

```python
pred = model.predict(fused_vector)
pred_real = [10 ** x for x in pred]
```

The official example saves the results as:

```text
Kinetic_parameters_predicted_label.xlsx
```

# OneScience Official Information

| Platform | OneScience Main Repository | Skills Repository |
| --- | --- | --- |
| Gitee | https://gitee.com/onescience-ai/onescience | https://gitee.com/onescience-ai/oneskills |
| GitHub | https://github.com/onescience-ai/OneScience | https://github.com/onescience-ai/oneskills |


# Citation and License

- Original UniKP paper: [UniKP: a unified framework for the prediction of enzyme kinetic parameters](https://doi.org/10.1038/s41467-023-44113-1).
- UniKP is licensed under the GNU General Public License version 3 (GPL-3.0).
- UniKP inference depends on third-party models and code such as ProtT5-XL-UniRef50 and the SMILES Transformer. Their respective licenses and terms of use must also be followed when using, modifying, or redistributing these resources.
- For research use, it is recommended to cite the original UniKP paper. If ProtT5 or the SMILES Transformer is used to generate representations, the corresponding projects should also be cited as required.