Metadata-Version: 2.4
Name: proteoannot
Version: 0.1.0
Summary: Biological and physicochemical protein annotation from FASTA sequences (iFeature, IEDB, SignalP)
Author-email: Samavi Nasir <samavi.nasir96@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/samavinasir/proteoannot
Project-URL: Repository, https://github.com/samavinasir/proteoannot
Project-URL: Bug Tracker, https://github.com/samavinasir/proteoannot/issues
Project-URL: Paper, https://doi.org/10.1016/j.vaccine.2024.126204
Keywords: bioinformatics,reverse vaccinology,protein annotation,vaccine design,epitope prediction
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: biopython
Requires-Dist: iedb
Requires-Dist: pybiolib
Dynamic: license-file

# 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](https://github.com/Superzchen/iFeature)) —
  autocorrelation, composition, quasi-sequence-order, and related descriptors (~3,650 features)
- **Epitope predictions** (via [IEDB](http://tools.iedb.org/main/)) — MHC class I & II binding
  (multi-allele supported), B-cell epitopes, surface probability, antigenicity
- **Signal peptide predictions** (via [SignalP 6.0](https://services.healthtech.dtu.dk/services/SignalP-6.0/),
  through [pybiolib](https://pypi.org/project/pybiolib/))

ProteoAnnot was extracted from the annotation engine originally built for
[VacSol-ML(ESKAPE)](https://doi.org/10.1016/j.vaccine.2024.126204), 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

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

```bash
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](https://github.com/Superzchen/iFeature)
> 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:
> ```bash
> pip install pybiolib
> ```

---

## Quickstart

### Python API

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

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

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

```bash
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:
```bash
  $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](LICENSE) for details.
