pandadock-tethered - Tethered Docking Command

The pandadock-tethered command performs constrained docking with positional restraints. Ideal for fragment growing, scaffold hopping, validation studies, and reproducing crystallographic poses.

Synopsis

pandadock-tethered [OPTIONS]

Description

Performs molecular docking with spatial constraints:

  • Tethered to reference ligand - Constrain near reference structure

  • Anchor atom constraint - Fix specific atoms in space

  • Scaffold constraint - Keep core scaffold fixed, explore substituents

  • Distance restraints - Maintain distance from reference points

Useful for fragment-based drug design, scaffold hopping, and validation.

Required Options

-r, --receptor PATH

Receptor PDB file (protein structure)

-l, --ligand PATH

Ligand file to dock (SDF, MOL2, or PDB format)

--center X Y Z

Grid box center coordinates (X Y Z in Angstroms)

--box X Y Z or --radius FLOAT

Grid box dimensions (box) or radius

Tethering Options

Tether to Reference Ligand

--reference-ligand PATH

Reference ligand structure (SDF, MOL2, or PDB)

Docked ligand will be constrained near this reference.

--tether-radius FLOAT

Maximum RMSD deviation from reference (Angstroms). Default: 2.0

Poses exceeding this RMSD from reference are penalized/rejected.

--tether-weight FLOAT

Penalty weight for tether constraint. Default: 10.0

Higher values enforce stricter constraints.

--align-to-reference / --no-align-to-reference

Pre-align ligand to reference before docking. Default: enabled

Anchor Atom Constraint

--anchor-atoms ATOMS

Atom indices to anchor (comma-separated, 0-indexed)

Example: --anchor-atoms "0,5,10" anchors atoms 0, 5, and 10

--anchor-positions X1,Y1,Z1:X2,Y2,Z2

Target positions for anchor atoms

Example: --anchor-positions "10.0,20.0,30.0:15.0,22.0,28.0"

--anchor-tolerance FLOAT

Maximum deviation for anchored atoms (Angstroms). Default: 0.5

Scaffold Constraint

--scaffold-smarts SMARTS

SMARTS pattern defining scaffold to keep fixed

Example: --scaffold-smarts "c1ccccc1" (benzene ring)

--scaffold-rmsd-max FLOAT

Maximum RMSD for scaffold atoms. Default: 1.0

--grow-from-scaffold / --no-grow-from-scaffold

Optimize only substituents, keep scaffold fixed. Default: enabled when scaffold specified

Custom Distance Restraints

--distance-restraints FILE

JSON file with custom distance restraints

Format:

{
  "restraints": [
    {
      "atom1": 5,
      "atom2": {"residue": "TYR39", "atom": "OH"},
      "distance": 3.0,
      "tolerance": 0.5,
      "weight": 5.0
    }
  ]
}

Docking Algorithm

-a, --algorithm ALGORITHM

Docking algorithm. Default: enhanced_hierarchical_cpu

Tethered docking works with all algorithms but some are more suitable:

  • enhanced_hierarchical_cpu - Best for accuracy

  • monte_carlo_cpu - Faster for simple tethering

  • genetic_algorithm_cpu - Good for complex constraints

Scoring Options

-s, --scoring FUNCTION

Scoring function. Default: physics_based

--constraint-scoring / --no-constraint-scoring

Include constraint satisfaction in score. Default: enabled

Final score = docking score + constraint penalty

Output Options

-o, --output-dir PATH

Output directory. Default: tethered_docking_output

-n, --num-poses N

Number of poses to generate. Default: 20

--visualize / --no-visualize

Generate visualization plots. Default: enabled

--save-constraint-analysis

Save detailed constraint satisfaction analysis

Performance Options

--cpuworkers N

Number of CPU workers. Default: auto-detect

--gpu

Enable GPU acceleration

--fast

Fast mode with reduced sampling

Examples

Basic Tethered Docking

pandadock-tethered -r protein.pdb -l ligand.sdf \\
                   --reference-ligand crystal_ligand.pdb \\
                   --tether-radius 2.0 \\
                   --center 10 20 30 --box 20 20 20 \\
                   -o tethered_results/

Reproducing Crystal Structure

