run_esmapfold

ESMapFold is a protein folding strategy utilizing mapping between queries and a reference structure.

Instead of folding a query sequence from scratch, ESMapFold transfers backbone coordinates (N, CA, C) from an experimentally or computationally determined reference structure onto the query through a pairwise alignment, and passes them to ESM3 as a partial structure prompt. Only alignment columns whose per-position HMM quality scores (both for the query and for the reference) pass a threshold are used as constraints; the remaining positions are generated by the model. This makes the predictions of a protein family consistent with a chosen reference conformation, which is useful when the family has alternative states or when a specific template is biologically meaningful.

The package provides three command line tools:

Tool	Purpose
esmapfold_init	Create the data directory, prediction cache and download the model weights
esmapfold_run	Fold the queries of an alignment json against a reference structure
esmapfold_select	Pick, per query, the best scoring model across seeds

Predictions are cached in an SQLite database keyed by the query sequence, the extracted coordinate constraints and the generation parameters (seed, number of steps, temperature), so re-running an input only folds what is genuinely new.

Installation

Requires Python >= 3.12 and a CUDA-capable GPU.

pip install git+https://github.com/BejaLab/run_esmapfold/

Or from a local clone:

git clone https://github.com/BejaLab/run_esmapfold.git
cd run_esmapfold
pip install .

Model weights are downloaded from the HuggingFace Hub and require an access token with the ESM3 license accepted:

export HF_TOKEN=hf_...
esmapfold_init -D data

Usage

# one-off: download the weights and create the cache
esmapfold_init -D data

# fold all queries of an alignment json onto the reference of an opsintools profile
esmapfold_run -i input/alignments.json -p opsintools/canon_microb_rhodopsin \
              -O output/canon_microb_rhodopsin -D data -m esm3-open-small \
              -t 0.5 -n 8 -s 123,456 -q 9

# collapse the per-seed outputs into one best model per query
esmapfold_select -I output/canon_microb_rhodopsin -O output/select

Input

esmapfold_run expects a json array of records, each describing one query-to-reference alignment:

{
  "profile": "canon_microb_rhodopsin",
  "query": "Aylward21|GVMAG-M-3300027770-73_2:95238-95832(-)",
  "trimmed": "Aylward21|GVMAG-M-3300027770-73_2:95238-95832(-)/1-198",
  "ref": "7Z09.A",
  "domain": 1,
  "alignment": {
    "query": "----------------------------...",
    "ref": "---qaqitgrpew---------------...",
    "query_score": "...------------------------...",
    "ref_score": "...----------..........3666...."
  }
}

• query — query identifier; trimmed — the same identifier with a /<start>-<end> suffix (1-based, inclusive) delimiting the region to fold. When absent, the full sequence is folded.
• alignment.query / alignment.ref — the aligned sequences (gaps as -).
• alignment.query_score / alignment.ref_score — per-column HMM quality characters (0..9, * = 10), used by --qual to decide which columns become constraints.

The reference structure is given by --pdb, either as a path to a PDB file or as a path to an opsintools data directory containing a ref.json with an id field and a reps/<id>.pdb file. Only chain A amino acid residues of the reference are used.

Output

esmapfold_run writes one PDB file per query and seed to <output>/<seed>/<query>.pdb (the query name is percent-encoded). B-factors hold the ESM3 pLDDT values. esmapfold_select averages the pLDDT over all atoms of each model and copies (or symlinks, with -l) the highest-scoring model per query name into a flat output directory.

Tool reference

esmapfold_init

Creates <data-dir>/<model>/, initializes the prediction cache (cache.db) and downloads the model weights into the same directory (used as HF_HOME). Requires HF_TOKEN to be set.

usage: esmapfold_init [-h] -D DATA_DIR [-m {esm3-open-small}]

ESMapFold: Initialize

options:
  -h, --help            show this help message and exit
  -D DATA_DIR, --data-dir DATA_DIR
                        Base directory for data
  -m {esm3-open-small}, --model {esm3-open-small}
                        Model name (optional)

esmapfold_run

Folds the queries of the input json. One worker process is spawned per GPU; each worker loads the model once and pins itself to a single device. Results are written to the cache and to the output directory as they arrive.

usage: esmapfold_run [-h] -i INPUT -p PDB -O OUTPUT -D DATA_DIR -m
                     {esm3-open-small} [-t TEMPERATURE] [-n NUM_STEPS]
                     [-g GPUS] [-s SEEDS] [-l LOG] [-q QUAL]

ESMapFold: Run

options:
  -h, --help            show this help message and exit
  -i INPUT, --input INPUT
                        Path to input json file
  -p PDB, --pdb PDB     Path to the reference structure or opsintools data
                        directory
  -O OUTPUT, --output OUTPUT
                        Output directory
  -D DATA_DIR, --data-dir DATA_DIR
                        Data directory
  -m {esm3-open-small}, --model {esm3-open-small}
                        Model name to use for inference [esm3-open-small]
  -t TEMPERATURE, --temperature TEMPERATURE
                        Temperature [0.1]
  -n NUM_STEPS, --num_steps NUM_STEPS
                        Number of steps [8]
  -g GPUS, --gpus GPUS  GPUs to use [0,1,...]
  -s SEEDS, --seeds SEEDS
                        Seeds [123]
  -l LOG, --log LOG     Raw log file
  -q QUAL, --qual QUAL  Minimum alignment quality (0..10) [9]

Notes:

• --temperature must be in the range 0.01 .. 2.0.
• --gpus and --seeds take comma-separated lists. The default for --gpus is CUDA_VISIBLE_DEVICES if it is set, otherwise all devices visible to torch.
• --qual is the minimum quality of an alignment column, required of both the query and the reference, for the reference backbone atoms of that column to be used as a constraint. Higher values mean fewer, more reliable constraints.
• --log redirects the (noisy) stdout/stderr of the worker processes to a file; without it the workers suppress warnings and progress bars.

esmapfold_select

usage: esmapfold_select [-h] -I INPUT -O OUTPUT [-l]

ESMapFold: Select

options:
  -h, --help            show this help message and exit
  -I INPUT, --input INPUT
                        Directory containing 'run' outputs
  -O OUTPUT, --output OUTPUT
                        Output directory for the best models
  -l, --soft-link       Soft link instead of hard copy

License

CC BY 4.0 (see LICENSE).