feat: protlabel EAT engine + protspace transfer subcommand

CLAUDE.md

@@ -49,6 +49,7 @@ Single entry point: `protspace = protspace.cli.app:app`
 | `protspace bundle` | Combine projections + annotations → .parquetbundle |
 | `protspace serve` | Launch Dash web frontend |
 | `protspace style` | Add annotation colors/styles |
+| `protspace transfer` | Fill missing annotations from nearest reference embeddings (EAT) |
 
 ### protspace prepare Usage
 

docs/annotations.md

@@ -183,3 +183,22 @@ Per-protein predictions from the [Biocentral API](https://biocentral.rostlab.org
 | Pfam clans     | `~/.cache/protspace/pfam_clans/`  | 30 days  | Pfam family → clan mapping                        |
 
 The `default` group only requires the UniProt REST API (+ ExPASy for EC names). For `--keep-tmp` annotation caching, see [CLI Reference](cli.md#annotation-caching---keep-tmp).
+
+## Prediction Overlay Columns (EAT Transfer)
+
+Running `protspace transfer` appends two new columns to the bundle's annotations table for each requested column `COL`. The curated `COL` column is never modified.
+
+| Column | Type | Meaning |
+| --- | --- | --- |
+| `COL__pred_value` | string | The transferred label from the nearest annotated reference protein |
+| `COL__pred_confidence` | float | Reliability index in [0, 1] — 1 = identical embeddings (formula depends on `--metric`/`--k`, see below) |
+
+A protein is considered "predicted" for `COL` when `COL` is empty but `COL__pred_value` is present. Use `COL__pred_confidence` to threshold low-reliability transfers.
+
+The reliability index depends on the `--metric` and `--k` used during transfer:
+
+- **Default (`--metric euclidean`, `--k 1`):** `0.5 / (0.5 + distance)`.
+- **`--metric cosine` (`--k 1`):** `clamp(1 - cosine_distance, 0, 1)`, where `cosine_distance` is in [0, 2].
+- **`--k > 1`:** the goPredSim mean reliability — `(1/m) · Σ s(d)` of the per-neighbour similarity over the `k` nearest neighbours carrying the chosen label, with `m = min(k, number of references)`. Because of this normalization, values are **not** comparable across different `--k` settings.
+
+See [`protspace transfer`](cli.md#protspace-transfer) for usage and option details.

docs/cli.md

@@ -9,6 +9,7 @@
 | `protspace bundle`   | Combine projections + annotations into .parquetbundle |
 | `protspace serve`    | Launch interactive Dash web frontend                  |
 | `protspace style`    | Add/inspect annotation styles in existing files       |
+| `protspace transfer` | Fill missing annotations from nearest reference embeddings (EAT) |
 
 Run `protspace <command> -h` for detailed help.
 
@@ -183,6 +184,43 @@ protspace style input.parquetbundle output.parquetbundle --annotation-styles sty
 protspace style data.parquetbundle --dump-settings
 ```
 
+## `protspace transfer`
+
+Embedding Annotation Transfer (EAT): fills missing annotation values for query proteins by transferring the annotation of the nearest annotated reference protein in pLM embedding space. For each query protein that lacks a value in the requested annotation column, the command finds the closest reference (by distance in the original high-dimensional embedding space — Euclidean by default, or cosine via `--metric`, and not in the 2-D/3-D projection) and assigns that reference's label along with a reliability index adapted from goPredSim, yielding a score in [0, 1] where 1 means identical embeddings. The curated source column (`COL`) is left untouched; results are written as two new columns: `COL__pred_value` (string) and `COL__pred_confidence` (float). The method is a direct application of the approach introduced by Littmann et al., Sci Rep 2021 ([DOI 10.1038/s41598-020-80786-0](https://doi.org/10.1038/s41598-020-80786-0)) and extended by Heinzinger et al., NAR Genom Bioinform 2022 ([DOI 10.1093/nargab/lqac043](https://doi.org/10.1093/nargab/lqac043)).
+
+**Reliability index (`COL__pred_confidence`).** The exact form depends on `--metric` and `--k`:
+
+- **Default (`--metric euclidean`, `--k 1`):** `confidence = 0.5 / (0.5 + distance)` (1 at distance 0, 0.5 at distance 0.5, → 0 as distance → ∞).
+- **`--metric cosine` (`--k 1`):** `confidence = clamp(1 - cosine_distance, 0, 1)`, where `cosine_distance` is in [0, 2].
+- **`--k > 1`:** the value is the goPredSim mean reliability — `(1/m) · Σ s(d)`, the sum of the per-neighbour similarity `s(d)` (the euclidean or cosine form above) over the `k` nearest neighbours that carry the chosen label, divided by `m = min(k, number of references)`. Because of this normalization, confidence values are **not** comparable across different `--k` settings.
+
+```bash
+protspace transfer \
+  -b results.parquetbundle \
+  -e embeddings.h5:prot_t5 \
+  -t protein_category \
+  -o results.parquetbundle \
+  --query-id-prefix TRINITY_ \
+  --reference-where 'protein_category~neurotoxin'
+```
+
+**Key options:**
+
+| Flag | Description | Default |
+| ---- | ----------- | ------- |
+| `-b, --bundle` | Input `.parquetbundle` file | — |
+| `-e, --embeddings` | HDF5 embeddings file (use `:name` suffix for external files) | — |
+| `-t, --transfer` | Annotation column to transfer (repeatable) | — |
+| `-o, --output` | Output `.parquetbundle` (may overwrite input) | — |
+| `--query-id-prefix` | Restrict query proteins to IDs starting with this prefix | — |
+| `--query-where` | Filter query proteins by annotation value (`col~substr`) | — |
+| `--reference-id-prefix` | Restrict reference proteins to IDs starting with this prefix | — |
+| `--reference-where` | Filter reference proteins by annotation value (`col~substr`) | — |
+| `--k` | Number of nearest neighbours | `1` |
+| `--metric` | Distance metric (`euclidean`, `cosine`); see the reliability-index forms above | `euclidean` |
+
+Distances are computed in the original embedding space (HDF5), not in the 2-D/3-D projection. The `--metric` choice also changes how `COL__pred_confidence` is computed: euclidean uses `0.5 / (0.5 + distance)`, while cosine uses `clamp(1 - cosine_distance, 0, 1)` (see the reliability-index note above).
+
 ## Combining Multiple Inputs (`-i`)
 
 When multiple `-i` inputs are provided, behavior depends on whether they share the same embedding name: