Metadata-Version: 2.4
Name: ecrecer
Version: 1.0.4
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
Provides-Extra: runtime
Requires-Dist: fair-esm>=2.0; extra == "runtime"
Requires-Dist: tensorflow>=2.21; extra == "runtime"
Requires-Dist: tf-keras>=2.21; extra == "runtime"
Requires-Dist: torch>=2.13; extra == "runtime"
Requires-Dist: xgboost>=3.2; extra == "runtime"
Dynamic: license-file

# ECRECer

ECRECer predicts and recommends Enzyme Commission (EC) numbers from protein FASTA sequences. It implements the hierarchical dual-core multitask learning workflow described in the ECRECer papers, with local inference support for annotation, recommendation, and hybrid sequence-alignment modes.

## Installation

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

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

The package intentionally does not include large data files, UniProt snapshots, feature banks, or trained model weights. Prepare those artifacts separately and point ECRECer at their root directory with `ECRECER_ROOT`.

For the RTX 5090 runtime, install PyTorch from the CUDA 13.0 PyTorch index first, then install the pinned runtime stack:

```bash
python -m pip install --index-url https://download.pytorch.org/whl/cu130 torch==2.13.0+cu130
python -m pip install -r requirements/runtime-5090.txt
```

## Artifact Layout

`ECRECER_ROOT` should contain the same runtime artifact layout used by the repository checkout:

```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`

Set the artifact root before running:

```bash
export ECRECER_ROOT=/path/to/ecrecer_artifacts
```

## Quick Start

Use `data/sample_10.fasta` for a minimal local run when the artifact root is this repository checkout:

```bash
export ECRECER_ROOT=/path/to/ecrecer_artifacts
ecrecer -i "$ECRECER_ROOT/data/sample_10.fasta" -o /tmp/ecrecer_sample10.tsv -mode p -topk 5
sed -n '1,5p' /tmp/ecrecer_sample10.tsv
```

## 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

- The validated 5090 stack uses PyTorch `2.13.0+cu130` for ESM embedding.
- Existing `.h5` prediction heads are loaded through TensorFlow/Keras compatibility wrappers.
- TensorFlow `2.21.0` can see RTX 5090 GPUs but may JIT kernels from PTX because current wheels do not ship native kernels for compute capability `12.0a`.

## Docker And Singularity

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

```bash
docker pull kingstdio/ecrecer
sudo docker run -it -d --gpus all --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
```

## 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`.
