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.
- esm3di-0.2.0/LICENSE +21 -0
- esm3di-0.2.0/PKG-INFO +385 -0
- esm3di-0.2.0/README.md +327 -0
- esm3di-0.2.0/pyproject.toml +108 -0
- esm3di-0.2.0/setup.cfg +4 -0
- esm3di-0.2.0/setup.py +6 -0
- esm3di-0.2.0/src/esm3di/ESM3di_model.py +4 -0
- esm3di-0.2.0/src/esm3di/__init__.py +40 -0
- esm3di-0.2.0/src/esm3di/_core/__init__.py +1 -0
- esm3di-0.2.0/src/esm3di/_core/checkpoints.py +529 -0
- esm3di-0.2.0/src/esm3di/_core/model.py +369 -0
- esm3di-0.2.0/src/esm3di/checkpoints.py +4 -0
- esm3di-0.2.0/src/esm3di/cli.py +35 -0
- esm3di-0.2.0/src/esm3di/cutting_cli.py +9 -0
- esm3di-0.2.0/src/esm3di/fastas2foldseekdb.py +90 -0
- esm3di-0.2.0/src/esm3di/foldseek_db.py +6 -0
- esm3di-0.2.0/src/esm3di/inference/__init__.py +15 -0
- esm3di-0.2.0/src/esm3di/inference/__main__.py +3 -0
- esm3di-0.2.0/src/esm3di/inference/checkpoint_predictor.py +335 -0
- esm3di-0.2.0/src/esm3di/inference/cli.py +437 -0
- esm3di-0.2.0/src/esm3di/inference/cutting.py +460 -0
- esm3di-0.2.0/src/esm3di/inference/cutting_bundle.py +169 -0
- esm3di-0.2.0/src/esm3di/inference/foldseek_db.py +66 -0
- esm3di-0.2.0/src/esm3di/inference/io.py +237 -0
- esm3di-0.2.0/src/esm3di/inference/model.py +18 -0
- esm3di-0.2.0/src/esm3di/inference/phylogeny.py +87 -0
- esm3di-0.2.0/src/esm3di/inference/predictor.py +372 -0
- esm3di-0.2.0/src/esm3di/inference/preprocessing.py +42 -0
- esm3di-0.2.0/src/esm3di/inference/windowing.py +81 -0
- esm3di-0.2.0/src/esm3di/io.py +6 -0
- esm3di-0.2.0/src/esm3di/model.py +4 -0
- esm3di-0.2.0/src/esm3di/predict.py +9 -0
- esm3di-0.2.0/src/esm3di/preprocessing.py +6 -0
- esm3di-0.2.0/src/esm3di/workflow/Snakefile +48 -0
- esm3di-0.2.0/src/esm3di/workflow/__init__.py +0 -0
- esm3di-0.2.0/src/esm3di/workflow/config.yaml +14 -0
- esm3di-0.2.0/src/esm3di/workflow/envs/foldtree.yaml +30 -0
- esm3di-0.2.0/src/esm3di/workflow/envs/prostt5_env.yaml +7 -0
- esm3di-0.2.0/src/esm3di/workflow/madroot/mad.py +678 -0
- esm3di-0.2.0/src/esm3di/workflow/rules/database_ops.smk +77 -0
- esm3di-0.2.0/src/esm3di/workflow/rules/homolog_grouping.smk +2 -0
- esm3di-0.2.0/src/esm3di/workflow/rules/prostt5_db.smk +72 -0
- esm3di-0.2.0/src/esm3di/workflow/rules/tree_building.smk +87 -0
- esm3di-0.2.0/src/esm3di/workflow/scripts/3di2foldseekdb.py +139 -0
- esm3di-0.2.0/src/esm3di/workflow/scripts/foldseek2tree.py +294 -0
- esm3di-0.2.0/src/esm3di/workflow/scripts/foldseekres2distmat_simple.py +53 -0
- esm3di-0.2.0/src/esm3di/workflow/scripts/postprocess.py +19 -0
- esm3di-0.2.0/src/esm3di/workflow/scripts/process_madroot.py +17 -0
- esm3di-0.2.0/src/esm3di/workflow/scripts/run_madroot.py +80 -0
- esm3di-0.2.0/src/esm3di/workflow/scripts/tipnames.py +38 -0
- esm3di-0.2.0/src/esm3di.egg-info/PKG-INFO +385 -0
- esm3di-0.2.0/src/esm3di.egg-info/SOURCES.txt +67 -0
- esm3di-0.2.0/src/esm3di.egg-info/dependency_links.txt +1 -0
- esm3di-0.2.0/src/esm3di.egg-info/entry_points.txt +6 -0
- esm3di-0.2.0/src/esm3di.egg-info/requires.txt +38 -0
- esm3di-0.2.0/src/esm3di.egg-info/top_level.txt +1 -0
- esm3di-0.2.0/tests/test_cli.py +52 -0
- esm3di-0.2.0/tests/test_cutting_bundle.py +127 -0
- esm3di-0.2.0/tests/test_cutting_cli.py +88 -0
- esm3di-0.2.0/tests/test_harmonization.py +149 -0
- esm3di-0.2.0/tests/test_inference.py +52 -0
- esm3di-0.2.0/tests/test_io.py +54 -0
- esm3di-0.2.0/tests/test_long_sequences.py +195 -0
- esm3di-0.2.0/tests/test_model.py +51 -0
- esm3di-0.2.0/tests/test_phylogeny.py +138 -0
- esm3di-0.2.0/tests/test_phylogeny_scripts.py +87 -0
- esm3di-0.2.0/tests/test_polyprotein_cut_training.py +30 -0
- esm3di-0.2.0/tests/test_preprocessing.py +34 -0
- 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.*
|