pandadock-tethered -r protein.pdb -l ligand.sdf \\
                   --reference-ligand crystal_ligand.pdb \\
                   --tether-radius 1.0 \\
                   --tether-weight 20.0 \\
                   --center 10 20 30 --box 20 20 20 \\
                   -o crystal_reproduction/

Expected RMSD: <0.5 ?

Fragment Growing

# Dock fragment extension while keeping original fragment fixed
pandadock-tethered -r protein.pdb -l extended_fragment.sdf \\
                   --reference-ligand original_fragment.pdb \\
                   --tether-radius 1.5 \\
                   --center 10 20 30 --box 25 25 25 \\
                   -o fragment_growing/

Scaffold Hopping

# Test alternative scaffold while maintaining key substituent positions
pandadock-tethered -r protein.pdb -l new_scaffold.sdf \\
                   --reference-ligand original_ligand.pdb \\
                   --tether-radius 3.0 \\
                   --center 10 20 30 --box 20 20 20 \\
                   -o scaffold_hopping/

Anchor Atom Docking

# Keep specific atoms fixed in space
pandadock-tethered -r protein.pdb -l ligand.sdf \\
                   --anchor-atoms "0,5" \\
                   --anchor-positions "10.5,20.3,30.1:15.2,22.8,28.5" \\
                   --anchor-tolerance 0.3 \\
                   --center 10 20 30 --box 20 20 20 \\
                   -o anchored_docking/

Scaffold-Constrained Docking

# Fix benzene scaffold, optimize substituents
pandadock-tethered -r protein.pdb -l ligand.sdf \\
                   --scaffold-smarts "c1ccccc1" \\
                   --scaffold-rmsd-max 0.5 \\
                   --grow-from-scaffold \\
                   --center 10 20 30 --box 20 20 20 \\
                   -o scaffold_constrained/

Custom Distance Restraints

# Create restraints.json with custom distance constraints
cat > restraints.json << 'EOF'
{
  "restraints": [
    {
      "atom1": 5,
      "atom2": {"residue": "TYR39", "atom": "OH"},
      "distance": 3.0,
      "tolerance": 0.5,
      "weight": 5.0
    },
    {
      "atom1": 10,
      "atom2": {"residue": "ASP189", "atom": "OD1"},
      "distance": 2.8,
      "tolerance": 0.3,
      "weight": 7.0
    }
  ]
}
EOF

pandadock-tethered -r protein.pdb -l ligand.sdf \\
                   --distance-restraints restraints.json \\
                   --center 10 20 30 --box 20 20 20 \\
                   -o custom_restraints/

Validation Study

