esm3di 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. esm3di-0.2.0/LICENSE +21 -0
  2. esm3di-0.2.0/PKG-INFO +385 -0
  3. esm3di-0.2.0/README.md +327 -0
  4. esm3di-0.2.0/pyproject.toml +108 -0
  5. esm3di-0.2.0/setup.cfg +4 -0
  6. esm3di-0.2.0/setup.py +6 -0
  7. esm3di-0.2.0/src/esm3di/ESM3di_model.py +4 -0
  8. esm3di-0.2.0/src/esm3di/__init__.py +40 -0
  9. esm3di-0.2.0/src/esm3di/_core/__init__.py +1 -0
  10. esm3di-0.2.0/src/esm3di/_core/checkpoints.py +529 -0
  11. esm3di-0.2.0/src/esm3di/_core/model.py +369 -0
  12. esm3di-0.2.0/src/esm3di/checkpoints.py +4 -0
  13. esm3di-0.2.0/src/esm3di/cli.py +35 -0
  14. esm3di-0.2.0/src/esm3di/cutting_cli.py +9 -0
  15. esm3di-0.2.0/src/esm3di/fastas2foldseekdb.py +90 -0
  16. esm3di-0.2.0/src/esm3di/foldseek_db.py +6 -0
  17. esm3di-0.2.0/src/esm3di/inference/__init__.py +15 -0
  18. esm3di-0.2.0/src/esm3di/inference/__main__.py +3 -0
  19. esm3di-0.2.0/src/esm3di/inference/checkpoint_predictor.py +335 -0
  20. esm3di-0.2.0/src/esm3di/inference/cli.py +437 -0
  21. esm3di-0.2.0/src/esm3di/inference/cutting.py +460 -0
  22. esm3di-0.2.0/src/esm3di/inference/cutting_bundle.py +169 -0
  23. esm3di-0.2.0/src/esm3di/inference/foldseek_db.py +66 -0
  24. esm3di-0.2.0/src/esm3di/inference/io.py +237 -0
  25. esm3di-0.2.0/src/esm3di/inference/model.py +18 -0
  26. esm3di-0.2.0/src/esm3di/inference/phylogeny.py +87 -0
  27. esm3di-0.2.0/src/esm3di/inference/predictor.py +372 -0
  28. esm3di-0.2.0/src/esm3di/inference/preprocessing.py +42 -0
  29. esm3di-0.2.0/src/esm3di/inference/windowing.py +81 -0
  30. esm3di-0.2.0/src/esm3di/io.py +6 -0
  31. esm3di-0.2.0/src/esm3di/model.py +4 -0
  32. esm3di-0.2.0/src/esm3di/predict.py +9 -0
  33. esm3di-0.2.0/src/esm3di/preprocessing.py +6 -0
  34. esm3di-0.2.0/src/esm3di/workflow/Snakefile +48 -0
  35. esm3di-0.2.0/src/esm3di/workflow/__init__.py +0 -0
  36. esm3di-0.2.0/src/esm3di/workflow/config.yaml +14 -0
  37. esm3di-0.2.0/src/esm3di/workflow/envs/foldtree.yaml +30 -0
  38. esm3di-0.2.0/src/esm3di/workflow/envs/prostt5_env.yaml +7 -0
  39. esm3di-0.2.0/src/esm3di/workflow/madroot/mad.py +678 -0
  40. esm3di-0.2.0/src/esm3di/workflow/rules/database_ops.smk +77 -0
  41. esm3di-0.2.0/src/esm3di/workflow/rules/homolog_grouping.smk +2 -0
  42. esm3di-0.2.0/src/esm3di/workflow/rules/prostt5_db.smk +72 -0
  43. esm3di-0.2.0/src/esm3di/workflow/rules/tree_building.smk +87 -0
  44. esm3di-0.2.0/src/esm3di/workflow/scripts/3di2foldseekdb.py +139 -0
  45. esm3di-0.2.0/src/esm3di/workflow/scripts/foldseek2tree.py +294 -0
  46. esm3di-0.2.0/src/esm3di/workflow/scripts/foldseekres2distmat_simple.py +53 -0
  47. esm3di-0.2.0/src/esm3di/workflow/scripts/postprocess.py +19 -0
  48. esm3di-0.2.0/src/esm3di/workflow/scripts/process_madroot.py +17 -0
  49. esm3di-0.2.0/src/esm3di/workflow/scripts/run_madroot.py +80 -0
  50. esm3di-0.2.0/src/esm3di/workflow/scripts/tipnames.py +38 -0
  51. esm3di-0.2.0/src/esm3di.egg-info/PKG-INFO +385 -0
  52. esm3di-0.2.0/src/esm3di.egg-info/SOURCES.txt +67 -0
  53. esm3di-0.2.0/src/esm3di.egg-info/dependency_links.txt +1 -0
  54. esm3di-0.2.0/src/esm3di.egg-info/entry_points.txt +6 -0
  55. esm3di-0.2.0/src/esm3di.egg-info/requires.txt +38 -0
  56. esm3di-0.2.0/src/esm3di.egg-info/top_level.txt +1 -0
  57. esm3di-0.2.0/tests/test_cli.py +52 -0
  58. esm3di-0.2.0/tests/test_cutting_bundle.py +127 -0
  59. esm3di-0.2.0/tests/test_cutting_cli.py +88 -0
  60. esm3di-0.2.0/tests/test_harmonization.py +149 -0
  61. esm3di-0.2.0/tests/test_inference.py +52 -0
  62. esm3di-0.2.0/tests/test_io.py +54 -0
  63. esm3di-0.2.0/tests/test_long_sequences.py +195 -0
  64. esm3di-0.2.0/tests/test_model.py +51 -0
  65. esm3di-0.2.0/tests/test_phylogeny.py +138 -0
  66. esm3di-0.2.0/tests/test_phylogeny_scripts.py +87 -0
  67. esm3di-0.2.0/tests/test_polyprotein_cut_training.py +30 -0
  68. esm3di-0.2.0/tests/test_preprocessing.py +34 -0
  69. esm3di-0.2.0/tests/test_workflow_tipnames.py +24 -0
