Metadata-Version: 2.4
Name: immunoHERD
Version: 0.1.1
Summary: HERD — host-aware prediction of protein immunogenicity
Author: Isidro Sobrino
License-Expression: MIT
Keywords: immunogenicity,antigen,vaccine,protein,ESM-2,protein-language-model,veterinary,bioinformatics,deep-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fair-esm
Requires-Dist: torch
Requires-Dist: tensorflow>=2.16
Requires-Dist: keras<4,>=3.13
Requires-Dist: numpy
Requires-Dist: pandas
Dynamic: license-file

# HERD

**H**ost-aware **E**stimation of antigen immunogenicity and **R**anking through
**D**eep-learning.

HERD predicts the immunogenicity of proteins taking the host species into
account. This package is the reusable core shared by the different surfaces of
the project (web Space, Colab and command line).

## Pipeline

1. Sequence cleaning: any character outside `ACDEFGHIKLMNPQRSTVWY` becomes `X`,
   and the sequence is truncated to 1022 residues.
2. Embedding with ESM-2 (`esm2_t33_650M_UR50D`, layer 33) via `fair-esm`,
   mean-pooled over the real residues: a 1280-dimensional vector.
3. A host-aware head on top of that embedding. Normalization lives inside the
   `.keras` file itself, so the raw embedding is fed in unscaled.
4. Decision threshold: 0.5.

## Installation

```bash
pip install immunoHERD
```

The package is installed as `immunoHERD` but imported as `herd`, and the
console command is `herd`.

The model weights ship inside the package. The ESM-2 weights, by contrast, are
downloaded automatically the first time an embedding is computed.

## Usage

### From Python

```python
from herd import predict_fasta

df = predict_fasta("proteins.fasta", host="Bos_taurus", model="integrated")
print(df)
```

`predict` (a list of `(id, sequence)` tuples) and `predict_text` (pasted FASTA
text, or a bare sequence) are also available. All three return a `DataFrame`
sorted by descending score with the columns `id`, `length`, `host`, `model`,
`score`, `prediction` and `warnings`. Sequences that fail validation are
returned at the end, with `score` set to `NaN`.

The `warnings` column also records when a sequence was modified: non-canonical
residues replaced by `X`, or truncation to 1022 residues.

### From the command line

```bash
herd predict proteins.fasta --host Bos_taurus --out results.csv
herd predict proteins.fasta --host Canis_sp --model individual --out dog.csv
herd hosts
```

`--out` is required, so a long run cannot be lost by forgetting to save it.
Other options: `--model`, `--threshold`, `--batch-seqs`, `--device`.
Warnings go to standard error, so the CSV stays clean when redirected.

## Models and hosts

Two models, selected with the `model` argument:

- `"integrated"` — a pan-species model with 15 heads, one per host.
  This is the recommended default.
- `"individual"` — one model trained per species. Only available for the six
  core hosts: `Homo_sapiens`, `Bos_taurus`, `Sus_scrofa`, `Gallus_gallus`,
  `Canis_sp` and `Equus_caballus`.

The integrated model also covers nine auxiliary hosts: `Camelidae`,
`Capra_hircus`, `Cavia_porcellus`, `Macaca_sp_`, `Mus_musculus`,
`Non_human_primate`, `Oryctolagus_cuniculus`, `Ovis_aries` and `Rattus_sp_`.
**These nine heads are not validated to the same level as the six core hosts,
and their scores should be interpreted with more caution.**

Host names accept some common aliases (`Canis_familiaris`, `Homo`, `Rattus`…)
and a loose genus match.

## Where the models are looked up

By default, in the `models/` directory that ships inside the installed package.
A different location can be given through the `HERD_MODELS_DIR` environment
variable, which takes precedence:

```bash
export HERD_MODELS_DIR=/path/to/my/models
```

The expected layout is `<HERD_MODELS_DIR>/integrated.keras` and
`<HERD_MODELS_DIR>/individual/<host>.keras`.

## Performance notes

Sequences are grouped into batches **sorted by length**, which removes almost
all padding: on a real proteome (4,570 sequences) this halves the GPU work.
Results are unaffected, since each mean is computed only over the real residues
of its own sequence.

A GPU is not required, but embedding on CPU is considerably slower.
