---
title: ESM-3 outputs and interpretation
description: >-
  Embeddings, attention maps, contact predictions, and function annotations from
  ESM-3.
tags:
  - esm3
  - outputs
---

ESM-3 returns embedding vectors — per-residue (L x D) and pooled per-sequence (1 x D) — plus optional attention maps and metadata. What you do next depends on which you use: pooled per-sequence embeddings feed cosine-similarity comparison and clustering, per-residue embeddings feed residue-level ML features and contact prediction, so choose the output that matches your downstream task.

## Output artifacts

Each completed ESM-3 job returns embedding vectors, optional attention maps, and metadata about the computation.

## Primary output fields

| Field | Shape | Description |
|-------|-------|-------------|
| **per_residue_embeddings** | L x D | Per-residue embedding matrix (L = sequence length, D = hidden dimension) |
| **per_sequence_embedding** | 1 x D | Pooled embedding vector representing the entire protein |
| **attention_maps** | H x L x L | Multi-head attention matrices (H = number of heads, if requested) |
| **sequence** | string | Input amino acid sequence |
| **model** | string | Model variant used (esm3_sm, esm3_md, esm3_lg) |
| **embedding_dim** | integer | Embedding dimension D |

## Understanding embeddings

### Per-residue embeddings

Each amino acid position gets a D-dimensional vector that encodes:
- **Local structural context**: Secondary structure propensity, solvent accessibility, flexibility
- **Evolutionary conservation**: Positions under strong selection have distinctive embedding patterns
- **Functional information**: Active site residues, binding interfaces, and catalytic residues have characteristic signatures
- **Positional relationships**: The embedding at each position captures context from the entire sequence via self-attention

### Per-sequence embeddings

The pooled embedding reduces the full L x D matrix to a single 1 x D vector:
- **Global protein identity**: Encodes overall fold, function, and taxonomic origin
- **Similarity metric**: Cosine similarity between per-sequence embeddings correlates with functional relatedness
- **Clustering input**: Suitable for direct use in k-means, HDBSCAN, or other clustering algorithms
- **Classification features**: Input for protein family, localization, or activity classifiers

### Embedding dimensions by model

| Model | Hidden Dimension (D) | Per-Residue Shape | Per-Sequence Shape |
|-------|---------------------|-------------------|-------------------|
| Small | 1,536 | L x 1,536 | 1 x 1,536 |
| Medium | 2,560 | L x 2,560 | 1 x 2,560 |
| Large | 6,144 | L x 6,144 | 1 x 6,144 |

## Attention maps

When `return_attention` is enabled, the output includes attention weight matrices from the transformer layers.

### Interpreting attention maps

- **Residue-residue contacts**: High attention weights between distant residues often indicate physical contacts in the 3D structure
- **Functional interactions**: Attention patterns highlight residues that are functionally coupled
- **Symmetry**: Attention maps are not symmetric; attention from residue i to j may differ from j to i

### Contact prediction from attention

- Average attention across multiple heads and layers to produce a contact map, then threshold it yourself to binarize predictions
- Compare with ESMFold PAE maps for structural validation
- Contact predictions are approximate; use ESMFold for higher-accuracy structural information

## Similarity analysis

### Cosine similarity

Compute similarity between two per-sequence embeddings:
- **>0.9**: Very high similarity; likely same protein family or close homologs
- **0.7-0.9**: High similarity; functionally related proteins, possibly in the same superfamily
- **0.5-0.7**: Moderate similarity; may share functional domains or motifs
- **<0.5**: Low similarity; likely unrelated proteins

### Comparison with sequence identity

ESM-3 embeddings capture functional similarity beyond raw sequence identity:
- Proteins with 20% sequence identity may have >0.7 embedding similarity if they share a fold
- Disordered regions contribute less to embedding similarity than structured regions
- Functionally convergent proteins (similar function, different sequences) may cluster together in embedding space

## Batch output format

For multi-sequence batch jobs, results are organized per sequence:
- Each sequence gets its own embedding vectors, keyed by FASTA header
- Pairwise similarity matrix can be computed across all sequences in the batch
- Batch statistics include mean embedding magnitude and variance across sequences

## Downloading artifacts

- **NPY files**: NumPy arrays of per-residue and per-sequence embeddings (best for Python ML pipelines)
- **PT files**: PyTorch tensors (best for PyTorch-based downstream models)
- **JSON**: Metadata, per-sequence embeddings, and attention summaries
- **CSV**: Per-residue embedding values in tabular format (large files for long sequences)
- **Contact map PNG**: Visualized attention-based contact predictions (if attention maps requested)

## Canvas visualization

When an ESM-3 job completes, a result card appears on the canvas showing:
- Embedding dimension and model information
- Per-residue embedding magnitude plot (highlights important positions)
- Attention heatmap (if requested)
- Sequence length and processing time

## Quality assessment

### Embedding quality indicators

- **Embedding magnitude**: Per-residue embedding norms should vary across the sequence; uniform magnitudes may indicate a quality issue
- **Attention entropy**: Attention distributions should be focused (low entropy); uniform attention suggests insufficient model capacity for the input
- **Consistency**: Re-running with the same model and sequence should produce identical embeddings

### Common quality concerns

- **Short sequences (<30 residues)**: May produce lower-quality embeddings due to limited context
- **Repetitive sequences**: Low-complexity or repetitive regions may have similar embeddings at each position
- **Non-natural sequences**: Synthetic or heavily engineered sequences may fall outside the training distribution

## Read next