ProteinMPNN

Overview

Sequence design for one backbone or a batch of PDB backbones.
Redesigning selected chains or residues while fixing structural context.
Ligand-aware sequence design around non-protein atoms in a PDB.
Generating FASTA/sequence records for downstream folding or filtering.

Modes

Mode	Input shape	When to use it
`sequence_design` Sequence Design Default	Uses one selected file/source when file parameters are present.	Generate designed protein sequences from one PDB backbone.
`batch_sequence_design` Batch Sequence Design	Consumes a folder or output set; useful for batches and pipeline handoffs.	Generate all-residue sequence designs for all PDB inputs in the selected source.

Canonical Job Configuration

These are the fields exposed by the default job configuration for proteinmpnn. They are also returned by GET /api/v1/program/params?program=proteinmpnn and submitted as the params JSON object to POST /api/v1/job/submit.

Parameter	Type	Modes	What it does
`structure` Structure	Structure file	Sequence Design	Choose the PDB backbone from an upload, dataset, or previous job output. Required; Files: .pdb
`design_model` Design Model	Text	All modes	Choose whether design should use ligand atoms, a general ProteinMPNN model, soluble-only training, or membrane labels. Default: Ligand-aware; Options: Ligand-aware, Protein-only, Soluble-only, Global membrane, Per-residue membrane
`design_scope` Design Scope	Text	Sequence Design	Choose which residues are redesigned; unselected residues stay fixed. Default: All residues; Options: All residues, Selected chains, Only listed residues, Fix listed residues
`chains_to_design` Chains To Design	Text	Sequence Design	Comma- or space-separated chain IDs to redesign while keeping other chains fixed. Required; Shown when design_scope is Selected chains
`batch_chains_to_design` Chains To Design	Text	Batch Sequence Design	Optional comma- or space-separated chain IDs to redesign for every PDB in the batch. Leave blank to redesign all parsed protein chains.
`redesigned_residues` Residues To Redesign	Residue selection	Sequence Design	Residues to redesign. Everything else in the parsed structure stays fixed. Required; Shown when design_scope is Only listed residues
`fixed_residues` Residues To Keep Fixed	Residue selection	Sequence Design	Residues to keep fixed while the rest of the parsed structure is redesigned. Required; Shown when design_scope is Fix listed residues
`sequence_count` Sequences	Integer	All modes	How many sequence designs to generate. Default: 8; Range: 1-100
`diversity` Sequence Diversity	Text	All modes	Higher diversity samples more broadly from the model. Default: Balanced; Options: Conservative, Balanced, Exploratory
`use_ligand_context` Use Ligand Context	Yes/no	All modes	Use non-protein atoms from the PDB as context for ligand-aware sequence design. Default: true; Shown when design_model is Ligand-aware
`membrane_environment` Membrane Environment	Text	All modes	Global membrane label used by the membrane ProteinMPNN model. Default: Transmembrane; Options: Transmembrane, Soluble; Shown when design_model is Global membrane
`membrane_buried_residues` Buried Membrane Residues	Residue selection	All modes	Residues labeled as buried in the membrane. Provide this and/or interface membrane residues. Shown when design_model is Per-residue membrane
`membrane_interface_residues` Interface Membrane Residues	Residue selection	All modes	Residues labeled as membrane interface. Provide this and/or buried membrane residues. Shown when design_model is Per-residue membrane
`split_fastas` Split FASTA Outputs	Yes/no	All modes	Write each generated FASTA record as its own single-record FASTA file under /outputs/seqs. Default: true

Advanced configuration fields

Parameter	Type	Modes	What it does
`disallowed_amino_acids` Disallowed Amino Acids	Text	All modes	Optional single-letter amino-acid codes to exclude globally from designed positions.
`side_chain_packing` Side-Chain Packing	Text	All modes	Optionally produce packed full-atom PDBs for each design. Default: Off; Options: Off, Fast, Thorough
`include_reference_fasta` Include Reference FASTA	Yes/no	All modes	When splitting FASTA outputs, also write the first input/reference record under /outputs/seqs. Default: false; Shown when split_fastas is true
`clean_fasta_headers` Clean FASTA Headers	Yes/no	All modes	Rewrite upstream FASTA headers to stable parser-safe IDs and write original header metadata to /outputs/proteinmpnn_fasta_metadata.tsv. Default: true
`repack_fixed_side_chains` Repack Fixed Side Chains	Yes/no	All modes	Allow the side-chain packer to move fixed residues too. Default: false; Shown when side_chain_packing is one of Fast, Thorough
`fixed_side_chain_context` Use Fixed Side Chains As Context	Yes/no	Sequence Design	Treat fixed residue side-chain atoms as additional ligand context. Default: false; Shown when design_model is Ligand-aware
`exclude_other_chains` Exclude Other Chains	Yes/no	Sequence Design	Parse and output only the selected design chains. Default: false; Shown when design_scope is Selected chains
`tie_homooligomer_chains` Tie Homooligomer Chains	Yes/no	All modes	Tie equivalent positions across chains for homooligomer design. Default: false
`random_seed` Random Seed	Integer	All modes	Set for reproducible sampling; leave blank for a random seed. Range: 1-999999999
`save_sampling_stats` Save Sampling Stats	Yes/no	All modes	Write model sampling tensors in addition to FASTA and PDB outputs. Default: false

Outputs And Metrics

Designed FASTA sequences.
Optional packed full-atom PDBs.
Metadata tables and sequence JSON sidecars for downstream pipeline steps.
ProteinMPNN header scores such as overall confidence, ligand confidence, and sequence recovery are useful for triage.
Sequence recovery measures native/reference similarity, not novelty or function.

Common Examples

All-residue design: one PDB, Ligand-aware or Protein-only model, 8 sequences, Balanced diversity.
Interface redesign: select only interface residues and keep the rest fixed.
Batch design: run all PDB inputs and split FASTA outputs for downstream folding.

Example API params

{
  "mode": "sequence_design",
  "structure": "backbone.pdb",
  "design_model": "Ligand-aware",
  "design_scope": "All residues",
  "sequence_count": 8,
  "diversity": "Balanced"
}

Caveats

Backbone quality sets the ceiling for useful sequences.
Ligand-aware design uses non-protein atoms as context; ligand chemistry and protonation still need expert review.
Designed sequences require independent folding, expression, and functional validation.

Advanced Submit

Advanced submit is still available for direct program arguments through POST /api/v1/job/submit-advanced. Prefer canonical configuration unless you need exact low-level arguments or are reproducing a known command line.

Advanced submit exposes ProteinMPNN/LigandMPNN flags such as model type, chain selection, fixed/redesigned residues, temperature, and side-chain packing.
Use canonical configuration for most single-backbone and batch design runs.

curl -X POST https://subseq.bio/api/v1/job/submit \
  -H "Authorization: Bearer <api_key>" \
  -F program=proteinmpnn \
  -F 'params={"mode":"sequence_design","structure":"backbone.pdb","design_model":"Ligand-aware","design_scope":"All residues","sequence_count":8,"diversity":"Balanced"}'