score_variant_effect
Read-only
Score protein substitutions with ESM-2, the zero-shot way facebookresearch/esm's own predict.py does: how much less (or more) likely the mutant residue is than the wild type at that site, under a protein language model. It ranks a saturation library without an assay — and it is a RANKING IN NATS, not a stability measurement: it carries no kcal/mol and is calibrated against nothing. THE MODEL IS DOWNLOADED ON FIRST RUN, 30 MB for the 8M export and 2.6 GB for the 650M one, then cached; a run in a browser with no network to Hugging Face will refuse rather than hang.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | which published ESM-2 ONNX export to score under. The three sizes are a download decision as much as an accuracy one, and the label says which. Values: esm2_t6_8M (ESM-2 8M · 30.3 MB), esm2_t12_35M (ESM-2 35M · 134.5 MB), esm2_t33_650M (ESM-2 650M · 2.61 GB). | esm2_t6_8M |
| _files | No | The project: record references shaped like _subject. Their records become library documents a tool names in sequences/parts/document; a trace or alignment is found by file name. | |
| protein | Yes | the protein the positions are numbered against, one letter per residue. Wire a translation, or the CDS protein the library was designed on — the positions mean nothing without it. | |
| _subject | No | The record to act on: exactly one of sequence, accession (+source), sample (an id from list_samples) or file ({name, text} or {name, base64}); record_index picks one record of several. | |
| strategy | No | how the score is computed. `masked-marginals` is ESM-1v's recommendation — one forward pass per residue, each with that site masked. `wt-marginals` is one pass over the wild type and the paper reports it as weaker. `pseudo-ppl` scores the whole mutant sequence and costs one pass per residue PER VARIANT, which is two orders of magnitude more; its number is a log-likelihood, not a ratio, and is comparable only against other variants of the same protein. Values: wt-marginals (Wild-type marginals), masked-marginals (Masked marginals), pseudo-ppl (Pseudo-perplexity). | masked-marginals |
| variants | Yes | the substitutions, in `A24D` form: wild-type residue, position, mutant residue. Every one is checked against `protein` first, because a scored substitution whose wild type does not match is a confident number about a protein nobody has. | |
| offset_idx | No | the number `position` counts from. 1 is ordinary protein numbering; set it when your variants are numbered against a mature chain or a construct that starts partway in. Advanced. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | which ESM-2 export produced these scores. Scores from two models are not comparable | |
| passes | Yes | forward passes the run cost — the price of the strategy, after the fact | |
| ranked | Yes | just the substitution notations, in the same order — the list to take forward into an order or a filter | |
| scores | Yes | every variant with its score in nats, the strategy that produced it and the forward passes it cost — MOST DAMAGING FIRST, which is the reason to rank a library at all | |
| caption | Yes | the one sentence a score may never be shown without, generated from THIS run rather than fixed: what the number means under the strategy that produced it, and what it is not | |
| strategy | Yes | which of the three strategies ran. Scores from two strategies are not comparable either, and pseudo-perplexity is not even the same quantity | |
| mostDamaging | Yes | the lowest-scoring substitution. It is the model's opinion about likelihood, not a measured loss of function, and `caption` is the sentence that says so | |
| variantCount | Yes | how many substitutions were scored | |
| leastDamaging | Yes | the highest-scoring substitution — the one the model finds most ordinary |