immunoHERD 0.1.1__tar.gz

immunoherd-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isidro Sobrino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

immunoherd-0.1.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# Ship the model weights in the sdist as well, not only in the wheel.
+recursive-include src/herd/models *.keras
+include README.md
+include LICENSE

immunoherd-0.1.1/PKG-INFO

@@ -0,0 +1,131 @@
+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.

immunoherd-0.1.1/README.md

@@ -0,0 +1,103 @@
+# 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.

immunoherd-0.1.1/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Distribution name (pip install immunoHERD). The IMPORT name and the
+# console command are both `herd`.
+name = "immunoHERD"
+# Única fuente de la versión: herd/__init__.py (__version__).
+dynamic = ["version"]
+description = "HERD — host-aware prediction of protein immunogenicity"
+readme = "README.md"
+# >=3.11 porque los modelos necesitan keras>=3.13 (ver dependencies),
+# y Keras 3.13 dejó de publicar para Python 3.10 y anteriores.
+requires-python = ">=3.11"
+authors = [{ name = "Isidro Sobrino" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "immunogenicity", "antigen", "vaccine", "protein", "ESM-2",
+    "protein-language-model", "veterinary", "bioinformatics", "deep-learning",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+# HERD needs torch (for ESM-2) and TensorFlow (for the .keras heads).
+#
+# keras>=3.13 is NOT optional: the bundled .keras files were written by
+# Keras 3.13.2 and their layer configs carry `quantization_config`, a field
+# Keras 3.12 does not know. TensorFlow only requires keras>=3.12, so without
+# this floor pip can resolve a Keras that installs fine but fails at load
+# time with "Unrecognized keyword arguments passed to Dense".
+dependencies = [
+    "fair-esm",
+    "torch",
+    # First TensorFlow release that requires Keras 3 (2.15 pins keras<2.16,
+    # i.e. Keras 2, which cannot load these models at all).
+    "tensorflow>=2.16",
+    # Floor: the bundled .keras files were written by Keras 3.13.2 and their
+    # layer configs carry `quantization_config`, unknown to Keras 3.12.
+    # Ceiling: the saved-model format has already broken twice across Keras
+    # minor versions, so a major bump is not assumed to be safe.
+    "keras>=3.13,<4",
+    "numpy",
+    "pandas",
+]
+
+# Console command: `herd predict ...` / `herd hosts`
+[project.scripts]
+herd = "herd.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "herd.__version__" }
+
+[tool.setuptools]
+# src-layout: el paquete no es importable desde la raíz del repositorio,
+# así que cualquier prueba usa por fuerza la versión instalada.
+package-dir = { "" = "src" }
+packages = ["herd"]
+include-package-data = true
+
+# The .keras weights are data, not code: without this declaration the wheel
+# is built without them and nothing fails until prediction time.
+[tool.setuptools.package-data]
+herd = ["models/*.keras", "models/individual/*.keras"]

immunoherd-0.1.1/setup.cfg

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

immunoherd-0.1.1/src/herd/__init__.py

@@ -0,0 +1,17 @@
+"""
+HERD — Host-aware Estimation of antigen immunogenicity and Ranking
+through Deep-learning. Núcleo reutilizable (Space / Colab / CLI).
+
+    from herd import predict_fasta
+    df = predict_fasta("proteinas.fasta", host="Bos_taurus", model="integrated")
+"""
+
+from .inference import predict, predict_fasta, predict_text
+from .config import SPECIES_ORDER, CORE_HOSTS, THRESHOLD
+
+__all__ = [
+    "predict", "predict_fasta", "predict_text",
+    "SPECIES_ORDER", "CORE_HOSTS", "THRESHOLD",
+]
+
+__version__ = "0.1.1"

immunoherd-0.1.1/src/herd/cli.py

@@ -0,0 +1,124 @@
+"""
+herd/cli.py — Interfaz de línea de comandos.
+
+    herd predict proteins.fasta --host Bos_taurus --out results.csv
+    herd hosts
+
+No contiene ciencia: traduce argumentos a llamadas de `herd.inference`.
+Los textos visibles para el usuario van en inglés, como el resto del proyecto.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from .config import SPECIES_ORDER, CORE_HOSTS, THRESHOLD, LABEL_POS
+
+
+# --- herd hosts --------------------------------------------------------------
+def _cmd_hosts(args) -> int:
+    core = set(CORE_HOSTS)
+    print("Hosts supported by the integrated model (15 heads):\n")
+    for sp in SPECIES_ORDER:
+        print(f"  {'core     ' if sp in core else 'auxiliary'} {sp}")
+    print(
+        "\ncore       also has its own individual model (--model individual)."
+        "\nauxiliary  exists only as a head of the integrated model. These nine"
+        "\n           heads are not validated to the same level as the core"
+        "\n           hosts: interpret their scores with caution."
+    )
+    return 0
+
+
+# --- herd predict ------------------------------------------------------------
+def _cmd_predict(args) -> int:
+    fasta = Path(args.fasta)
+    if not fasta.is_file():
+        print(f"herd: no such file '{fasta}'", file=sys.stderr)
+        return 2
+
+    out = Path(args.out)
+    if out.parent and not out.parent.exists():
+        print(f"herd: output directory '{out.parent}' does not exist", file=sys.stderr)
+        return 2
+
+    # Importación diferida: arrastra torch y TensorFlow, que tardan en cargar.
+    from .models import resolve_host
+    from .inference import predict_fasta
+
+    sp = resolve_host(args.host)
+    if sp is None:
+        print(f"herd: unknown host '{args.host}'. "
+              f"Run 'herd hosts' to see the list.", file=sys.stderr)
+        return 2
+    if args.model == "individual" and sp not in CORE_HOSTS:
+        print(f"herd: no individual model for '{sp}'. "
+              f"Only available for: {', '.join(CORE_HOSTS)}.", file=sys.stderr)
+        return 2
+    if sp != args.host:
+        print(f"herd: '{args.host}' interpreted as '{sp}'.", file=sys.stderr)
+    if sp not in CORE_HOSTS:
+        print(f"herd: warning — '{sp}' is an auxiliary head, not validated to "
+              f"the same level as the core hosts.", file=sys.stderr)
+
+    df = predict_fasta(
+        str(fasta),
+        host=sp,
+        model=args.model,
+        threshold=args.threshold,
+        device=args.device,
+        batch_seqs=args.batch_seqs,
+    )
+
+    df.to_csv(out, index=False)
+
+    total = len(df)
+    errors = int((df["prediction"] == "ERROR").sum()) if total else 0
+    positives = int((df["prediction"] == LABEL_POS).sum()) if total else 0
+    print(f"herd: {total} sequences | {positives} above threshold "
+          f"{args.threshold} | {errors} with errors", file=sys.stderr)
+    print(f"herd: results written to {out}", file=sys.stderr)
+    return 0
+
+
+# --- Punto de entrada --------------------------------------------------------
+def build_parser() -> argparse.ArgumentParser:
+    from . import __version__
+
+    p = argparse.ArgumentParser(
+        prog="herd",
+        description="HERD — host-aware prediction of protein immunogenicity.",
+    )
+    p.add_argument("--version", action="version", version=f"herd {__version__}")
+    sub = p.add_subparsers(dest="command", required=True, metavar="COMMAND")
+
+    pr = sub.add_parser("predict", help="Predict from a FASTA file.")
+    pr.add_argument("fasta", help="Input FASTA file.")
+    pr.add_argument("--host", required=True,
+                    help="Target host (see 'herd hosts').")
+    pr.add_argument("--out", required=True,
+                    help="Output CSV file (required).")
+    pr.add_argument("--model", choices=("integrated", "individual"),
+                    default="integrated",
+                    help="Model to use (default: integrated).")
+    pr.add_argument("--threshold", type=float, default=THRESHOLD,
+                    help=f"Decision threshold (default: {THRESHOLD}).")
+    pr.add_argument("--batch-seqs", type=int, default=8, dest="batch_seqs",
+                    help="Sequences per batch when embedding (default: 8).")
+    pr.add_argument("--device", default=None,
+                    help="Torch device: cpu or cuda (default: automatic).")
+    pr.set_defaults(func=_cmd_predict)
+
+    ho = sub.add_parser("hosts", help="List the available hosts.")
+    ho.set_defaults(func=_cmd_hosts)
+
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

immunoherd-0.1.1/src/herd/config.py

@@ -0,0 +1,56 @@
+"""
+herd/config.py — Constantes inmutables de HERD (sin lógica).
+Verificado desde el código original. Si es un número o nombre fijo, va aquí.
+"""
+
+import os
+from pathlib import Path
+
+# --- Pipeline ESM-2 (idéntico en generación e inferencia) -------------------
+ESM_MODEL   = "esm2_t33_650M_UR50D"   # fair-esm, NO HuggingFace
+REPR_LAYER  = 33
+EMBED_DIM   = 1280
+SEQ_LENGTH  = 1022
+VALID_AA    = "ACDEFGHIKLMNPQRSTVWY"
+UNKNOWN_AA  = "X"
+THRESHOLD   = 0.5
+
+# --- Modelo integrado: orden de las 15 cabezas (config_modelo_final.json) ----
+SPECIES_ORDER = [
+    "Bos_taurus", "Gallus_gallus", "Homo_sapiens", "Equus_caballus",
+    "Sus_scrofa", "Canis_sp", "Camelidae", "Capra_hircus", "Cavia_porcellus",
+    "Macaca_sp_", "Mus_musculus", "Non_human_primate", "Oryctolagus_cuniculus",
+    "Ovis_aries", "Rattus_sp_",
+]
+SP2ID = {sp: i for i, sp in enumerate(SPECIES_ORDER)}
+
+# Hosts con modelo INDIVIDUAL propio (solo los 6 core)
+CORE_HOSTS = [
+    "Homo_sapiens", "Bos_taurus", "Sus_scrofa",
+    "Gallus_gallus", "Canis_sp", "Equus_caballus",
+]
+
+# Alias de nombres de host (de app_integrado_porhost.ipynb)
+HOST_ALIASES = {
+    "Canis": "Canis_sp", "Canis_familiaris": "Canis_sp",
+    "Canis_lupus_familiaris": "Canis_sp", "Cavia": "Cavia_porcellus",
+    "Rattus": "Rattus_sp_", "Macaca": "Macaca_sp_", "Homo": "Homo_sapiens",
+}
+
+# --- Localización de los pesos (layout limpio) ------------------------------
+# Estructura esperada:
+#   <MODELS_ROOT>/individual/<host>.keras   (host = clave de especie)
+#   <MODELS_ROOT>/integrated.keras
+# Resolución en dos escalones:
+#   1) HERD_MODELS_DIR si está definida (Space, pruebas, modelos alternativos).
+#   2) la carpeta empaquetada junto a este módulo (paquete instalado).
+# Se resuelve desde __file__, NO desde el directorio de trabajo: tras un
+# `pip install` el cwd del usuario no tiene ninguna carpeta 'models'.
+_ENV_MODELS = os.environ.get("HERD_MODELS_DIR")
+MODELS_ROOT = Path(_ENV_MODELS) if _ENV_MODELS else Path(__file__).resolve().parent / "models"
+INDIVIDUAL_DIR  = "individual"
+INTEGRATED_FILE = "integrated.keras"
+
+# Etiquetas de salida
+LABEL_POS = "probable immunogen"
+LABEL_NEG = "probable non immunogen"

immunoherd-0.1.1/src/herd/esm.py

@@ -0,0 +1,85 @@
+"""
+herd/esm.py — ESM-2: carga y embedding (parte de GPU).
+
+Reglas heredadas del código original que NO se tocan:
+  - el modelo se carga UNA sola vez (singleton perezoso),
+  - .eval() + torch.no_grad(),
+  - se devuelve numpy (CPU), nunca tensores CUDA (crítico en ZeroGPU),
+  - la receta de pooling `reps[k, 1:tr+1].mean(0)` es intocable.
+
+Recibe secuencias YA LIMPIAS (ver validation.py).
+"""
+
+from typing import List, Optional
+
+import numpy as np
+import torch
+from esm import pretrained
+
+from .config import ESM_MODEL, REPR_LAYER, SEQ_LENGTH, EMBED_DIM
+
+_esm = None  # caché a nivel de módulo: (model, alphabet, batch_converter, device)
+
+
+def get_esm(device: Optional[str] = None):
+    """Carga ESM-2 la primera vez y lo reutiliza en llamadas posteriores."""
+    global _esm
+    if _esm is None:
+        model, alphabet = pretrained.load_model_and_alphabet(ESM_MODEL)
+        model.eval()
+        device = device or ("cuda" if torch.cuda.is_available() else "cpu")
+        model = model.to(device)
+        batch_converter = alphabet.get_batch_converter(SEQ_LENGTH)
+        _esm = (model, alphabet, batch_converter, device)
+    return _esm
+
+
+@torch.no_grad()
+def embed_sequences(
+    seqs: List[str],
+    ids: Optional[List[str]] = None,
+    device: Optional[str] = None,
+    batch_seqs: int = 8,
+) -> np.ndarray:
+    """
+    Secuencias limpias -> matriz (N, 1280) float32, en el orden de entrada.
+
+    `batch_seqs` es el nº máximo de secuencias por lote (como en las apps).
+
+    Las secuencias se agrupan ORDENADAS POR LONGITUD y el resultado se
+    devuelve al orden original. Cada lote se rellena hasta su secuencia más
+    larga, así que agrupar longitudes parecidas elimina casi todo el relleno:
+    sobre un proteoma real (4.570 secuencias, media 386 residuos, con un 5%
+    en el tope de 1022) esto reduce a la mitad el cómputo de GPU.
+
+    NO cambia el resultado numérico: la media de cada secuencia se hace solo
+    sobre sus residuos reales, y el relleno nunca entra en ella. Tampoco sube
+    el pico de memoria: el lote más caro sigue siendo `batch_seqs` secuencias
+    de longitud máxima, igual que antes.
+    """
+    model, alphabet, batch_converter, dev = get_esm(device)
+    n = len(seqs)
+    X = np.zeros((n, EMBED_DIM), dtype="float32")
+    if n == 0:
+        return X
+
+    if ids is None:
+        ids = [str(i) for i in range(n)]
+
+    # Índices ordenados de más larga a más corta. Descendente a propósito:
+    # si algo va a quedarse sin memoria, falla en el primer lote y no a mitad.
+    orden = sorted(range(n), key=lambda i: len(seqs[i]), reverse=True)
+
+    for st in range(0, n, batch_seqs):
+        idx = orden[st:st + batch_seqs]
+        chunk = [seqs[i] for i in idx]
+        labels = [ids[i] for i in idx]
+        _, _, toks = batch_converter(list(zip(labels, chunk)))
+        toks = toks.to(dev)
+        reps = model(toks, repr_layers=[REPR_LAYER])["representations"][REPR_LAYER].to("cpu")
+        for k, (i, s) in enumerate(zip(idx, chunk)):
+            tr = min(SEQ_LENGTH, len(s))
+            # ---- receta EXACTA: descarta BOS, excluye EOS y padding ----
+            # Se escribe en la posición ORIGINAL i, no en la del lote.
+            X[i] = reps[k, 1:tr + 1].mean(0).numpy().astype("float32")
+    return X

immunoherd-0.1.1/src/herd/fasta.py

@@ -0,0 +1,51 @@
+"""
+herd/fasta.py — Lectura de secuencias (CPU).
+parse_fasta es la función original de las apps; parse_fasta_text es para la web.
+"""
+
+from typing import List, Tuple
+
+
+def parse_fasta(path: str) -> Tuple[List[str], List[str]]:
+    """Lee un fichero FASTA -> (ids, seqs). Copiado de las apps."""
+    ids, seqs, name, chunks = [], [], None, []
+    with open(path) as f:
+        for line in f:
+            line = line.rstrip()
+            if line.startswith(">"):
+                if name is not None:
+                    ids.append(name)
+                    seqs.append("".join(chunks))
+                name = line[1:].split()[0]
+                chunks = []
+            else:
+                chunks.append(line.strip())
+    if name is not None:
+        ids.append(name)
+        seqs.append("".join(chunks))
+    return ids, seqs
+
+
+def parse_fasta_text(text: str) -> Tuple[List[str], List[str]]:
+    """Igual pero desde un string. Sin '>' -> una sola secuencia 'sequence_1'."""
+    text = text.strip()
+    if not text:
+        return [], []
+    if not text.lstrip().startswith(">"):
+        return ["sequence_1"], ["".join(text.split())]
+
+    ids, seqs, name, chunks = [], [], None, []
+    for line in text.splitlines():
+        line = line.rstrip()
+        if line.startswith(">"):
+            if name is not None:
+                ids.append(name)
+                seqs.append("".join(chunks))
+            name = line[1:].split()[0]
+            chunks = []
+        else:
+            chunks.append(line.strip())
+    if name is not None:
+        ids.append(name)
+        seqs.append("".join(chunks))
+    return ids, seqs

immunoherd-0.1.1/src/herd/inference.py

@@ -0,0 +1,85 @@
+"""
+herd/inference.py — Orquestación: secuencias -> embedding -> modelo -> scores.
+
+Es el "pegamento" que une CPU (validación) y GPU (embedding) y produce la tabla
+de resultados. No contiene ciencia nueva: solo encadena los módulos.
+"""
+
+from typing import List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from . import esm, models
+from .config import THRESHOLD, LABEL_POS, LABEL_NEG, SP2ID, CORE_HOSTS
+from .validation import validate_records
+from .fasta import parse_fasta, parse_fasta_text
+
+
+def predict(
+    records: List[Tuple[str, str]],
+    host: str,
+    model: str = "integrated",
+    threshold: float = THRESHOLD,
+    device: Optional[str] = None,
+    batch_seqs: int = 8,
+) -> pd.DataFrame:
+    """
+    records : lista de (id, seq).
+    host    : especie objetivo (clave o alias).
+    model   : 'integrated' (recomendado, 15 cabezas) o 'individual' (6 core).
+
+    Devuelve un DataFrame ordenado por score descendente con columnas:
+    id, length, host, model, score, prediction, warnings.
+    Las secuencias inválidas se devuelven al final con score NaN.
+    """
+    if model not in ("integrated", "individual"):
+        raise ValueError("model must be 'integrated' or 'individual'.")
+    if model == "individual" and host not in CORE_HOSTS:
+        raise ValueError(f"'individual' is only available for the 6 core hosts: {CORE_HOSTS}")
+
+    valid, invalid = validate_records(records)
+
+    rows = []
+    if valid:
+        seqs = [r.seq for r in valid]
+        ids = [r.id for r in valid]
+        X = esm.embed_sequences(seqs, ids=ids, device=device, batch_seqs=batch_seqs)
+        if model == "integrated":
+            scores = models.score_integrated(X, host)
+        else:
+            scores = models.score_individual(X, host)
+        for r, sc in zip(valid, scores):
+            sc = float(sc)
+            rows.append({
+                "id": r.id,
+                "length": r.orig_length,
+                "host": host,
+                "model": model,
+                "score": round(sc, 4),
+                "prediction": LABEL_POS if sc >= threshold else LABEL_NEG,
+                "warnings": "; ".join(r.warnings),
+            })
+
+    for inv in invalid:
+        rows.append({
+            "id": inv.id, "length": 0, "host": host, "model": model,
+            "score": np.nan, "prediction": "ERROR", "warnings": inv.reason,
+        })
+
+    df = pd.DataFrame(rows)
+    if not df.empty:
+        df = df.sort_values("score", ascending=False, na_position="last").reset_index(drop=True)
+    return df
+
+
+def predict_fasta(path: str, host: str, **kwargs) -> pd.DataFrame:
+    """Atajo: predice directamente desde un fichero FASTA."""
+    ids, seqs = parse_fasta(path)
+    return predict(list(zip(ids, seqs)), host, **kwargs)
+
+
+def predict_text(text: str, host: str, **kwargs) -> pd.DataFrame:
+    """Atajo: predice desde texto pegado (FASTA o una secuencia cruda)."""
+    ids, seqs = parse_fasta_text(text)
+    return predict(list(zip(ids, seqs)), host, **kwargs)

immunoherd-0.1.1/src/herd/models.py

@@ -0,0 +1,94 @@
+"""
+herd/models.py — Carga de los modelos Keras y puntuación (CPU).
+
+Individual: `model.predict(X)` -> sigmoide única.
+Integrado:  se reconstruye `heads_model` apuntando a la capa 'species_heads'
+            y se toma la columna del host. Esto reproduce EXACTAMENTE el truco
+            del código original, que evita las capas Lambda ('mask'/'pick')
+            que se rompen al recargar el modelo.
+
+La normalización va DENTRO del .keras (capa Normalization adaptada en
+entrenamiento), así que se alimenta el embedding crudo (N, 1280) sin escalar.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+import tensorflow as tf
+
+from .config import (
+    MODELS_ROOT, INDIVIDUAL_DIR, INTEGRATED_FILE,
+    SP2ID, CORE_HOSTS, HOST_ALIASES, SPECIES_ORDER,
+)
+
+_individual_cache = {}   # host -> keras.Model
+_integrated_cache = {}   # 'heads' -> keras.Model (salida species_heads)
+
+
+# --- Resolución de nombres de host ------------------------------------------
+def resolve_host(host: str) -> Optional[str]:
+    """Normaliza un nombre de host al de una cabeza del modelo, o None."""
+    if host is None:
+        return None
+    h = str(host).strip()
+    if h in SP2ID:
+        return h
+    if h in HOST_ALIASES and HOST_ALIASES[h] in SP2ID:
+        return HOST_ALIASES[h]
+    genus = h.lower().split("_")[0]          # match laxo por género
+    for sp in SP2ID:
+        if sp.lower().startswith(genus):
+            return sp
+    return None
+
+
+# --- Rutas de los pesos ------------------------------------------------------
+def individual_path(host: str) -> Path:
+    if host not in CORE_HOSTS:
+        raise ValueError(f"No individual model for '{host}'. Core hosts: {CORE_HOSTS}")
+    return MODELS_ROOT / INDIVIDUAL_DIR / f"{host}.keras"
+
+
+def integrated_path() -> Path:
+    return MODELS_ROOT / INTEGRATED_FILE
+
+
+# --- Carga -------------------------------------------------------------------
+def load_individual(host: str):
+    """Carga (y cachea) el modelo individual de un host core."""
+    if host not in _individual_cache:
+        path = individual_path(host)
+        _individual_cache[host] = tf.keras.models.load_model(str(path), compile=False)
+    return _individual_cache[host]
+
+
+def load_integrated_heads():
+    """
+    Carga el modelo integrado y devuelve un sub-modelo cuya salida es la capa
+    'species_heads' (N, 15 sigmoides). Cachea el resultado.
+    """
+    if "heads" not in _integrated_cache:
+        path = str(integrated_path())
+        try:
+            integ = tf.keras.models.load_model(path, compile=False, safe_mode=False)
+        except TypeError:  # versiones de Keras sin 'safe_mode'
+            integ = tf.keras.models.load_model(path, compile=False)
+        heads = tf.keras.Model(integ.inputs[0], integ.get_layer("species_heads").output)
+        _integrated_cache["heads"] = heads
+    return _integrated_cache["heads"]
+
+
+# --- Puntuación --------------------------------------------------------------
+def score_individual(X: np.ndarray, host: str) -> np.ndarray:
+    model = load_individual(host)
+    return model.predict(X, verbose=0).ravel()
+
+
+def score_integrated(X: np.ndarray, host: str) -> np.ndarray:
+    sp = resolve_host(host)
+    if sp is None:
+        raise ValueError(f"Host '{host}' is not in the model. Available: {SPECIES_ORDER}")
+    heads = load_integrated_heads()
+    H = heads.predict(X, verbose=0)          # (N, 15)
+    return H[:, SP2ID[sp]]

immunoherd-0.1.1/src/herd/validation.py

@@ -0,0 +1,78 @@
+"""
+herd/validation.py — Limpieza y validación de secuencias (CPU).
+
+Se ejecuta ANTES de tocar la GPU. Saca a su propia función la limpieza que
+en el código original vivía dentro de `embed_sequences`, para poder:
+  - reportar problemas por secuencia sin reventar el lote entero (guía §23),
+  - dejar que `esm.embed_sequences` reciba secuencias ya limpias (guía §5, §13).
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import List, Tuple
+
+from .config import VALID_AA, UNKNOWN_AA, SEQ_LENGTH
+
+# Precompila la regex una vez: cualquier carácter fuera de los 20 canónicos.
+_NON_CANONICAL = re.compile(f"[^{VALID_AA}]")
+
+
+def clean_sequence(seq: str) -> Tuple[str, List[str]]:
+    """
+    Aplica la receta EXACTA del código original:
+        residuos no canónicos -> 'X', y truncado a SEQ_LENGTH.
+    Devuelve (secuencia_limpia, avisos).
+    """
+    warnings: List[str] = []
+    up = seq.upper()
+
+    n_bad = len(_NON_CANONICAL.findall(up))
+    if n_bad:
+        warnings.append(f"{n_bad} non-canonical residue(s) -> '{UNKNOWN_AA}'")
+    clean = _NON_CANONICAL.sub(UNKNOWN_AA, up)
+
+    if len(clean) > SEQ_LENGTH:
+        warnings.append(f"truncated from {len(clean)} to {SEQ_LENGTH} residues")
+        clean = clean[:SEQ_LENGTH]
+
+    return clean, warnings
+
+
+@dataclass
+class ValidatedRecord:
+    id: str
+    seq: str                       # secuencia limpia (lista para ESM)
+    orig_length: int
+    warnings: List[str] = field(default_factory=list)
+
+
+@dataclass
+class InvalidRecord:
+    id: str
+    reason: str
+
+
+def validate_records(
+    records: List[Tuple[str, str]]
+) -> Tuple[List[ValidatedRecord], List[InvalidRecord]]:
+    """
+    Valida y limpia una lista de (id, seq).
+    Devuelve (validas, invalidas). Las inválidas se reportan aparte en vez
+    de abortar todo el trabajo (guía §23). No se impone longitud mínima:
+    en el paper el mínimo de 40 era un filtro de dataset, no de inferencia.
+    """
+    valid: List[ValidatedRecord] = []
+    invalid: List[InvalidRecord] = []
+
+    for sid, seq in records:
+        raw = (seq or "").strip()
+        if not raw:
+            invalid.append(InvalidRecord(sid, "empty sequence"))
+            continue
+        clean, warns = clean_sequence(raw)
+        if not clean:
+            invalid.append(InvalidRecord(sid, "no valid residues"))
+            continue
+        valid.append(ValidatedRecord(id=sid, seq=clean, orig_length=len(raw), warnings=warns))
+
+    return valid, invalid

immunoherd-0.1.1/src/immunoHERD.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+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.

immunoherd-0.1.1/src/immunoHERD.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+src/herd/__init__.py
+src/herd/cli.py
+src/herd/config.py
+src/herd/esm.py
+src/herd/fasta.py
+src/herd/inference.py
+src/herd/models.py
+src/herd/validation.py
+src/herd/models/integrated.keras
+src/herd/models/individual/Bos_taurus.keras
+src/herd/models/individual/Canis_sp.keras
+src/herd/models/individual/Equus_caballus.keras
+src/herd/models/individual/Gallus_gallus.keras
+src/herd/models/individual/Homo_sapiens.keras
+src/herd/models/individual/Sus_scrofa.keras
+src/immunoHERD.egg-info/PKG-INFO
+src/immunoHERD.egg-info/SOURCES.txt
+src/immunoHERD.egg-info/dependency_links.txt
+src/immunoHERD.egg-info/entry_points.txt
+src/immunoHERD.egg-info/requires.txt
+src/immunoHERD.egg-info/top_level.txt
+tests/test_basics.py

immunoherd-0.1.1/src/immunoHERD.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

immunoherd-0.1.1/src/immunoHERD.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+herd = herd.cli:main

immunoherd-0.1.1/src/immunoHERD.egg-info/requires.txt

@@ -0,0 +1,6 @@
+fair-esm
+torch
+tensorflow>=2.16
+keras<4,>=3.13
+numpy
+pandas

immunoherd-0.1.1/src/immunoHERD.egg-info/top_level.txt

@@ -0,0 +1 @@
+herd

immunoherd-0.1.1/tests/test_basics.py

@@ -0,0 +1,56 @@
+"""
+Pruebas mínimas del paquete instalado.
+
+Con el layout src/ estas pruebas NO pueden importar la carpeta del repositorio:
+importan siempre `herd` instalado, que es justo lo que se quiere comprobar.
+
+    pip install -e .
+    pytest
+"""
+
+from herd.validation import clean_sequence, validate_records
+from herd.fasta import parse_fasta_text
+from herd.config import SEQ_LENGTH, CORE_HOSTS, SPECIES_ORDER
+from herd.models import resolve_host
+
+
+def test_non_canonical_residues_become_x():
+    clean, warnings = clean_sequence("MKVBBBZZZ")
+    assert "B" not in clean and "Z" not in clean
+    assert clean.count("X") == 6
+    assert "non-canonical" in warnings[0]
+
+
+def test_truncation_to_1022():
+    clean, warnings = clean_sequence("M" * 1315)
+    assert len(clean) == SEQ_LENGTH
+    assert warnings == [f"truncated from 1315 to {SEQ_LENGTH} residues"]
+
+
+def test_empty_sequence_is_invalid():
+    valid, invalid = validate_records([("a", "")])
+    assert valid == []
+    assert invalid[0].reason == "empty sequence"
+
+
+def test_fasta_text_multiline_is_joined():
+    ids, seqs = parse_fasta_text(">p1\nMKV\nLAA\n>p2\nMSE")
+    assert ids == ["p1", "p2"]
+    assert seqs == ["MKVLAA", "MSE"]
+
+
+def test_bare_sequence_without_header():
+    ids, seqs = parse_fasta_text("MKVLAA")
+    assert ids == ["sequence_1"]
+    assert seqs == ["MKVLAA"]
+
+
+def test_host_aliases_resolve():
+    assert resolve_host("Canis_familiaris") == "Canis_sp"
+    assert resolve_host("Homo") == "Homo_sapiens"
+    assert resolve_host("Tyrannosaurus") is None
+
+
+def test_core_hosts_are_a_subset_of_the_heads():
+    assert set(CORE_HOSTS) <= set(SPECIES_ORDER)
+    assert len(SPECIES_ORDER) == 15