esm3di-0.2.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ESM3di Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
esm3di-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,385 @@
1
+ Metadata-Version: 2.4
2
+ Name: esm3di
3
+ Version: 0.2.0
4
+ Summary: Lightweight ESM3Di inference, cleavage prediction, and FoldSeek database tools
5
+ Author: Finn Weikert, Philippe Le Mercier, Christophe Dessimoz
6
+ Author-email: David Moi <dmoi@unil.ch>, Dongwook Kim <dongwook.kim@unil.ch>
7
+ Maintainer-email: David Moi <dmoi@unil.ch>, Dongwook Kim <dongwook.kim@unil.ch>
8
+ License: MIT
9
+ Project-URL: Homepage, https://github.com/DessimozLab/ESM3di
10
+ Project-URL: Repository, https://github.com/DessimozLab/ESM3di
11
+ Project-URL: Issues, https://github.com/DessimozLab/ESM3di/issues
12
+ Project-URL: Documentation, https://github.com/DessimozLab/ESM3di#readme
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Requires-Python: >=3.10
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ Requires-Dist: torch>=2.7.0
25
+ Requires-Dist: transformers<4.49.0,>=4.45.0
26
+ Requires-Dist: peft<0.14.0,>=0.12.0
27
+ Requires-Dist: accelerate>=1.0.0
28
+ Requires-Dist: safetensors>=0.4.0
29
+ Requires-Dist: tokenizers>=0.20.0
30
+ Requires-Dist: numpy>=1.24.0
31
+ Requires-Dist: biopython>=1.80
32
+ Requires-Dist: tqdm>=4.65.0
33
+ Requires-Dist: huggingface-hub>=0.20.0
34
+ Requires-Dist: einops>=0.7.0
35
+ Provides-Extra: training
36
+ Requires-Dist: esm3di-training==0.2.0; extra == "training"
37
+ Provides-Extra: workflow
38
+ Requires-Dist: snakemake>=7.8.0; extra == "workflow"
39
+ Requires-Dist: pulp<2.8.0; extra == "workflow"
40
+ Requires-Dist: numpy>=1.24.0; extra == "workflow"
41
+ Requires-Dist: scipy>=1.10.0; extra == "workflow"
42
+ Requires-Dist: pandas>=2.0.0; extra == "workflow"
43
+ Requires-Dist: pyyaml>=6.0; extra == "workflow"
44
+ Provides-Extra: gpu
45
+ Requires-Dist: bitsandbytes>=0.42.0; extra == "gpu"
46
+ Requires-Dist: triton>=2.1.0; extra == "gpu"
47
+ Provides-Extra: dev
48
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
49
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
50
+ Requires-Dist: black>=23.0.0; extra == "dev"
51
+ Requires-Dist: isort>=5.12.0; extra == "dev"
52
+ Requires-Dist: flake8>=6.0.0; extra == "dev"
53
+ Requires-Dist: ipython>=8.0.0; extra == "dev"
54
+ Requires-Dist: jupyter>=1.0.0; extra == "dev"
55
+ Provides-Extra: all
56
+ Requires-Dist: esm3di[dev,gpu,training,workflow]; extra == "all"
57
+ Dynamic: license-file
58
+
59
+ # ESM3Di
60
+
61
+ <p align="center"><img src="logo_ESM3Di_transparent.png" alt="ESM3Di logo: viral protLLM" width="50%"></p>
62
+
63
+ Predict per-residue **3Di structural tokens** from amino-acid sequences, build
64
+ FoldSeek search databases, and predict polyprotein cleavage sites.
65
+ Pretrained weights are downloaded automatically from
66
+ [Hugging Face](https://huggingface.co/cactuskid13/ESM3di_Small_MLM_3di);
67
+ you do not need structures or training checkpoints to run predictions.
68
+
69
+ **Scope:** ESM3Di is an experimental resource for viral proteins and curated,
70
+ specialized structure collections. It is not a general-purpose replacement
71
+ for ProstT5. Validate predictions on your target dataset.
72
+
73
+ ## Installation
74
+
75
+ ```bash
76
+ pip install esm3di
77
+ ```
78
+
79
+ Use Python 3.10–3.12. CPU inference works; compatible NVIDIA GPUs are used
80
+ automatically. The first prediction needs internet access to download weights.
81
+
82
+ That gives you 3Di prediction, cleavage prediction and FoldSeek database
83
+ building. The rest is optional:
84
+
85
+ | You also want | Install |
86
+ |---|---|
87
+ | Alignments and trees | `conda install -c conda-forge -c bioconda foldseek foldmason=4.dd3c235 'fasttree>=2.2.0'` |
88
+ | Training on your own data | `pip install 'esm3di[training]'` (adds the `esm3di-learn`, `esm3di-prepare`, `esm3di-train-mlm`, `esm3di-train` commands) |
89
+ | The Snakemake FoldTree workflow | `pip install 'esm3di[workflow]'`, plus Conda for its external tools |
90
+
91
+ A Conda environment with FoldSeek, FoldMason and FastTree already in it:
92
+
93
+ ```bash
94
+ conda env create -f environment_inference.yml # from a clone; see below
95
+ conda activate esm3di_inference
96
+ ```
97
+
98
+ [environment.yml](environment.yml) adds the training stack, and Blackwell GPU
99
+ users can use [environment_blackwell.yml](environment_blackwell.yml). The Conda
100
+ environments use PyTorch with CUDA 12.8; a compatible NVIDIA driver is required
101
+ (Linux driver 570 or newer recommended). Keep the installed `transformers` and
102
+ `peft` versions within the supplied dependency ranges.
103
+
104
+ <details>
105
+ <summary><b>Developing ESM3Di, or reproducing the paper</b></summary>
106
+
107
+ ```bash
108
+ git clone https://github.com/DessimozLab/ESM3di.git
109
+ cd ESM3di
110
+ pip install -e '.[dev]' -e ./training
111
+ ```
112
+
113
+ You only need a clone to change the code or rerun the analyses. It also carries
114
+ the benchmarks, paper figures and experiment notebooks, so it is a few hundred
115
+ megabytes; the data behind the figures is deposited separately at
116
+ [doi.org/10.5281/zenodo.24082798](https://doi.org/10.5281/zenodo.24082798).
117
+ </details>
118
+
119
+ ## Predict 3Di or build a FoldSeek database
120
+
121
+ ```bash
122
+ # Amino-acid FASTA → predicted 3Di FASTA
123
+ esm3di-infer predict \
124
+ --input-fasta proteins.fasta \
125
+ --output-fasta outputs/proteins_3di.fasta
126
+
127
+ # Amino-acid FASTA → FoldSeek database
128
+ esm3di-infer foldseek-db \
129
+ --input-fasta proteins.fasta \
130
+ --output-db dbs/proteins
131
+
132
+ # Search the resulting database
133
+ foldseek easy-search query_db dbs/proteins hits.m8 tmp --exhaustive-search 1
134
+ ```
135
+
136
+ The default model is
137
+ [`cactuskid13/ESM3di_Small_MLM_3di`](https://huggingface.co/cactuskid13/ESM3di_Small_MLM_3di).
138
+ Use `--model-ckpt` to select another compatible Hub repository or your own
139
+ supervised ESM++ LoRA/CNN `.pt` checkpoint. An MLM-only directory is not a
140
+ trained 3Di predictor.
141
+
142
+ Use `--num-gpus 1` to restrict inference to one GPU and `--batch-size 8` to set
143
+ the batch size per device. Keep all database files sharing the output prefix
144
+ together. FoldSeek must be installed for searches, but database writing itself
145
+ does not need the FoldSeek executable.
146
+
147
+ **Long sequences are supported by default, including with Hugging Face models.**
148
+ Prediction, confidence output, FoldSeek database generation and cutter embeddings
149
+ use overlapping windows and retain every residue. The standard inference window
150
+ is up to 1,024 tokens including special tokens (normally 1,022 residues), reduced
151
+ if the tokenizer has a smaller limit. Windows overlap by 128 residues (less for
152
+ very small contexts); 3Di probabilities or cutter embeddings are averaged in
153
+ overlaps. Short sequences use a single window. Windowing preserves length, but
154
+ does not provide interactions between residues in distant windows.
155
+
156
+ **Verified with real model weights:** the default Hugging Face model, a legacy
157
+ supervised `.pt` checkpoint and a corrected MLM-to-3Di `.pt` checkpoint each
158
+ produced exactly one 3Di token per input residue for sequences of 22, 1,022,
159
+ 1,023 and 2,051 residues. Predictions matched the existing standalone windowed
160
+ predictor, and short-sequence predictions were unchanged. Confidence output and
161
+ paired AA/3Di FoldSeek records also retained every residue. The Hugging Face
162
+ cutter produced probabilities for all 2,051 residues of a test polyprotein,
163
+ and concatenating its predicted products reconstructed the complete input.
164
+ These checks verify output completeness and compatibility, not prediction
165
+ accuracy or unlimited sequence length; available memory still limits inference.
166
+ Existing model weights and checkpoints were not modified.
167
+
168
+ ### Prediction options
169
+
170
+ | Option | Applies to | Behavior |
171
+ |---|---|---|
172
+ | `--model-ckpt REPO_OR_PATH` | `predict`, `foldseek-db`, `perplexity` | Select compatible Hub weights, a local adapter/CNN directory, or a supervised `.pt` checkpoint |
173
+ | `--batch-size N` | `predict`, `foldseek-db`, `perplexity` | Maximum windows per model batch (default: 8); reduce if GPU memory is limited |
174
+ | `--num-gpus N` | `predict`, `foldseek-db` | Number of GPUs (default: all available; CPU when none are available) |
175
+ | `--no-sort-by-length` | `predict`, `foldseek-db` | Disable length-sorted batching; output record order is preserved either way |
176
+ | `--truncate` | `predict`, `perplexity` only | **Opt in** to discarding residues after the first model window; never enabled by default |
177
+ | `-v 0` through `-v 3` | All inference commands | Quiet through informational logging (default: 3) |
178
+
179
+ Truncated predictions are incomplete and must not be paired with full-length AA
180
+ sequences for a FoldSeek database. Accordingly, `foldseek-db` and the cutter do
181
+ not offer truncation. To deliberately generate only first-window predictions:
182
+
183
+ ```bash
184
+ esm3di-infer predict --input-fasta proteins.fasta \
185
+ --output-fasta outputs/first_window_only.fasta --truncate
186
+ ```
187
+
188
+ For custom supervised checkpoints, the standalone predictor also supports
189
+ explicit window sizes and overlap, plus per-residue confidence digits:
190
+
191
+ ```bash
192
+ esm3di-predict --checkpoint runs/my_model/3di/best.pt \
193
+ -i proteins.fasta -o proteins_3di.fasta \
194
+ --window 1022 --overlap 128 --confidence-output confidence.fasta
195
+ ```
196
+
197
+ That interface uses the checkpoint's training sequence length by default and
198
+ does not truncate. Use `esm3di-infer perplexity --input-fasta proteins.fasta
199
+ --output-tsv confidence.tsv` for full-length entropy-derived confidence from
200
+ the default Hub model (lower perplexity means a more concentrated prediction).
201
+
202
+ See the [database wrapper guide](fastas2foldseekdb_README.md) for working with
203
+ precomputed AA/3Di FASTAs.
204
+
205
+ ### Other interfaces
206
+
207
+ - **Polyprotein cutter:** `esm3di-infer cut` downloads the matching Hugging Face
208
+ weights and writes cleaved-product FASTA and cut-information CSVs.
209
+ See [cleavage prediction](#polyprotein-cleavage-prediction) below.
210
+ - **Alignment and trees:** `esm3di-infer foldmason-fasttree` builds an alignment
211
+ and an approximate tree from a FoldSeek database.
212
+ - **Prediction confidence:** `esm3di-infer perplexity --help`.
213
+ - **Training:** `esm3di-learn` provides `prepare`, `mlm`, `train` and `pipeline`.
214
+ - **FoldTree workflow:** `esm3di-infer foldtree --help`; requires
215
+ `pip install 'esm3di[workflow]'` and Conda for its external tools.
216
+
217
+ ## Polyprotein cleavage prediction
218
+
219
+ ```bash
220
+ esm3di-infer cut \
221
+ --cutter-model cactuskid13/ESM3di_Small_MLM_3di \
222
+ --input-fasta polyproteins.fasta \
223
+ --output-prefix outputs/polyproteins
224
+ ```
225
+
226
+ This downloads both cut-site classifiers and their matching embedding model
227
+ from Hugging Face. **No local `.pt` file is required.** Downloaded weights are
228
+ cached for subsequent runs.
229
+ Long polyproteins are embedded with overlapping windows without truncation;
230
+ the cut-site classifiers then process the complete embedding sequence.
231
+
232
+ By default, the command writes:
233
+
234
+ | Output | Contents |
235
+ |---|---|
236
+ | `polyproteins_residue_predictions.csv` | Per-residue probabilities and cleavage calls |
237
+ | `polyproteins_sequence_summary.csv` | Cut positions and product counts per sequence |
238
+ | `polyproteins_cleaved_products.fasta` | Predicted cleaved products |
239
+
240
+ Use `--output-format fasta`, `csv`, or `both` (default). Positions are
241
+ **1-based and cut after the indicated residue**. The default is an
242
+ FFN/transformer ensemble with probability cutoff `0.5`; change it with
243
+ `--cutoff`, or select one head with `--classifier ffn` or `transformer`.
244
+ Use `--device cpu` or `cuda` and `--batch-size` as needed.
245
+ Existing files with the same output prefix are overwritten.
246
+
247
+ For reproducibility, `--cutter-revision` pins the cutter's Hub commit.
248
+ The matching embedding model is already pinned in its configuration.
249
+ `esm3di-cut` is an equivalent standalone command.
250
+
251
+ **Interpretation:** these classifiers have limited held-out-group performance.
252
+ A predicted cut is not experimental evidence of biological cleavage.
253
+ See [cut-site methods and validation](experiments/analyses/polyprotein_cut/README.md).
254
+
255
+ ## Align sequences and infer a tree
256
+
257
+ FoldMason and FastTree are included in the Conda environments. To install them
258
+ separately:
259
+
260
+ ```bash
261
+ conda install -c conda-forge -c bioconda foldmason=4.dd3c235 'fasttree>=2.2.0'
262
+
263
+ esm3di-infer foldmason-fasttree --input-db dbs/proteins \
264
+ --output-dir results/proteins_tree --threads 8
265
+ ```
266
+
267
+ The output includes AA and 3Di alignments, a guide tree, `tree.nwk`, and logs.
268
+ Use a new output directory for each run; existing results are not overwritten.
269
+
270
+ FoldMason uses `structuremsa --fast 1 --refine-iters 0`. FastTree uses the
271
+ **amino-acid alignment**, with `-fastest -noml -spr 0 -nosupport`: approximate
272
+ neighbor joining and minimum-evolution NNI, not maximum-likelihood refinement.
273
+ The tree is unrooted and has no support values. See the
274
+ [tree-building methods](experiments/analyses/phylogeny/metagenomic_trees/README.md) for limitations.
275
+
276
+ ## Train on your own sequences and structures
277
+
278
+ Install the training component first:
279
+
280
+ ```bash
281
+ pip install 'esm3di[training]'
282
+ ```
283
+
284
+ The supported recipe uses **ESM++**, unsupervised MLM fine-tuning, then
285
+ supervised 3Di training with LoRA and a CNN head. FoldSeek must be on `PATH`
286
+ to extract labels from structures, or set `FOLDSEEK_BIN`.
287
+
288
+ ```bash
289
+ esm3di-learn pipeline \
290
+ --structures structures/ \
291
+ --sequences viral_proteins.fasta \
292
+ --init-from Synthyra/ESMplusplus_small \
293
+ --out-dir runs/my_model
294
+ ```
295
+
296
+ This prepares paired training data, trains the MLM, and writes the supervised
297
+ model to `runs/my_model/3di/best.pt`.
298
+
299
+ | Starting material | Pipeline options |
300
+ |---|---|
301
+ | Structures plus additional sequences | `--structures structures/ --sequences proteins.fasta` |
302
+ | Structures only, including MLM | `--structures structures/ --mlm-on-structure-sequences` |
303
+ | Structures only, without MLM | `--structures structures/` |
304
+ | Previously prepared data | `--data-dir data/` instead of `--structures` |
305
+ | Existing MLM checkpoint | `--init-from runs/mlm/best` without `--sequences` |
306
+ | Existing supervised checkpoint | `--init-from model.pt` without a new MLM stage |
307
+
308
+ Use a new output directory for a fresh run. To continue an interrupted pipeline,
309
+ repeat the command with `--resume`.
310
+
311
+ ### Run stages separately
312
+
313
+ ```bash
314
+ esm3di-learn prepare --structures structures/ --out-dir data --cluster-split
315
+
316
+ esm3di-learn mlm --input-fasta data/train_aa.fasta extra_sequences.fasta \
317
+ --val-fasta data/val_aa.fasta --model-name Synthyra/ESMplusplus_small \
318
+ --output-dir runs/mlm --epochs 3 --batch-size 4
319
+
320
+ esm3di-learn train --data-dir data --init-from runs/mlm/best \
321
+ --out-dir runs/3di --epochs 5 --batch-size 4
322
+ ```
323
+
324
+ Preparation accepts PDB/mmCIF files, directories, and gzip-compressed structures.
325
+ It produces paired `{all,train,val,test}_{aa,3di,plddt_bins}.fasta` files and a
326
+ manifest. `--cluster-split` keeps FoldSeek clusters in one split.
327
+ Use `--no-plddt` for experimental structures whose B-factors are not pLDDT.
328
+ Custom paired FASTAs must match in header order and residue length.
329
+
330
+ When pLDDT bins are available, keep labels unmasked and use confidence-weighted
331
+ loss. Otherwise, `X` can mark ignored labels. Training defaults use LoRA rank
332
+ 16, a two-layer CNN, AdamW and mixed precision.
333
+
334
+ Both trainers accept JSON configs; explicit CLI flags override config values.
335
+ Recipes are in [configs/](configs), including
336
+ [small MLM](configs/mlm_esmpp_small.json) and
337
+ [small supervised](configs/3di_esmpp_small_from_mlm.json).
338
+ Use `esm3di-learn mlm --help` or `esm3di-learn train --help` for options.
339
+ Individual stages support `--resume auto`; supervised `--init-from model.pt`
340
+ starts a new fine-tune rather than restoring optimizer state.
341
+
342
+ **Evidence:** MLM initialization is supported, but is not guaranteed to improve
343
+ your results. The [paired MetaVR comparison](benchmarks/quality/README.md#mlm-versus-3di-only-fine-tuning--3di_alignment_mlm_vs_3di_onlyipynb)
344
+ did not show an aggregate improvement for the evaluated epoch-5 checkpoints.
345
+ Historical checkpoints named `esm3di_from_mlm` did not receive MLM weights;
346
+ do not interpret their results as evidence of an MLM benefit.
347
+
348
+ ## Research and benchmarks
349
+
350
+ - [Benchmarks](benchmarks/README.md): 3Di accuracy on MetaVR and SCOPe40,
351
+ speed against ProstT5 and ColabFold, MLM versus 3Di-only fine-tuning, and
352
+ the brief communication figures.
353
+ - [Phylogeny experiments](experiments/analyses/phylogeny/README.md): monophyly
354
+ scoring and tree visualization.
355
+ - [Flavivirus](experiments/analyses/flavi_redo/README.md),
356
+ [Ebola](experiments/analyses/ebola_data/README.md), and
357
+ [HIV](experiments/analyses/HIV_mutations/README.md) analyses.
358
+ - [Experiment overview](experiments/README.md) and
359
+ [training reports](experiments/reports/README.md).
360
+
361
+ ## Citation
362
+
363
+ If you use ESM3Di, please cite:
364
+
365
+ - Kim, D.\*, Weikert, F.\*, Hulo, C., Le Mercier, P., Dessimoz, C. & Moi, D.
366
+ *Protein language model enables metagenomic-scale reconstruction of viral
367
+ structural evolution.* (\*equal contribution) — in preparation.
368
+ - The data behind the figures:
369
+ [doi.org/10.5281/zenodo.24082798](https://doi.org/10.5281/zenodo.24082798)
370
+
371
+ And the underlying methods:
372
+
373
+ - ESM++: [Synthyra](https://huggingface.co/Synthyra)
374
+ - LoRA: Hu et al., 2021
375
+ - FoldSeek / 3Di: van Kempen et al., 2023
376
+
377
+ ## License
378
+
379
+ MIT License. Third-party components retain their own licensing requirements.
380
+
381
+ ## Funding
382
+
383
+ Funded by NIH through the [Pathogen Data Network](https://www.pathogendatanetwork.org).
384
+
385
+ *This resource is supported by the National Institute Of Allergy And Infectious Diseases of the National Institutes of Health under Award Number U24AI183840. The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.*