enzymehunter 0.1.0__tar.gz

enzymehunter-0.1.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: enzymehunter
+Version: 0.1.0
+Summary: Fine-grained enzyme function prediction with EnzymeHunter
+Author: CGXBio
+Project-URL: Homepage, https://github.com/cgxbio/EnzymeHunter_pypi
+Project-URL: Repository, https://github.com/cgxbio/EnzymeHunter_pypi
+Project-URL: Issues, https://github.com/cgxbio/EnzymeHunter_pypi/issues
+Requires-Python: <3.13,>=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: biopython>=1.80
+Requires-Dist: biotite>=0.39
+Requires-Dist: tqdm>=4.65
+Requires-Dist: torch>=2.0
+Requires-Dist: torchvision>=0.15
+Requires-Dist: fair-esm>=2.0
+Requires-Dist: tm-vec>=1.0
+Requires-Dist: huggingface_hub>=0.23
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: hf
+Requires-Dist: huggingface_hub>=0.23; extra == "hf"
+
+# EnzymeHunter
+
+## Overview
+
+**EnzymeHunter**: Achieving fine-grained enzyme function prediction with a hierarchically-aware contrastive learning framework.
+The prediction pipeline was developed and tested on **Linux (CentOS)** with
+**Python 3.9**. The package also provides a CLI and Python API for installed
+use.
+
+## EnzymeHunter Architecture
+
+Architecture and workflow of the EnzymeHunter model：
+
+![EnzymeHunter Architecture](png/Architecture_EnzymeHunter.png)
+
+## Installation & Setup
+
+### Install from PyPI
+
+The project provides a Python API and a command-line entry point. Large
+pretrained weights and reference databases are distributed separately rather
+than embedded in the PyPI wheel.
+
+```bash
+python -m pip install enzymehunter
+```
+
+The PyPI package does not embed the large pretrained weights or reference
+database. Download both from Hugging Face with the command below, then run a
+prediction from the download directory:
+
+```bash
+cd /path/to/model-and-data
+enzymehunter predict input.fasta -o results.csv
+```
+
+By default, the CLI looks for `./model` and then
+`~/.cache/enzymehunter/model`, so `--model-dir` is normally unnecessary. If
+you store the model somewhere else, pass its location explicitly:
+
+```bash
+enzymehunter predict input.fasta \
+  --model-dir /data/enzymehunter/model \
+  -o results.csv
+```
+
+Use a specific device when needed:
+
+```bash
+# Automatically choose CUDA when available, otherwise CPU
+enzymehunter predict input.fasta --device auto -o results.csv
+
+# Force CPU
+enzymehunter predict input.fasta --device cpu -o results.csv
+
+# Use physical GPU 1
+enzymehunter predict input.fasta --device cuda:1 -o results.csv
+
+# Model stored outside the default locations
+enzymehunter predict input.fasta --model-dir /data/enzymehunter/model \
+  --device cuda:1 -o results.csv
+```
+
+For `cuda:N`, the selected physical GPU is isolated as logical `cuda:0` for
+the pipeline and its external tools, so all stages use the same GPU.
+
+The model directory must contain the downloaded model files, and its parent
+directory must contain the reference data used by the pipeline. Install
+`diamond` separately and ensure it is available on `PATH` or in the model
+directory. Linux with Python 3.9--3.11 is currently the tested environment.
+
+The same operation is available from Python:
+
+```python
+from enzymehunter import predict
+
+# Uses ./model by default
+predict("input.fasta", "results.csv")
+
+# Use this only when the model is stored elsewhere
+predict("input.fasta", "results.csv", model_dir="/data/enzymehunter/model")
+```
+
+### Download the model and reference data from Hugging Face
+
+The `Tonybio/EnzymeHunter` repository contains both the `model/` tree and the
+reference `data/` tree. Hugging Face support is installed automatically with
+`enzymehunter`:
+
+> Note: the current `model/` tree is approximately 18 GB, mainly because it
+> contains the ESM2 and ProtT5 weights. Make sure the target disk has enough
+> free space before starting.
+
+```bash
+python -m pip install enzymehunter
+enzymehunter download-hf-assets
+```
+
+By default, this creates `./model/` and `./data/` in the current directory.
+The older name `download-hf-model` remains an alias. Choose another directory
+or a fixed revision with:
+
+```bash
+enzymehunter download-hf-assets \
+  --dir /data/enzymehunter/model \
+  --repo-id Tonybio/EnzymeHunter \
+  --revision main
+```
+
+The `--dir` value is the model directory; the downloader places `data/` next
+to it. For example, `--dir /data/enzymehunter/model` creates:
+
+```text
+/data/enzymehunter/
+├── model/
+└── data/
+```
+
+The downloader supports caching and resuming and only retrieves the
+repository's `model/` and `data/` trees. The model tree is approximately
+18 GB, with additional space required for the reference data.
+
+The downloader tries the official Hugging Face endpoint first. If that fails,
+it automatically sets `HF_ENDPOINT=https://hf-mirror.com` and retries. To
+disable this fallback:
+
+```bash
+enzymehunter download-hf-assets --no-mirror-fallback
+```
+
+### Install from source for development
+
+1. **Clone the repository**
+
+   ```bash
+   git clone https://github.com/cgxbio/EnzymeHunter_pypi.git
+   cd EnzymeHunter_pypi
+   ```
+2. **Create and activate the virtual environment**
+
+   ```bash
+   conda env create -f environment.yml
+   conda activate EnzymeHunter
+   ```
+3. **Build and validate the package**
+
+   ```bash
+   python -m pip install -e ".[dev]"
+   python -m build
+   python -m twine check dist/*
+   ```
+
+## Assets layout
+
+The prediction pipeline expects the model directory and its reference data to
+be siblings:
+
+```
+<assets-root>/
+├── model/         # Model files downloaded from Hugging Face
+└── data/
+    ├── datasets/
+    │   ├── split100.csv
+    │   └── split100.fasta
+    ├── datasets_process/
+    │   └── train_dataset_model_embedding/
+    └── pdb/       # Optional PDB files named {UNIPROT_ID}.pdb
+```
+
+The `--model-dir` option points to `model/`. Its parent directory is used to
+locate the matching `data/` directory. If `--model-dir` is omitted, the CLI
+looks for `./model` first and then `~/.cache/enzymehunter/model`.
+
+## Usage Example
+
+Here are the common examples of using the **EnzymeHunter**, corresponding to different running modes:
+
+### 1. Normal Mode (Default Mode)
+
+Use this mode when you need the program to automatically distinguish between enzymes and non-enzymes, and only predict EC numbers for proteins classified as enzymes:
+
+```bash
+# Example: run prediction on a dataset where not all proteins are enzymes
+enzymehunter predict input.fasta \
+  -o results.csv
+```
+
+Explanation:
+
+- The input is a regular FASTA file; sequence identifiers become the `Entry` column.
+- The program first performs enzyme/non-enzyme classification.
+- Only proteins predicted as enzymes (`pred_label=1`) undergo EC number prediction.
+- Non-enzyme proteins are marked with EC number `0.0.0.0`.
+
+### 2. All-Enzymes Mode
+
+Use this mode when you know all proteins in the dataset are enzymes and want to skip the enzyme/non-enzyme classification step, proceeding directly to EC number prediction:
+
+```bash
+   # Example: run prediction assuming all proteins are enzymes
+   enzymehunter predict input.fasta \
+     --all-are-enzymes \
+     -o results.csv
+```
+
+Explanation:
+
+- `--all-are-enzymes` treats every input protein as an enzyme.
+- The enzyme/non-enzyme classification step is skipped.
+- All proteins receive `pred_label=1` and `pred_prob=1.0`.
+
+### 3. PDB-Based Contact Map Mode
+
+By default, EnzymeHunter uses **ESM2-predicted contact maps**. You can switch to **PDB-based contact maps** (computed from [AlphaFold](https://alphafold.com/download) or [ESMFold](https://github.com/facebookresearch/esm) 3D structures) with `--contact-map-source pdb`:
+
+1. Place your PDB structure files (named `{UNIPROT_ID}.pdb`) into the assets
+   directory under `data/pdb/` (for example, `/path/to/assets/data/pdb/`).
+2. Run the pipeline with `--contact-map-source pdb`:
+
+In this mode, EnzymeHunter will use the model trained with PDB-derived contact maps.
+
+```bash
+# Normal mode with PDB contact maps
+enzymehunter predict input.fasta \
+  --contact-map-source pdb \
+  -o results.csv
+
+# All-enzymes mode with PDB contact maps
+enzymehunter predict input.fasta \
+  --all-are-enzymes \
+  --contact-map-source pdb \
+  -o results.csv
+```
+
+## Output
+
+When using the PyPI CLI, the result is written to the path supplied with `-o`:
+
+```
+results.csv
+```

enzymehunter-0.1.0/README.md

@@ -0,0 +1,241 @@
+# EnzymeHunter
+
+## Overview
+
+**EnzymeHunter**: Achieving fine-grained enzyme function prediction with a hierarchically-aware contrastive learning framework.
+The prediction pipeline was developed and tested on **Linux (CentOS)** with
+**Python 3.9**. The package also provides a CLI and Python API for installed
+use.
+
+## EnzymeHunter Architecture
+
+Architecture and workflow of the EnzymeHunter model：
+
+![EnzymeHunter Architecture](png/Architecture_EnzymeHunter.png)
+
+## Installation & Setup
+
+### Install from PyPI
+
+The project provides a Python API and a command-line entry point. Large
+pretrained weights and reference databases are distributed separately rather
+than embedded in the PyPI wheel.
+
+```bash
+python -m pip install enzymehunter
+```
+
+The PyPI package does not embed the large pretrained weights or reference
+database. Download both from Hugging Face with the command below, then run a
+prediction from the download directory:
+
+```bash
+cd /path/to/model-and-data
+enzymehunter predict input.fasta -o results.csv
+```
+
+By default, the CLI looks for `./model` and then
+`~/.cache/enzymehunter/model`, so `--model-dir` is normally unnecessary. If
+you store the model somewhere else, pass its location explicitly:
+
+```bash
+enzymehunter predict input.fasta \
+  --model-dir /data/enzymehunter/model \
+  -o results.csv
+```
+
+Use a specific device when needed:
+
+```bash
+# Automatically choose CUDA when available, otherwise CPU
+enzymehunter predict input.fasta --device auto -o results.csv
+
+# Force CPU
+enzymehunter predict input.fasta --device cpu -o results.csv
+
+# Use physical GPU 1
+enzymehunter predict input.fasta --device cuda:1 -o results.csv
+
+# Model stored outside the default locations
+enzymehunter predict input.fasta --model-dir /data/enzymehunter/model \
+  --device cuda:1 -o results.csv
+```
+
+For `cuda:N`, the selected physical GPU is isolated as logical `cuda:0` for
+the pipeline and its external tools, so all stages use the same GPU.
+
+The model directory must contain the downloaded model files, and its parent
+directory must contain the reference data used by the pipeline. Install
+`diamond` separately and ensure it is available on `PATH` or in the model
+directory. Linux with Python 3.9--3.11 is currently the tested environment.
+
+The same operation is available from Python:
+
+```python
+from enzymehunter import predict
+
+# Uses ./model by default
+predict("input.fasta", "results.csv")
+
+# Use this only when the model is stored elsewhere
+predict("input.fasta", "results.csv", model_dir="/data/enzymehunter/model")
+```
+
+### Download the model and reference data from Hugging Face
+
+The `Tonybio/EnzymeHunter` repository contains both the `model/` tree and the
+reference `data/` tree. Hugging Face support is installed automatically with
+`enzymehunter`:
+
+> Note: the current `model/` tree is approximately 18 GB, mainly because it
+> contains the ESM2 and ProtT5 weights. Make sure the target disk has enough
+> free space before starting.
+
+```bash
+python -m pip install enzymehunter
+enzymehunter download-hf-assets
+```
+
+By default, this creates `./model/` and `./data/` in the current directory.
+The older name `download-hf-model` remains an alias. Choose another directory
+or a fixed revision with:
+
+```bash
+enzymehunter download-hf-assets \
+  --dir /data/enzymehunter/model \
+  --repo-id Tonybio/EnzymeHunter \
+  --revision main
+```
+
+The `--dir` value is the model directory; the downloader places `data/` next
+to it. For example, `--dir /data/enzymehunter/model` creates:
+
+```text
+/data/enzymehunter/
+├── model/
+└── data/
+```
+
+The downloader supports caching and resuming and only retrieves the
+repository's `model/` and `data/` trees. The model tree is approximately
+18 GB, with additional space required for the reference data.
+
+The downloader tries the official Hugging Face endpoint first. If that fails,
+it automatically sets `HF_ENDPOINT=https://hf-mirror.com` and retries. To
+disable this fallback:
+
+```bash
+enzymehunter download-hf-assets --no-mirror-fallback
+```
+
+### Install from source for development
+
+1. **Clone the repository**
+
+   ```bash
+   git clone https://github.com/cgxbio/EnzymeHunter_pypi.git
+   cd EnzymeHunter_pypi
+   ```
+2. **Create and activate the virtual environment**
+
+   ```bash
+   conda env create -f environment.yml
+   conda activate EnzymeHunter
+   ```
+3. **Build and validate the package**
+
+   ```bash
+   python -m pip install -e ".[dev]"
+   python -m build
+   python -m twine check dist/*
+   ```
+
+## Assets layout
+
+The prediction pipeline expects the model directory and its reference data to
+be siblings:
+
+```
+<assets-root>/
+├── model/         # Model files downloaded from Hugging Face
+└── data/
+    ├── datasets/
+    │   ├── split100.csv
+    │   └── split100.fasta
+    ├── datasets_process/
+    │   └── train_dataset_model_embedding/
+    └── pdb/       # Optional PDB files named {UNIPROT_ID}.pdb
+```
+
+The `--model-dir` option points to `model/`. Its parent directory is used to
+locate the matching `data/` directory. If `--model-dir` is omitted, the CLI
+looks for `./model` first and then `~/.cache/enzymehunter/model`.
+
+## Usage Example
+
+Here are the common examples of using the **EnzymeHunter**, corresponding to different running modes:
+
+### 1. Normal Mode (Default Mode)
+
+Use this mode when you need the program to automatically distinguish between enzymes and non-enzymes, and only predict EC numbers for proteins classified as enzymes:
+
+```bash
+# Example: run prediction on a dataset where not all proteins are enzymes
+enzymehunter predict input.fasta \
+  -o results.csv
+```
+
+Explanation:
+
+- The input is a regular FASTA file; sequence identifiers become the `Entry` column.
+- The program first performs enzyme/non-enzyme classification.
+- Only proteins predicted as enzymes (`pred_label=1`) undergo EC number prediction.
+- Non-enzyme proteins are marked with EC number `0.0.0.0`.
+
+### 2. All-Enzymes Mode
+
+Use this mode when you know all proteins in the dataset are enzymes and want to skip the enzyme/non-enzyme classification step, proceeding directly to EC number prediction:
+
+```bash
+   # Example: run prediction assuming all proteins are enzymes
+   enzymehunter predict input.fasta \
+     --all-are-enzymes \
+     -o results.csv
+```
+
+Explanation:
+
+- `--all-are-enzymes` treats every input protein as an enzyme.
+- The enzyme/non-enzyme classification step is skipped.
+- All proteins receive `pred_label=1` and `pred_prob=1.0`.
+
+### 3. PDB-Based Contact Map Mode
+
+By default, EnzymeHunter uses **ESM2-predicted contact maps**. You can switch to **PDB-based contact maps** (computed from [AlphaFold](https://alphafold.com/download) or [ESMFold](https://github.com/facebookresearch/esm) 3D structures) with `--contact-map-source pdb`:
+
+1. Place your PDB structure files (named `{UNIPROT_ID}.pdb`) into the assets
+   directory under `data/pdb/` (for example, `/path/to/assets/data/pdb/`).
+2. Run the pipeline with `--contact-map-source pdb`:
+
+In this mode, EnzymeHunter will use the model trained with PDB-derived contact maps.
+
+```bash
+# Normal mode with PDB contact maps
+enzymehunter predict input.fasta \
+  --contact-map-source pdb \
+  -o results.csv
+
+# All-enzymes mode with PDB contact maps
+enzymehunter predict input.fasta \
+  --all-are-enzymes \
+  --contact-map-source pdb \
+  -o results.csv
+```
+
+## Output
+
+When using the PyPI CLI, the result is written to the path supplied with `-o`:
+
+```
+results.csv
+```

enzymehunter-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "enzymehunter"
+version = "0.1.0"
+description = "Fine-grained enzyme function prediction with EnzymeHunter"
+readme = "README.md"
+requires-python = ">=3.9,<3.13"
+authors = [
+  { name = "CGXBio" }
+]
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+  "scipy>=1.10",
+  "scikit-learn>=1.2",
+  "biopython>=1.80",
+  "biotite>=0.39",
+  "tqdm>=4.65",
+  "torch>=2.0",
+  "torchvision>=0.15",
+  "fair-esm>=2.0",
+  "tm-vec>=1.0",
+  "huggingface_hub>=0.23"
+]
+
+[project.optional-dependencies]
+dev = [
+  "build",
+  "twine",
+  "pytest",
+  "ruff"
+]
+hf = [
+  "huggingface_hub>=0.23"
+]
+
+[project.urls]
+Homepage = "https://github.com/cgxbio/EnzymeHunter_pypi"
+Repository = "https://github.com/cgxbio/EnzymeHunter_pypi"
+Issues = "https://github.com/cgxbio/EnzymeHunter_pypi/issues"
+
+[project.scripts]
+enzymehunter = "enzymehunter.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

enzymehunter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

enzymehunter-0.1.0/src/enzymehunter/__init__.py

@@ -0,0 +1,11 @@
+"""EnzymeHunter: fine-grained enzyme function prediction."""
+
+
+def predict(*args, **kwargs):
+    """Run a prediction, importing the heavy scientific stack lazily."""
+    from .api import predict as _predict
+
+    return _predict(*args, **kwargs)
+
+
+__all__ = ["predict"]

enzymehunter-0.1.0/src/enzymehunter/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

enzymehunter-0.1.0/src/enzymehunter/api.py

@@ -0,0 +1,69 @@
+"""Public Python API for EnzymeHunter."""
+
+from pathlib import Path
+import shutil
+
+from .runtime import workspace
+from .device import configure_device, validate_device
+
+
+def _default_model_dir():
+    """Find the model directory in the current project or user cache."""
+    current = Path.cwd()
+    if (current / "model").is_dir():
+        return current / "model"
+
+    cached = Path.home() / ".cache" / "enzymehunter"
+    if (cached / "model").is_dir():
+        return cached / "model"
+
+    return current / "model"
+
+
+def predict(
+    input_fasta,
+    output_path=None,
+    model_dir=None,
+    all_enzymes=False,
+    contact_map_source="esm2",
+    device="auto",
+):
+    """Run EnzymeHunter on a FASTA file.
+
+    ``model_dir`` points to the directory containing EnzymeHunter model files.
+    It is optional: when omitted, ``./model`` and then
+    ``~/.cache/enzymehunter/model`` are checked. The matching reference data
+    is expected in the model directory's parent under ``data/``.
+    """
+    input_fasta = Path(input_fasta).expanduser().resolve()
+    if model_dir is None:
+        model_dir = _default_model_dir()
+    configure_device(device)
+    if not input_fasta.is_file():
+        raise FileNotFoundError(f"Input FASTA file does not exist: {input_fasta}")
+
+    if output_path is None:
+        output_path = input_fasta.with_name(f"{input_fasta.stem}_results.csv")
+    output_path = Path(output_path).expanduser().resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Import the scientific stack only when a prediction is requested. This
+    # keeps ``enzymehunter --help`` and package metadata commands lightweight.
+    from .pipeline import run_prediction_pipeline
+    validate_device(device)
+
+    with workspace(model_dir) as root:
+        dataset_name = input_fasta.stem
+        staged_input = root / "data" / "datasets" / f"{dataset_name}.fasta"
+        shutil.copy2(input_fasta, staged_input)
+
+        result = run_prediction_pipeline(
+            dataset_name,
+            all_enzymes=all_enzymes,
+            contact_map_source=contact_map_source,
+        )
+        # The legacy pipeline writes tab-separated files with a .csv suffix.
+        # The public API writes a conventional comma-separated CSV.
+        result.to_csv(output_path, index=False)
+
+    return result