Example Workflows

Complete examples for common protein design use cases.

Example 1: Protein Binder Design (BoltzGen)

Design a protein to bind EGFR using BoltzGen (default design tool).

Create Design YAML

egfr_protein_design.yaml

# BoltzGen design specification for protein binder
entities:
  # Designed protein entity
  - protein:
      id: C
      sequence: 80..120  # Length range for designed protein

  # Target structure entity  
  - file:
      path: egfr_structure.cif
      include:
        - chain:
            id: A  # Target chain to bind

Create Samplesheet

egfr_samplesheet.csv

sample_id,design_yaml,structure_files,protocol,num_designs,budget,reuse,target_msa,target_sequence,target_template
egfr_binder,egfr_protein_design.yaml,egfr_structure.cif,protein-anything,3,2,,egfr.a3m,egfr_sequence.fasta,

Run Pipeline

All analysis modules are enabled by default:

nextflow run seqeralabs/nf-proteindesign \
    -profile docker \
    --input egfr_samplesheet.csv \
    --outdir egfr_designs

Analyze Results

import pandas as pd

# Load consolidated metrics
results = pd.read_csv('egfr_designs/egfr_binder/consolidated/consolidated_metrics.csv')

# Find top 5 candidates by binding affinity
top5 = results.nsmallest(5, 'prodigy_delta_g')
print(top5[['design_file', 'prodigy_delta_g', 'prodigy_kd', 'ipsae_score']])

Example 2: Peptide Binder Design (BoltzGen)

Design peptide binders for a target protein.

Create Design YAML

peptide_design.yaml

# BoltzGen design specification for peptide binder
entities:
  # Designed peptide entity
  - protein:
      id: P
      sequence: 12..25  # Peptide length range

  # Target structure
  - file:
      path: target.cif
      include:
        - chain:
            id: A

Create Samplesheet

peptide_samplesheet.csv

sample_id,design_yaml,structure_files,protocol,num_designs,budget,reuse,target_msa,target_sequence,target_template
peptide_binder,peptide_design.yaml,target.cif,peptide-anything,3,2,,,target.fasta,

Run Pipeline

nextflow run seqeralabs/nf-proteindesign \
    -profile docker \
    --input peptide_samplesheet.csv \
    --outdir peptide_designs

:material-antibody: Example 3: Nanobody Design (BoltzGen)

Design nanobodies to bind a specific target.

Create Design YAML

nanobody_design.yaml

# BoltzGen design specification for nanobody
entities:
  # Designed nanobody entity
  - protein:
      id: N
      sequence: 110..130  # Typical nanobody length range

  # Target structure
  - file:
      path: antigen.cif
      include:
        - chain:
            id: A

Create Samplesheet

nanobody_samplesheet.csv

sample_id,design_yaml,structure_files,protocol,num_designs,budget,reuse,target_msa,target_sequence,target_template
nanobody_binder,nanobody_design.yaml,antigen.cif,nanobody-anything,3,2,,,antigen.fasta,

Run Pipeline

nextflow run seqeralabs/nf-proteindesign \
    -profile docker \
    --input nanobody_samplesheet.csv \
    --outdir nanobody_designs

Example 4: Protein Binder Design (Complexa)

Design a protein binder using the Proteina-Complexa backend.

Create Samplesheet

complexa_samplesheet.csv

sample_id,target_pdb,pipeline_config,target_sequence,target_msa,target_template
egfr_binder,data/egfr.cif,configs/egfr_pipeline.yaml,data/egfr.fasta,data/egfr.a3m,

Run Pipeline

nextflow run seqeralabs/nf-proteindesign \
    -profile docker \
    --protein_design_tool complexa \
    --input complexa_samplesheet.csv \
    --complexa_ckpt_dir /path/to/checkpoints \
    --outdir complexa_designs

Example 5: Multiple Targets

Design binders for multiple targets in a single run.

Create Design YAMLs

target1_design.yaml

entities:
  - protein:
      id: C
      sequence: 80..120
  - file:
      path: target1.cif
      include:
        - chain:
            id: A

target2_design.yaml

entities:
  - protein:
      id: C
      sequence: 60..100
  - file:
      path: target2.cif
      include:
        - chain:
            id: B

Create Samplesheet

multi_target_samplesheet.csv

sample_id,design_yaml,structure_files,protocol,num_designs,budget,reuse,target_msa,target_sequence,target_template
target1_binder,target1_design.yaml,target1.cif,protein-anything,3,2,,,target1.fasta,
target2_binder,target2_design.yaml,target2.cif,protein-anything,3,2,,,target2.fasta,

Run Pipeline

