EdouardKoehn commited on
Commit
cf3c821
·
verified ·
1 Parent(s): f946378

Delete files README:md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README:md +0 -212
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.