Metadata-Version: 2.4
Name: ecrecer
Version: 1.0.5
Summary: ECRECer enzyme commission number prediction and recommendation toolkit.
Author: Zhenkun Shi
License-Expression: MIT
Project-URL: Homepage, https://github.com/kingstdio/ECRECer
Project-URL: Repository, https://github.com/kingstdio/ECRECer
Keywords: bioinformatics,enzyme,EC number,machine learning,protein
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.87
Requires-Dist: h5py>=3.14
Requires-Dist: joblib>=1.5
Requires-Dist: numpy>=2.0
Requires-Dist: pandarallel>=1.6
Requires-Dist: pandas>=3.0
Requires-Dist: pyarrow>=25.0
Requires-Dist: scikit-learn>=1.9
Requires-Dist: scipy>=1.17
Requires-Dist: tqdm>=4.68
Requires-Dist: fair-esm>=2.0
Requires-Dist: tensorflow>=2.21
Requires-Dist: tf-keras>=2.21
Requires-Dist: torch>=2.13
Requires-Dist: xgboost>=3.2
Dynamic: license-file

# DMLF: Enzyme Commission Number Predicting and Benchmarking with Multi-agent Dual-core Learning

ECRECer is the official implementation of the hierarchical dual-core multitask learning framework described in the ECRECer papers. It is an Enzyme Commission (EC) number prediction and recommendation tool that accepts protein FASTA sequences and returns EC predictions, ranked EC recommendations, or hybrid results that combine prediction, recommendation, and sequence alignment.

## Web Server

For the simplest use, visit the ECRECer web server:

https://ecrecer.biodesign.ac.cn

## Papers

1. Zhenkun Shi, Qianqian Yuan, Ruoyu Wang, Haoran Li, Xiaoping Liao, and Hongwu Ma. ECRECer: Enzyme Commission Number Recommendation and Benchmarking based on Multiagent Dual-core Learning. arXiv:2202.03632.
2. Zhenkun Shi, Rui Deng, Qianqian Yuan, Zhitao Mao, Ruoyu Wang, Haoran Li, Xiaoping Liao, and Hongwu Ma. Enzyme Commission Number Prediction and Benchmarking with Hierarchical Dual-core Multitask Learning Framework. Research, 2023.

## Installation

Install the Python package from a built wheel or PyPI package:

```bash
python -m pip install ecrecer
```

The package installs the Python runtime dependencies needed for local inference. Large runtime artifacts are prepared with `ecrecer-setup` after installation.

## Step-by-step Local Pipeline

1. Install ECRECer:

```bash
python -m pip install ecrecer
```

2. Download and prepare runtime artifacts. This creates the directory layout, installs the bundled label dictionaries and sample FASTA file, and downloads the trained models, UniProt cache, and ESM32 feature bank:

```bash
ecrecer-setup --target ~/ecrecer_artifacts
```

The default artifact download is about 4.2 GB. For hybrid mode, also download the DIAMOND database:

```bash
ecrecer-setup --target ~/ecrecer_artifacts --with-hybrid
```

3. Point ECRECer at the artifact directory:

```bash
export ECRECER_ROOT=~/ecrecer_artifacts
```

4. Run the bundled sample in recommendation mode:

```bash
ecrecer -i "$ECRECER_ROOT/data/sample_10.fasta" -o ecrecer_sample10.tsv -mode r -topk 5
sed -n 1,5p ecrecer_sample10.tsv
```

5. Run your own FASTA file:

```bash
ecrecer -i input.fasta -o output.tsv -mode p -topk 5
```

## Artifact Layout

`ecrecer-setup` creates an `ECRECER_ROOT` directory with this runtime artifact layout:

```text
ECRECER_ROOT/
  data/
    dict/
    featureBank/
    uniprot/
  model/
  results/
  tmp/
```

Required production artifacts include:

- `data/uniprot/sprot_latest.feather`
- `data/featureBank/embd_esm32.feather`
- `data/dict/dict_label_task1.h5`
- `data/dict/dict_label_task2.h5`
- `data/dict/dict_label_task3.h5`
- `model/isenzyme.h5`
- `model/howmany_enzyme.h5`
- `model/ec.h5`