nextflow run seqeralabs/nf-proteindesign \
    -profile docker \
    --input multi_target_samplesheet.csv \
    --outdir multi_designs

Example 6: Selective Analysis Modules

By default all analysis modules are enabled. To disable specific modules:

Run Pipeline

nextflow run seqeralabs/nf-proteindesign \
    -profile docker \
    --input samplesheet.csv \
    --outdir selective_results \
    --run_foldseek false \
    --run_prodigy false

Review Consolidated Report

# View consolidated metrics
cat selective_results/{sample_id}/consolidated/consolidated_metrics.csv | column -t -s,

# Find designs with best affinity
sort -t',' -k3,3n selective_results/{sample_id}/consolidated/consolidated_metrics.csv | head -10

Example 7: Using Test Profiles

The pipeline includes built-in test profiles for quick validation.

Test Protein Design

nextflow run seqeralabs/nf-proteindesign \
    -profile test_design_protein,docker \
    --outdir test_protein_results

Test Peptide Design

nextflow run seqeralabs/nf-proteindesign \
    -profile test_design_peptide,docker \
    --outdir test_peptide_results

Test Nanobody Design

nextflow run seqeralabs/nf-proteindesign \
    -profile test_design_nanobody,docker \
    --outdir test_nanobody_results

Example 8: Seqera Platform Deployment

Run the pipeline on Seqera Platform with GPU compute.

Via Seqera Platform UI

1. Navigate to your workspace
2. Click "Launch Pipeline"
3. Select seqeralabs/nf-proteindesign
4. Upload your samplesheet to a Data Link
5. Configure parameters:
6. input: Path to samplesheet in Data Link
7. outdir: Output Data Link path
8. protein_design_tool: boltzgen or complexa
9. Select GPU-enabled compute environment
10. Click "Launch"

Via Seqera CLI

# Create launch configuration
tw launch seqeralabs/nf-proteindesign \
    --workspace <your-workspace> \
    --compute-env <gpu-compute-env> \
    --params-file params.json \
    --outdir s3://your-bucket/results

Output Files

After pipeline completion, you'll find:

results/
└── {sample_id}/
    ├── boltzgen/ or complexa/         # Design structures (depends on tool)
    │   ├── design_1.pdb
    │   ├── design_2.pdb
    │   └── ...
    ├── proteinmpnn/                   # Optimized sequences & scores
    │   ├── sequences/
    │   └── scores/
    ├── boltz2/                        # Refolded structures
    │   ├── structures/
    │   ├── confidence/
    │   └── npz/
    ├── ipsae/                         # Interface scores
    │   └── *_ipsae_scores.txt
    ├── prodigy/                       # Affinity predictions
    │   └── *_prodigy_results.txt
    ├── foldseek/                      # Structural search results
    │   └── *_foldseek_summary.tsv
    └── consolidated/                  # Combined metrics report
        ├── consolidated_metrics.csv
        └── consolidated_report.html

Tips and Best Practices

Design YAML Tips (BoltzGen)

• Length ranges: Use 80..120 syntax for flexible design lengths
• Multiple chains: Specify multiple target chains for complex interfaces
• Chain IDs: Use descriptive chain IDs (A, B, C, etc.)

Parameter Tuning

• Quick tests: Use small num_designs and budget values for fast validation
• Production runs: Increase num_designs and budget for diversity and quality
• Complexa tuning: Adjust --complexa_nsteps, --complexa_batch_size, and --complexa_replicas

Resource Optimization

• GPU memory: Ensure 16GB+ VRAM for standard runs
• Caching: Use --cache_dir (BoltzGen) or --complexa_ckpt_dir (Complexa) for model weights
• Resume: Always use -resume flag to recover from interruptions

Analysis Workflow

1. Run BoltzGen or Complexa to generate initial designs
2. ProteinMPNN optimizes sequences for generated structures
3. Boltz-2 predicts structures from optimized sequences (refolding validation)
4. ipSAE scores interface quality
5. PRODIGY predicts binding affinity
6. Foldseek searches for structural similarity
7. Consolidation combines all metrics into a ranked report
8. Select top designs for experimental validation

Troubleshooting

Common Issues

GPU not detected:

# Verify GPU access
nvidia-smi
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

Out of memory:

# For Complexa, reduce batch size
nextflow run ... --complexa_batch_size 8

Pipeline fails:

# Resume from last successful step
nextflow run seqeralabs/nf-proteindesign -resume ...

Next Steps

• Parameter Reference
• Quick Reference Guide
• Analysis Modules
• Architecture Documentation

---

Need Help?

Join the discussion on GitHub or open an issue.