Delete files README:md with huggingface_hub
Browse files
README:md
DELETED
|
@@ -1,212 +0,0 @@
|
|
| 1 |
-
---
|
| 2 |
-
license: mit
|
| 3 |
-
base_model: facebook/esm2_t12_35M_UR50D
|
| 4 |
-
base_model_relation: finetune
|
| 5 |
-
tags:
|
| 6 |
-
- biology
|
| 7 |
-
- protein-language-model
|
| 8 |
-
- antibody
|
| 9 |
-
- sequence-editing
|
| 10 |
-
- flow-matching
|
| 11 |
-
- esm-2
|
| 12 |
-
- reproduction
|
| 13 |
-
---
|
| 14 |
-
|
| 15 |
-
# EditJumps — Edit Flows editor (`faithful-appendixa`)
|
| 16 |
-
|
| 17 |
-
**Give one antibody sequence in. Get near neighbours of it back** — a handful of insertions,
|
| 18 |
-
deletions and substitutions, placed where related natural sequences actually differ. You set
|
| 19 |
-
roughly how many edits you want.
|
| 20 |
-
|
| 21 |
-
This is a discrete **edit-flow** generative model over amino-acid sequences: an ESM-2 encoder trunk
|
| 22 |
-
with per-position edit-rate and token heads, trained on aligned antibody homolog pairs to carry one
|
| 23 |
-
natural sequence to another by insertions, deletions and substitutions.
|
| 24 |
-
|
| 25 |
-
It is an **independent reproduction** of the editor in
|
| 26 |
-
[EvoFlows](https://arxiv.org/abs/2603.11703) §3.4, built over
|
| 27 |
-
[Edit Flows](https://arxiv.org/abs/2506.09018). Neither original paper released code or weights;
|
| 28 |
-
these are not the original authors' weights, and no comparison against theirs was possible.
|
| 29 |
-
|
| 30 |
-
> **All code, documentation, training pipeline and evaluation artefacts live in the source
|
| 31 |
-
> repository — this repo holds only the weights.**
|
| 32 |
-
> 👉 **https://github.com/VisiumCH/editjumps**
|
| 33 |
-
|
| 34 |
-
## ⚠️ The two flags you cannot omit
|
| 35 |
-
|
| 36 |
-
```
|
| 37 |
-
--rate-head mlp --q-head esm_lm_head
|
| 38 |
-
```
|
| 39 |
-
|
| 40 |
-
The head parameterisation changes tentory's `params.yaml` defaults to
|
| 41 |
-
`linear` / `fresh` for local dry runs, which will **not** load this checkpoint — `load_trained`
|
| 42 |
-
inspects the state dict and raises ray. Pass both flags every time.
|
| 43 |
-
|
| 44 |
-
## Files in this repo
|
| 45 |
-
|
| 46 |
-
| path | bytes | what it is |
|
| 47 |
-
|---|---|---|
|
| 48 |
-
| `evoflows_model.pt` | 140,946,461 |runk *and* the five heads (228tensors) |
|
| 49 |
-
| `encoder/` | 133,099,700 | ESM-2 arer and trunk weights |
|
| 50 |
-
|
| 51 |
-
`EvoFlowsModel.load_trained` needs **mizer/RNG resume state
|
| 52 |
-
(`checkpoint.pt`) is deliberately not published: no evaluation path can open it, and further
|
| 53 |
-
fine-tuning of these weights is not a
|
| 54 |
-
|
| 55 |
-
## Download
|
| 56 |
-
|
| 57 |
-
```bash
|
| 58 |
-
pip install -U "huggingface_hub[cli]"
|
| 59 |
-
hf download Visium/editjumps-edit-floithful-appendixa
|
| 60 |
-
```
|
| 61 |
-
|
| 62 |
-
or from Python:
|
| 63 |
-
|
| 64 |
-
```python
|
| 65 |
-
from huggingface_hub import snapshot_
|
| 66 |
-
|
| 67 |
-
folder = snapshot_download("Visium/ed)
|
| 68 |
-
```
|
| 69 |
-
|
| 70 |
-
## Use it
|
| 71 |
-
|
| 72 |
-
Clone the source repository first — the sampler, the alignment code and the CLI all live there.
|
| 73 |
-
|
| 74 |
-
```bash
|
| 75 |
-
git clone __REPO_URL__
|
| 76 |
-
cd editjumps
|
| 77 |
-
uv sync --all-groups
|
| 78 |
-
|
| 79 |
-
uv run --group train editjumps edit \
|
| 80 |
-
--sequence QVQLVESGGGLVQPGGSLRLSCAAS \
|
| 81 |
-
--model /path/to/faithful-appendixa
|
| 82 |
-
--rate-head mlp --q-head esm_lm_head \
|
| 83 |
-
--edits 5
|
| 84 |
-
```
|
| 85 |
-
|
| 86 |
-
From Python:
|
| 87 |
-
|
| 88 |
-
```python
|
| 89 |
-
from pathlib import Path
|
| 90 |
-
from editjumps.pipeline.train.evoflows import EvoFlowsModel
|
| 91 |
-
|
| 92 |
-
model = EvoFlowsModel.load_trained(
|
| 93 |
-
Path("faithful-appendixa"),
|
| 94 |
-
rate_head="mlp",
|
| 95 |
-
q_head="esm_lm_head",
|
| 96 |
-
)
|
| 97 |
-
```
|
| 98 |
-
`--edits` is a **budget, not a guaranr checkpoint and per input and lands
|
| 99 |
-
within roughly a factor of two. The per-variant edit distance printed with each result is the truth — read that, not the budget.
|
| 100 |
-
## Model details
|
| 101 |
-
| | |
|
| 102 |
-
|---|---| | Model type | discrete flow matchingC over insert / delete / substitute) |
|
| 103 |
-
| Trunk | stock `facebook/esm2_t12_35M_UR50D` — 12 layers, hidden 480, 20 heads, vocab 33 | | Heads | 3 rate heads (`mlp`) + 2 to FiLM-conditioned on a time MLP |
|
| 104 |
-
| Parameters | 35,213,590 | | Precision | fp32 (the trainer has n
|
| 105 |
-
| Input form | joined `VH.VL` antibody chains — `.` is a real token in the ESM-2 vocabulary | | Training data | 1,660,105 unorderedS paired corpus (2,586,927 `VH.VL`sequences) | | Objective | eq. 6 Bregman rate-match path, linear `kappa` schedule |
|
| 106 |
-
| Budget | 20,000 steps × batch 16 = 320,000 pairs ≈ **19% of one epoch**. Not converged, and not claimed to be. |
|
| 107 |
-
| Optimizer | Adam, lr 1e-4, constant, no warm-up/decay/weight-decay, grad-clip 1.0, seed 0 |
|
| 108 |
-
| Best val loss | 130.48 at step 18,5
|
| 109 |
-
| Training cost | ~3 h on a single A100 (~0.54 s/step); ~5.8 h on an L4 |
|
| 110 |
-
|
| 111 |
-
The trunk is deliberately **stock** ESM-2 rather than the project's OAS-adapted trunk, because
|
| 112 |
-
EvoFlows §3.4 describes no domain-adathe encoder trunk of a pre-trained
|
| 113 |
-
ESM-2 model".
|
| 114 |
-
|
| 115 |
-
## Evaluation
|
| 116 |
-
|
| 117 |
-
EvoFlows §4.2 protocol, Ty1 seed family, disjoint frame, clock 40: 400 generated sequences against
|
| 118 |
-
a 200-sequence natural holdout.
|
| 119 |
-
|
| 120 |
-
| method | edits/seq (95% CI) | poole MMD ↓ | composition KL ↓ | covariance agr. ↑ | MIP agr. ↑ |
|
| 121 |
-
|---|---|---|---|---|---|---|
|
| 122 |
-
| **this editor** | **4.58** [3.73, 5.50] | 24.47 | 0.9839 | 0.000503 | 0.9119 | 0.8267 |
|
| 123 |
-
| evotuned PLM (§4.3) | 4.47 [4.24, 4000540 | 0.9069 | 0.8126 |
|
| 124 |
-
| evotuned PLM, forced | 5.00 [5.00, 5.00] | 25.22 | 1.0893 | 0.000531 | 0.8702 | 0.7355 |
|
| 125 |
-
| EvoDiff-MSA | 2.96 [2.67, 3.25] | 2 0.8919 | 0.7793 |
|
| 126 |
-
| random mutations (*floor*) | 4.81 | 30.01 | 1.4054 | 0.000768 | 0.8483 | 0.6617 |
|
| 127 |
-
| random homolog pairing (*ceiling*) 0.000137 | 0.9751 | 0.9422 |
|
| 128 |
-
|
| 129 |
-
**It beats the random-mutation floor ** All four of the editor's leads
|
| 130 |
-
over the unforced evotuned baseline (2 metrics × 2 families) include zero under a paired bootstrap.
|
| 131 |
-
On Ty1 MIP the editor leads by +0.014esampled difference centres on
|
| 132 |
-
**−0.0120** and puts the editor ahead in only **35%** of 2,000 paired draws.
|
| 133 |
-
|
| 134 |
-
### Read this before quoting a number
|
| 135 |
-
|
| 136 |
-
* **Indels are real**: roughly half of 400 generated variants changed length (195/400 on Ty1 at
|
| 137 |
-
4.58 mean edits; 198/400 on HER2-VHng a fixed-length masked LM cannot do.
|
| 138 |
-
* **The edits move the wrong way.** Novelty Δ — the change in distance to the nearest natural family
|
| 139 |
-
neighbour — is **+1.855** on Ty1 (+ real family member sits at a
|
| 140 |
-
*negative* Δ. Better than random mutation (+4.455), but still outward. Diversity is near natural
|
| 141 |
-
(24.47 vs 23.53), so the shortfall y. An editor whose ~4.6-residue edits
|
| 142 |
-
move novelty away from the family **has not been shown** to make the kind of small in-distribution
|
| 143 |
-
move this class of model is wanted
|
| 144 |
-
* **Spectrum MMD travels only with its template count.** On one fixed checkpoint at 300 generated
|
| 145 |
-
sequences, MMD spans **1.588 → 0.54a 2.9× swing, larger than any model
|
| 146 |
-
difference measured here. The paper never states its template count, so "our MMD is inside their
|
| 147 |
-
range" is not a result.
|
| 148 |
-
* **Covariance and MIP are within-study only.** They move more with the reference-set size than they
|
| 149 |
-
do between methods. Difference them table and against no source whose
|
| 150 |
-
reference size is unknown.
|
| 151 |
-
* **Run-to-run variation is larger thces above.** Two replicates of this
|
| 152 |
-
exact configuration differ by **0.0343** in Ty1 MIP agreement.
|
| 153 |
-
|
| 154 |
-
Full tables, per-family breakdowns and the raw JSON are in `metrics/` in the source repository.
|
| 155 |
-
|
| 156 |
-
## Intended use
|
| 157 |
-
|
| 158 |
-
Reproducing and auditing the EvoFlows §4.2 comparison, and generating homolog-like variants of a
|
| 159 |
-
template antibody sequence at a contrnstream experimental evaluation.
|
| 160 |
-
|
| 161 |
-
### Out of scope
|
| 162 |
-
|
| 163 |
-
* **It does not score its own varianttributional quality metric needs a
|
| 164 |
-
holdout of natural sequences from the input's own family, which one pasted sequence does not come
|
| 165 |
-
with. **Edit distance is not confid
|
| 166 |
-
* **It knows no downstream property.** Generation is unconditional; nothing is told what a target
|
| 167 |
-
property is at edit time. Which var assay's answer.
|
| 168 |
-
* **It is not a property filter, a design tool for wet-lab commitment, or a safety-screened model.**
|
| 169 |
-
No generated sequence here has been
|
| 170 |
-
* **Further fine-tuning is not an intended use** and no stage in the source repository supports it.
|
| 171 |
-
|
| 172 |
-
## Limitations
|
| 173 |
-
|
| 174 |
-
* **Antibody-only, paired-chain only.** The training corpus is OAS paired, so the model has never
|
| 175 |
-
seen a non-antibody protein and nevas input. Three of the EvoFlows
|
| 176 |
-
paper's six seed proteins are outside anything this model can be evidence about.
|
| 177 |
-
* **Measured corpus bias.** A cap of y shifts the training edit
|
| 178 |
-
distribution: mean 60.76 edits against an estimated 65.42 uncapped, substitution share 86.26%
|
| 179 |
-
against 84.23% — **indels under-repe**, which is the part most likely
|
| 180 |
-
to matter, since the loss is defined over alignment operations.
|
| 181 |
-
* **Known deviations from the papers.f Edit Flows eq. 9–10 is replaced
|
| 182 |
-
here by a frozen-rate Euler τ-leaping integration. The alignment scoring, the `kappa` schedule,
|
| 183 |
-
the clock formula and the evaluatioby the paper and were invented here.
|
| 184 |
-
Six of the ten quantities in the paper's only results figure cannot be recomputed from the paper
|
| 185 |
-
as written. The deviation register ows/README.md` in the source repo.
|
| 186 |
-
* **Dual-use, stated rather than assessed.** This is a generative model for antibody variable
|
| 187 |
-
domains. It proposes evolutionarilyn input the caller supplies; it has
|
| 188 |
-
no target, no affinity model and no screen. **No biosecurity evaluation has been performed.**
|
| 189 |
-
|
| 190 |
-
## Citation
|
| 191 |
-
|
| 192 |
-
Cite this reproduction via `CITATION.cff` in the source repository. The papers being reproduced:
|
| 193 |
-
|
| 194 |
-
```bibtex
|
| 195 |
-
@article{evoflows2026,
|
| 196 |
-
title = {EvoFlows: Evolutionary Edit-Based Flow-Matching for Protein Engineering},
|
| 197 |
-
author = {Deutschmann and Ferragu and Bixby},
|
| 198 |
-
year = {2026},
|
| 199 |
-
note = {arXiv:2603.11703. ICLR 20Science" workshop}
|
| 200 |
-
}
|
| 201 |
-
@article{editflows2025,
|
| 202 |
-
title = {Edit Flows: Flow Matching with Edit Operations},
|
| 203 |
-
author = {Havasi and Karrer and Gat
|
| 204 |
-
year = {2025},
|
| 205 |
-
note = {arXiv:2506.09018. NeurIPS
|
| 206 |
-
}
|
| 207 |
-
```
|
| 208 |
-
|
| 209 |
-
## License
|
| 210 |
-
|
| 211 |
-
MIT, for both the code and these weigsource repository.
|
| 212 |
-
The file is also on disk at /private/ard-koehn-Documents-GitHub-editjumps-archive/c6e44320-196c-4ea7-b21b-62cc5cdcb6fe/scratchpad/hf-editjumps/README.md, alongside the staged weights. Say the word if you want it stead.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|