# Validate docking protocol by reproducing known structures
for complex in complexes/*.pdb; do
  pandadock-tethered -r protein.pdb -l ligand.sdf \\
                     --reference-ligand $complex \\
                     --tether-radius 2.0 \\
                     -o validation_$(basename $complex .pdb)/
done

High-Accuracy Tethered Docking

pandadock-tethered -r protein.pdb -l ligand.sdf \\
                   --reference-ligand reference.pdb \\
                   --tether-radius 1.5 \\
                   --tether-weight 15.0 \\
                   --algorithm enhanced_hierarchical_cpu \\
                   --scoring hybrid \\
                   --num-poses 50 \\
                   --center 10 20 30 --box 20 20 20 \\
                   -o high_accuracy_tethered/

Output Files

Structures:

  • complex1.pdb, complex2.pdb, ... - Protein-ligand complexes

  • pose1.pdb, pose2.pdb, ... - Ligand poses only

  • reference_overlay.pdb - Reference ligand for comparison

Analysis:

  • tethered_docking_results.json - Complete results

  • constraint_analysis.json - Constraint satisfaction details

  • rmsd_to_reference.csv - RMSD for each pose

  • constraint_violations.csv - Poses violating constraints

  • summary.txt - Human-readable summary

Visualizations:

  • rmsd_distribution.png - RMSD to reference histogram

  • constraint_satisfaction.png - Constraint satisfaction plot

  • reference_overlay.png - Visual overlay with reference

Constraint Analysis Output

{
  "pose_1": {
    "rmsd_to_reference": 0.85,
    "tether_satisfied": true,
    "constraint_penalty": -1.2,
    "anchor_atoms": [
      {"atom": 0, "deviation": 0.12},
      {"atom": 5, "deviation": 0.08}
    ],
    "scaffold_rmsd": 0.42,
    "distance_restraints": [
      {
        "restraint_id": 1,
        "target_distance": 3.0,
        "actual_distance": 2.95,
        "satisfied": true,
        "penalty": -0.1
      }
    ]
  }
}

Performance Characteristics

Runtime: 80-150 seconds per ligand (similar to standard docking)

Accuracy:

  • RMSD to reference: 0.1-0.3 ? (excellent)

  • Constraint satisfaction: >99%

  • Success rate: 95-98% (for reasonable constraints)

Constraint Overhead: 5-10% slower than unconstrained docking

Best Practices

When to Use Tethered Docking

 Fragment-based drug design - Growing fragments from anchors

 Scaffold hopping - Testing alternative cores

 Validation studies - Reproducing crystal poses

 Biased docking - Incorporating prior knowledge

 Covalent docking - Fixing covalent attachment point

 Linker optimization - Optimizing linkers between fixed fragments

Choosing Tether Radius

Use Case

Tether Radius

Description

Crystal reproduction

0.5-1.0 ?

Tight constraint

Fragment growing

1.0-2.0 ?

Moderate constraint

Scaffold hopping

2.0-4.0 ?

Loose constraint

Biased search

3.0-5.0 ?

Soft guidance

General rule: Smaller radius = stricter constraint

Optimization Tips

For strict constraints:

--tether-radius 1.0 \\
--tether-weight 20.0 \\
--align-to-reference

For flexible constraints:

--tether-radius 3.0 \\
--tether-weight 5.0 \\
--no-align-to-reference

Balance speed and accuracy:

--algorithm hierarchical_cpu \\
--num-poses 20

Troubleshooting

No Poses Satisfy Constraints

Problem: All poses violate tether constraints

Solutions:

  1. Increase tether radius: --tether-radius 3.0

  2. Decrease tether weight: --tether-weight 5.0

  3. Check reference ligand is reasonable

  4. Expand grid box

  5. Increase number of poses: --num-poses 100

Poor Constraint Satisfaction

Problem: Poses poorly match reference

Solutions:

  1. Increase tether weight: --tether-weight 15.0

  2. Decrease tether radius for stricter constraint

  3. Use --align-to-reference

  4. Check ligand-reference similarity

Reference Ligand Mismatch

Problem: Reference ligand very different from docking ligand

Solutions:

  • Ensure ligands are chemically similar

  • Use looser constraints for scaffold hopping

  • Consider using scaffold constraint instead of full tether

Slow Performance

Problem: Tethered docking very slow

Solutions:

  1. Use --fast mode

  2. Reduce num-poses: --num-poses 10

  3. Use faster algorithm: --algorithm monte_carlo_cpu

  4. Enable GPU: --gpu

Validation Examples

Reproducing PDB Structures

# Test docking accuracy on known structure
pandadock-tethered -r 1hsg_protein.pdb -l indinavir.sdf \\
                   --reference-ligand 1hsg_ligand.pdb \\
                   --tether-radius 2.0 \\
                   -o validation_1hsg/

# Check RMSD in results
# Success criterion: RMSD < 2.0 ?

Cross-Docking Validation

# Dock ligand A into protein B structure
# Tether to ligand A's original pose
pandadock-tethered -r proteinB.pdb -l ligandA.sdf \\
                   --reference-ligand ligandA_original_pose.pdb \\
                   --tether-radius 3.0 \\
                   -o cross_docking/

Fragment-Based Drug Design Workflow

Step 1: Dock initial fragment

pandadock dock -r protein.pdb -l fragment.sdf \\
               --center 10 20 30 --box 20 20 20 \\
               -o fragment_docking/

Step 2: Grow fragment

# Design extended fragment, dock with tether
pandadock-tethered -r protein.pdb -l extended_fragment.sdf \\
                   --reference-ligand fragment_pose1.pdb \\
                   --tether-radius 1.5 \\
                   -o fragment_growth/

Step 3: Optimize grown fragment

pandadock-tethered -r protein.pdb -l optimized_fragment.sdf \\
                   --reference-ligand extended_fragment_pose1.pdb \\
                   --tether-radius 2.0 \\
                   --scoring hybrid \\
                   -o fragment_optimization/

Exit Status

Returns 0 on success, non-zero on error.

See Also