ProteoAnnot

ProteoAnnot is a standalone Python package for annotating protein sequences with biological and physicochemical properties — the kind of feature set used in reverse vaccinology and machine-learning-based antigen prediction pipelines.

Given a FASTA file, ProteoAnnot produces:

• Physicochemical descriptors (via iFeature) — autocorrelation, composition, quasi-sequence-order, and related descriptors (~3,650 features)
• Epitope predictions (via IEDB) — MHC class I & II binding (multi-allele supported), B-cell epitopes, surface probability, antigenicity
• Signal peptide predictions (via SignalP 6.0, through pybiolib)

ProteoAnnot was extracted from the annotation engine originally built for VacSol-ML(ESKAPE), a machine-learning tool for predicting vaccine candidates against ESKAPE pathogens. It's published here as a general-purpose, reusable annotation library — independent of any specific prediction model or pathogen family.

---

Installation

pip install proteoannot

(Or, for local development: pip install -e . from a cloned copy of this repo.)

External dependencies you must obtain separately

ProteoAnnot orchestrates external bioinformatics tools rather than reimplementing them. Two of these are not pip-installable and must be set up yourself:

iFeature (physicochemical descriptors) — clone it and point ProteoAnnot at the script:

git clone https://github.com/Superzchen/iFeature.git

Note on licensing: the iFeature repository does not include an explicit open-source license file. Review the original repository yourself before using or redistributing it. ProteoAnnot does not bundle or redistribute iFeature — you run your own local copy.

IEDB and SignalP — accessed automatically via the iedb and pybiolib Python packages (installed as part of ProteoAnnot's dependencies), which make live API calls to IEDB's tools and a hosted SignalP job via BioLib. An internet connection is required at runtime.

Common gotcha: there are two unrelated PyPI packages that both import as biolib. ProteoAnnot depends on pybiolib (the BioLib remote-execution client). If you see AttributeError: module 'biolib' has no attribute 'load', you likely have the wrong package installed:

pip install pybiolib

---

Quickstart

Python API

from proteoannot.pipeline import annotate

result = annotate(
    fasta_path="proteins.fasta",
    ifeature_script_path="iFeature/iFeature.py",
    mhci_alleles=["HLA-A*02:01"],
    mhcii_alleles=["HLA-DRB1*01:01"],
)

result.physicochemical      # DataFrame: iFeature descriptors, one row per protein
result.mhci_df              # DataFrame: MHC-I scores, one row per (protein, allele)
result.mhcii_df             # DataFrame: MHC-II scores, one row per (protein, allele)
result.bcell_df             # DataFrame: B-cell/surface/antigenicity, one row per protein
result.signal_peptide_df    # DataFrame: SignalP predictions, one row per protein
result.epitopes             # dict: raw predicted epitope sequences per protein/allele
result.header_map           # dict: sanitized ID -> original FASTA header

# Convenience: one wide table, MHC scores aggregated across alleles
merged_df = result.merged(allele_aggregation="mean")

Command line

proteoannot run \
  --fasta proteins.fasta \
  --ifeature-script iFeature/iFeature.py \
  --mhci-alleles HLA-A*02:01 HLA-B*07:02 \
  --mhcii-alleles HLA-DRB1*01:01 \
  --output-dir results/

This writes physicochemical.csv, mhci.csv, mhcii.csv, bcell.csv, signal_peptide.csv, and merged.csv into results/.

Run proteoannot run --help for the full list of options (peptide lengths, rank cutoffs, SignalP organism type, allele aggregation method, etc.).

---

Validated example

ProteoAnnot has been run end-to-end against real protein sequences via live IEDB and SignalP services. For example, annotating UniProt entry P32722.1 produced biologically plausible results across every module: a confidently predicted Sec/SPI signal peptide (cleavage site, high SP score), non-trivial MHC-I/II binding epitopes passing standard rank-cutoff filters, and a full, NaN-free physicochemical feature set matching the original VacSol-ML(ESKAPE) feature specification (3,650 descriptors).

---

Architecture

proteoannot/
├── io.py FASTA parsing and header sanitization
├── physicochemical.py iFeature subprocess wrapper
├── epitopes.py IEDB MHC-I/II + B-cell epitope wrapper (multi-allele)
├── signal_peptide.py SignalP 6.0 wrapper (via pybiolib)
├── pipeline.py Orchestrates the above into annotate()
└── cli.py argparse-based command-line interface

Each module is independently testable and has no dependency on any specific downstream ML model — ProteoAnnot's job ends at producing annotated features; what you do with them (train a classifier, score candidates, etc.) is up to the caller.

---

Development

git clone proteoannot
cd proteoannot
python -m venv .venv
.venv\Scripts\Activate.ps1   # Windows PowerShell
pip install -e .
pip install pytest

Run the test suite:

python -m pytest tests/ -v

Windows note: always invoke tests via python -m pytest, not bare pytest. If you have a globally-installed Python alongside your virtual environment, the bare pytest command can resolve to the global installation's executable rather than the one inside .venv, silently running against the wrong environment.

Some tests require external tools/services and are conditionally skipped:

• test_physicochemical.py requires a local iFeature installation. Set the IFEATURE_SCRIPT_PATH environment variable to enable it:

  $env:IFEATURE_SCRIPT_PATH = "path\to\iFeature\iFeature.py"

• test_epitopes.py and test_signal_peptide.py use mocked external calls and run without network access or external tool installation.

---

Citation

If you use ProteoAnnot in your research, please cite the original VacSol-ML(ESKAPE) paper:

Nasir S, Anwer F, Ishaq Z, Saeed MT, Ali A. VacSol-ML(ESKAPE): Machine learning empowering vaccine antigen prediction for ESKAPE pathogens. Vaccine. 2024;42:126204. https://doi.org/10.1016/j.vaccine.2024.126204

---

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.