Preprocessed benchmark datasets are available separately from the public archive:

https://tibd-public-datasets.s3.amazonaws.com/ecrecer/ecrecer_datasets.zip


## Command Line Usage

Prediction mode writes final EC predictions:

```bash
ecrecer -i input.fasta -o output.tsv -mode p -topk 5
```

Recommendation mode writes top-k EC candidates with scores:

```bash
ecrecer -i input.fasta -o recommendations.tsv -mode r -topk 10
```

Hybrid mode also uses DIAMOND sequence alignment and requires a DIAMOND executable plus a production BLAST database under `data/uniprot_blast_db/`:

```bash
ecrecer -i input.fasta -o hybrid.tsv -mode h -topk 10
```

Legacy script usage is still supported:

```bash
python production.py -i input.fasta -o output.tsv -mode p -topk 5
```

## Input And Output Example

Input is a standard FASTA file:

```text
>query_1
MKTAYIAKQRQISFVKSHFSRQDILD
>query_2
MGSSHHHHHHSSGLVPRGSHM
```

Prediction mode (`-mode p`) writes a tab-separated table with one row per input sequence:

```text
id_input	ec_pred
query_1	2.6.1.19
query_2	-
```

Recommendation mode (`-mode r`) returns top-k candidate EC numbers and probabilities:

```text
id_input	dmlf_recomendations
query_1	[('2.6.1.19', 0.685800), ('2.6.1.22', 0.248600)]
```

`-` indicates a predicted non-enzyme or no EC assignment. For exact values, use the output generated by the installed model artifacts.

## GPU Runtime Notes

ECRECer uses the installed TensorFlow and PyTorch runtimes automatically. No separate ECRECer package is needed for different NVIDIA GPU models. For GPU acceleration, use a recent NVIDIA driver and a Python environment where TensorFlow and PyTorch can see the GPU; otherwise ECRECer runs with the available CPU/GPU backend.

## Docker And Singularity

Container images remain useful for users who prefer a prebuilt runtime:

```bash
docker pull kingstdio/ecrecer

# GPU runtime
sudo docker run -it -d --gpus all --name ecrecer -v "$PWD":/home kingstdio/ecrecer

# CPU runtime
sudo docker run -it -d --name ecrecer -v "$PWD":/home kingstdio/ecrecer

sudo docker exec ecrecer python /ecrecer/production.py -i /home/input.fasta -o /home/output.tsv -mode h -topk 10
```

```bash
wget -c https://tibd-public-datasets.s3.us-east-1.amazonaws.com/ecrecer/sifimages/ecrecer.sif
singularity run --nv ecrecer.sif python /ecrecer/production.py -i input.fasta -o output.tsv -mode h -topk 10

# CPU runtime
singularity run ecrecer.sif python /ecrecer/production.py -i input.fasta -o output.tsv -mode h -topk 10
```

## Citation

If ECRECer is useful in your work, please cite:

```bibtex
@article{shi2023enzyme,
  title={Enzyme Commission Number Prediction and Benchmarking with Hierarchical Dual-core Multitask Learning Framework},
  author={Shi, Zhenkun and Deng, Rui and Yuan, Qianqian and Mao, Zhitao and Wang, Ruoyu and Li, Haoran and Liao, Xiaoping and Ma, Hongwu},
  journal={Research},
  year={2023},
  publisher={AAAS}
}
```

Earlier preprint:

```text
Shi, Zhenkun, Qianqian Yuan, Ruoyu Wang, Haoran Li, Xiaoping Liao, and Hongwu Ma. ECRECer: Enzyme Commission Number Recommendation and Benchmarking based on Multiagent Dual-core Learning. arXiv:2202.03632.
```

## License

ECRECer is released under the MIT License. See `LICENSE`.

## Stargazers Over Time

[![Stargazers over time](https://starchart.cc/kingstdio/ECRECer.svg)](https://github.com/kingstdio/ECRECer/)
