# OEDocking TK

> Molecular docking, pose prediction, and receptor preparation toolkit for structure-based drug design

## Links
- [Full Documentation](https://docs.eyesopen.com/toolkits/python/dockingtk/index.html)
- [Theory](https://docs.eyesopen.com/toolkits/python/dockingtk/theory/theory.html)
- [Code Examples](https://docs.eyesopen.com/toolkits/python/dockingtk/examples.html)
- [API Reference](https://docs.eyesopen.com/toolkits/python/dockingtk/api.html)

## Core API - Function Quick Reference

### Receptor Creation & Management
```
OEMakeReceptor(receptor: OEReceptor, protein: OEGraphMol, ligand: OEGraphMol) -> bool
  Use for: Creating a receptor from protein and bound ligand structures
  Example: OEMakeReceptor(receptor, protein_mol, ligand_mol)
  See: https://docs.eyesopen.com/toolkits/python/dockingtk/theory/receptor.html

OEWriteReceptorFile(receptor: OEReceptor, filename: str) -> bool
  Use for: Saving a prepared receptor to disk for reuse
  Example: OEWriteReceptorFile(receptor, "receptor.oeb.gz")
  
OEReadReceptorFile(receptor: OEReceptor, filename: str) -> bool
  Use for: Loading a previously prepared receptor from file
  Example: OEReadReceptorFile(receptor, "receptor.oeb.gz")

OEReceptorGetProtein(receptor: OEReceptor) -> OEGraphMol
  Use for: Extracting the protein structure from a receptor
  Example: protein = OEReceptorGetProtein(receptor)

OEReceptorGetBoundLigand(receptor: OEReceptor) -> OEGraphMol
  Use for: Getting the reference ligand used to define the binding site
  Example: ref_ligand = OEReceptorGetBoundLigand(receptor)
```

### Docking Operations
```
OEDock.__init__(resolution: unsigned int = OESearchResolution_Default)
  Use for: Creating a docking object with specified search resolution
  Example: dock = OEDock(OESearchResolution_High)
  See: https://docs.eyesopen.com/toolkits/python/dockingtk/theory/docking.html

OEDock.Initialize(receptor: OEReceptor) -> bool
  Use for: Preparing the docking engine with a receptor
  Example: dock.Initialize(receptor)

OEDock.DockMultiConformerMolecule(mcmol: OEMol) -> OEMol
  Use for: Docking a multi-conformer molecule and returning best pose
  Example: docked_mol = dock.DockMultiConformerMolecule(mcmol)

OEDock.ScoreLigand(ligand: OEGraphMol) -> float
  Use for: Scoring a ligand pose without docking
  Example: score = dock.ScoreLigand(posed_ligand)

OEDock.AnnotatePose(pose: OEGraphMol) -> bool
  Use for: Adding docking score and metadata to a docked pose
  Example: dock.AnnotatePose(docked_mol)
```

### Scoring Functions
```
OEScore.__init__(scoreType: unsigned int = OEScoreType_Chemgauss4)
  Use for: Creating a scoring object with specific scoring function
  Example: score = OEScore(OEScoreType_Chemgauss4)
  See: https://docs.eyesopen.com/toolkits/python/dockingtk/theory/scoring.html

OEScore.Initialize(receptor: OEReceptor) -> bool
  Use for: Preparing the scoring function with a receptor
  Example: score.Initialize(receptor)

OEScore.ScoreLigand(ligand: OEGraphMol) -> float
  Use for: Calculating score for a ligand pose
  Example: score_value = score.ScoreLigand(ligand)

OEScore.AnnotatePose(pose: OEGraphMol) -> bool
  Use for: Adding score information to pose SD data
  Example: score.AnnotatePose(docked_mol)

OEScore.SystematicSolidBodyOptimize(pose: OEGraphMol) -> float
  Use for: Optimizing ligand position/orientation in binding site
  Example: optimized_score = score.SystematicSolidBodyOptimize(pose)
```

### POSIT (Pose Prediction)
```
OEPosit.__init__()
  Use for: Creating a POSIT object for pose-by-alignment
  Example: posit = OEPosit()
  See: https://docs.eyesopen.com/toolkits/python/dockingtk/theory/pose_stub_tk.html

OEPosit.AddReceptor(receptor: OEReceptor) -> bool
  Use for: Adding a receptor with bound ligand for alignment
  Example: posit.AddReceptor(receptor)

OEPosit.Dock(mcmol: OEMol) -> OESinglePoseResult
  Use for: Generating single best pose using bound ligand alignment
  Example: result = posit.Dock(mcmol)

OEPosit.DockMulti(mcmol: OEMol, num_poses: int) -> OEMultiPoseResult
  Use for: Generating multiple poses ranked by probability
  Example: results = posit.DockMulti(mcmol, 10)

OEPositOptions.SetIgnoreNitrogenStereo(ignore: bool)
  Use for: Controlling whether nitrogen stereochemistry is considered
  Example: opts.SetIgnoreNitrogenStereo(True)
```

### ShapeFit (Shape-Based Docking)
```
OEShapeFit.__init__()
  Use for: Creating shape-based overlay optimization object
  Example: shapefit = OEShapeFit()
  See: https://docs.eyesopen.com/toolkits/python/dockingtk/theory/shapefit.html

OEShapeFit.SetupRef(refmol: OEMol) -> bool
  Use for: Setting reference molecule for shape overlay
  Example: shapefit.SetupRef(reference_ligand)

OEShapeFit.Overlay(fitmol: OEMol) -> OEBestOverlayResults
  Use for: Performing flexible shape overlay optimization
  Example: results = shapefit.Overlay(fit_molecule)

OEShapeFitOptions.SetAllowClash(allow: bool)
  Use for: Controlling whether protein clashes are allowed
  Example: opts.SetAllowClash(False)
```

### Receptor Manipulation
```
OESetInnerContourLevel(receptor: OEReceptor, level: float) -> bool
  Use for: Adjusting inner contour to control binding site cavity size
  Example: OESetInnerContourLevel(receptor, 2.5)

OEGetReceptorVolume(receptor: OEReceptor) -> float
  Use for: Getting the volume of the receptor binding site
  Example: volume = OEGetReceptorVolume(receptor)

OEToggleReceptorInnerContour(receptor: OEReceptor) -> bool
  Use for: Enabling/disabling inner contour constraints
  Example: OEToggleReceptorInnerContour(receptor)
```

### Result Handling
```
OESinglePoseResult.GetProbability() -> float
  Use for: Getting probability estimate for POSIT pose
  Example: prob = result.GetProbability()

OESinglePoseResult.GetPose() -> OEGraphMol
  Use for: Extracting the predicted pose from POSIT result
  Example: pose = result.GetPose()

OEMultiPoseResult.GetSinglePoseResults() -> iterator
  Use for: Iterating through multiple POSIT poses
  Example: for result in multi_result.GetSinglePoseResults()

OEBestOverlayResults.GetTanimoto() -> float
  Use for: Getting shape Tanimoto score from ShapeFit overlay
  Example: tanimoto = overlay_result.GetTanimoto()
```

## Common Patterns - Complete Working Examples

### Pattern: Basic Molecular Docking Workflow
```python
from openeye import oechem, oedocking

# Read receptor and prepare docking
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")

# Initialize docking with high resolution
dock = oedocking.OEDock(oedocking.OESearchResolution_High)
dock.Initialize(receptor)

# Read and dock molecules
ifs = oechem.oemolistream("ligands.sdf")
ofs = oechem.oemolostream("docked.sdf")
for mol in ifs.GetOEGraphMols():
    docked_mol = oechem.OEGraphMol()
    dock.DockMultiConformerMolecule(docked_mol, mol)
    oechem.OEWriteMolecule(ofs, docked_mol)
```
Use when: You have a prepared receptor and want to dock a library of molecules with standard settings

### Pattern: Creating a Receptor from PDB
```python
from openeye import oechem, oedocking, oespruce

# Read protein-ligand complex
ifs = oechem.oemolistream("complex.pdb")
complex_mol = oechem.OEGraphMol()
oechem.OEReadMolecule(ifs, complex_mol)

# Split into protein and ligand
protein = oechem.OEGraphMol()
ligand = oechem.OEGraphMol()
oechem.OESplitMolComplex(ligand, protein, complex_mol)

# Create and save receptor
receptor = oechem.OEGraphMol()
oedocking.OEMakeReceptor(receptor, protein, ligand)
oedocking.OEWriteReceptorFile(receptor, "receptor.oeb.gz")
```
Use when: Starting from a PDB structure with bound ligand to create a docking receptor

### Pattern: Rescoring Docked Poses
```python
from openeye import oechem, oedocking

# Load receptor and create scoring object
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")
score = oedocking.OEScore(oedocking.OEScoreType_Chemgauss4)
score.Initialize(receptor)

# Rescore poses from file
ifs = oechem.oemolistream("docked.sdf")
ofs = oechem.oemolostream("rescored.sdf")
for pose in ifs.GetOEGraphMols():
    score_value = score.ScoreLigand(pose)
    score.AnnotatePose(pose)
    oechem.OEWriteMolecule(ofs, pose)
```
Use when: You have docked poses and want to rescore with a different scoring function

### Pattern: POSIT Pose Prediction
```python
from openeye import oechem, oedocking

# Load receptor with bound ligand
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")

# Initialize POSIT
posit = oedocking.OEPosit()
posit.AddReceptor(receptor)

# Generate pose for new molecule
mol = oechem.OEGraphMol()
ifs = oechem.oemolistream("query.sdf")
oechem.OEReadMolecule(ifs, mol)
result = posit.Dock(mol)
if result.GetProbability() > 0.5:
    pose = result.GetPose()
    oechem.OEWriteMolecule(ofs, pose)
```
Use when: You want to predict binding pose based on similarity to a known bound ligand

### Pattern: Multiple POSIT Poses with Probability Filtering
```python
from openeye import oechem, oedocking

# Setup POSIT with receptor
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")
posit = oedocking.OEPosit()
posit.AddReceptor(receptor)

# Generate multiple poses
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)
multi_result = posit.DockMulti(mol, 10)

# Filter by probability threshold
ofs = oechem.oemolostream("poses.sdf")
for result in multi_result.GetSinglePoseResults():
    if result.GetProbability() > 0.3:
        pose = result.GetPose()
        oechem.OESetSDData(pose, "Probability", str(result.GetProbability()))
        oechem.OEWriteMolecule(ofs, pose)
```
Use when: You need multiple alternative poses ranked by confidence for analysis

### Pattern: ShapeFit Flexible Overlay
```python
from openeye import oechem, oedocking

# Read reference and fit molecules
ref_mol = oechem.OEGraphMol()
fit_mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("reference.sdf"), ref_mol)
oechem.OEReadMolecule(oechem.oemolistream("fit.sdf"), fit_mol)

# Setup ShapeFit with protein context
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")
shapefit = oedocking.OEShapeFit()
shapefit.SetupRef(ref_mol, receptor)

# Perform overlay and get result
overlay_result = shapefit.Overlay(fit_mol)
overlaid_mol = overlay_result.GetOverlayConf()
tanimoto = overlay_result.GetTanimoto()
```
Use when: Overlaying molecules by shape while avoiding protein clashes

### Pattern: Adjusting Receptor Binding Site Volume
```python
from openeye import oechem, oedocking

# Load receptor
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")

# Check current volume
original_volume = oedocking.OEGetReceptorVolume(receptor)
print(f"Original volume: {original_volume}")

# Adjust inner contour to expand site
oedocking.OESetInnerContourLevel(receptor, 2.5)
new_volume = oedocking.OEGetReceptorVolume(receptor)
print(f"New volume: {new_volume}")

# Save modified receptor
oedocking.OEWriteReceptorFile(receptor, "receptor_expanded.oeb.gz")
```
Use when: The default binding site is too restrictive and you need to accommodate larger ligands

### Pattern: Docking with Custom Resolution
```python
from openeye import oechem, oedocking

# Create docking objects with different resolutions
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")

# High resolution for final docking
dock_high = oedocking.OEDock(oedocking.OESearchResolution_High)
dock_high.Initialize(receptor)

# Standard resolution for screening
dock_std = oedocking.OEDock(oedocking.OESearchResolution_Standard)
dock_std.Initialize(receptor)

# Dock with appropriate resolution
mol = oechem.OEGraphMol()
docked = oechem.OEGraphMol()
dock_high.DockMultiConformerMolecule(docked, mol)
```
Use when: Balancing speed vs accuracy - use Standard for large libraries, High for final poses

### Pattern: POSIT with Nitrogen Stereochemistry Control
```python
from openeye import oechem, oedocking

# Setup POSIT with custom options
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")

opts = oedocking.OEPositOptions()
opts.SetIgnoreNitrogenStereo(True)  # Ignore nitrogen inversion

posit = oedocking.OEPosit(opts)
posit.AddReceptor(receptor)

# Dock molecule
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)
result = posit.Dock(mol)
pose = result.GetPose()
```
Use when: Dealing with molecules containing pyramidal nitrogens that can invert

### Pattern: Extracting Receptor Components
```python
from openeye import oechem, oedocking

# Load receptor
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")

# Extract protein structure
protein = oedocking.OEReceptorGetProtein(receptor)
oechem.OEWriteMolecule(oechem.oemolostream("protein.pdb"), protein)

# Extract bound ligand
bound_ligand = oedocking.OEReceptorGetBoundLigand(receptor)
oechem.OEWriteMolecule(oechem.oemolostream("ligand.sdf"), bound_ligand)

# Use components for analysis or visualization
```
Use when: You need to access the protein or reference ligand from a receptor for separate analysis

### Pattern: Batch Docking with Score Annotation
```python
from openeye import oechem, oedocking

# Initialize docking
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")
dock = oedocking.OEDock()
dock.Initialize(receptor)

# Process library
ifs = oechem.oemolistream("library.sdf")
ofs = oechem.oemolostream("docked_scored.sdf")

for mol in ifs.GetOEGraphMols():
    docked = oechem.OEGraphMol()
    dock.DockMultiConformerMolecule(docked, mol)
    dock.AnnotatePose(docked)  # Add score to SD data
    oechem.OEWriteMolecule(ofs, docked)
```
Use when: Processing large libraries and need scores stored with each pose for downstream analysis

### Pattern: ShapeFit with Clash Control
```python
from openeye import oechem, oedocking

# Setup ShapeFit with clash prevention
receptor = oechem.OEGraphMol()
oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz")
ref_mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("ref.sdf"), ref_mol)

opts = oedocking.OEShapeFitOptions()
opts.SetAllowClash(False)  # Prevent protein clashes

shapefit = oedocking.OEShapeFit(opts)
shapefit.SetupRef(ref_mol, receptor)

# Overlay molecule
fit_mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("fit.sdf"), fit_mol)
result = shapefit.Overlay(fit_mol)
```
Use when: Ensuring overlaid molecules don't clash with protein structure

### Pattern: Multi-Receptor POSIT
```python
from openeye import oechem, oedocking

# Load multiple receptor conformations
posit = oedocking.OEPosit()
for i in range(1, 4):
    receptor = oechem.OEGraphMol()
    oedocking.OEReadReceptorFile(receptor, f"receptor_{i}.oeb.gz")
    posit.AddReceptor(receptor)

# Dock against ensemble
mol = oechem.OEGraphMol()
oechem.OEReadMolecule(oechem.oemolistream("ligand.sdf"), mol)
result = posit.Dock(mol)  # Uses best receptor match
pose = result.GetPose()
prob = result.GetProbability()
```
Use when: Accounting for receptor flexibility by using multiple conformations

## API Decision Guide

### Choosing Docking Method
- **For structure-based docking without reference ligand**: use `OEDock` (exhaustive search in binding site)
- **For pose prediction with known bound ligand**: use `OEPosit` (alignment-based, faster, more accurate when reference available)
- **For shape-based overlay with protein context**: use `OEShapeFit` (flexible overlay avoiding clashes)

### Choosing Scoring Function
- **For general docking**: use `OEScoreType_Chemgauss4` (default, well-validated)
- **For rescoring poses**: use `OEScore` with desired scoring function
- **For shape similarity**: use `OEShapeFit` (returns Tanimoto scores)

### Choosing Search Resolution
- **For large library screening**: use `OESearchResolution_Standard` (faster, good accuracy)
- **For final pose refinement**: use `OESearchResolution_High` (slower, best accuracy)
- **For very fast screening**: use `OESearchResolution_Low` (fastest, lower accuracy)

### Receptor Preparation
- **From PDB with bound ligand**: use `OEMakeReceptor(receptor, protein, ligand)`
- **From Design Unit**: receptor is already prepared in DU
- **Adjusting binding site size**: use `OESetInnerContourLevel()` to expand/contract cavity
- **Disabling inner contour**: use `OEToggleReceptorInnerContour()` for very flexible docking

### POSIT Options
- **Molecules with invertible nitrogens**: use `OEPositOptions.SetIgnoreNitrogenStereo(True)`
- **Multiple receptor conformations**: use `OEPosit.AddReceptor()` multiple times
- **Single best pose**: use `OEPosit.Dock()` returns `OESinglePoseResult`
- **Multiple ranked poses**: use `OEPosit.DockMulti(mol, num_poses)` returns `OEMultiPoseResult`

### Result Handling
- **Getting docking score**: use `OEDock.AnnotatePose()` or `OEScore.ScoreLigand()`
- **Getting POSIT probability**: use `OESinglePoseResult.GetProbability()`
- **Getting shape Tanimoto**: use `OEBestOverlayResults.GetTanimoto()`
- **Extracting pose**: use `result.GetPose()` for POSIT or ShapeFit results

## Common Parameters & Types

**OEReceptor**: Prepared protein binding site with grids and constraints
  - Create with: `OEMakeReceptor(receptor, protein, ligand)` or `OEReadReceptorFile(receptor, filename)`
  - Common in: All docking, scoring, and POSIT functions
  - Gotcha: Must be initialized before use; contains protein, ligand, and pre-calculated grids

**OESearchResolution**: Controls docking exhaustiveness vs speed
  - Values: `OESearchResolution_Low`, `OESearchResolution_Standard`, `OESearchResolution_High`
  - Common in: `OEDock` constructor
  - Typical values: Standard for screening, High for final docking

**OEScoreType**: Specifies which scoring function to use
  - Values: `OEScoreType_Chemgauss4` (default), `OEScoreType_Shapegauss`, `OEScoreType_Chemscore`
  - Common in: `OEScore` constructor
  - Typical values: Chemgauss4 for most applications

**OEGraphMol**: OpenEye molecule object (from OEChem)
  - Create with: `oechem.OEGraphMol()` or read from file
  - Common in: All molecule input/output operations
  - Gotcha: Multi-conformer molecules needed for docking; use OEOmega to generate conformers

**OESinglePoseResult**: Result from single-pose POSIT docking
  - Create with: Returned by `OEPosit.Dock()`
  - Methods: `GetPose()` returns molecule, `GetProbability()` returns confidence
  - Common in: POSIT workflows

**OEMultiPoseResult**: Result from multi-pose POSIT docking
  - Create with: Returned by `OEPosit.DockMulti()`
  - Methods: `GetSinglePoseResults()` returns iterator of `OESinglePoseResult`
  - Common in: POSIT workflows needing multiple poses

**OEBestOverlayResults**: Result from ShapeFit overlay
  - Create with: Returned by `OEShapeFit.Overlay()`
  - Methods: `GetOverlayConf()` returns overlaid molecule, `GetTanimoto()` returns shape score
  - Common in: ShapeFit workflows

**OEPositOptions**: Configuration for POSIT docking
  - Create with: `oedocking.OEPositOptions()`
  - Methods: `SetIgnoreNitrogenStereo()`, other configuration methods
  - Common in: Customizing POSIT behavior

## Return Types & Error Handling

```python
# Boolean returns - most setup/initialization functions
receptor = oechem.OEGraphMol()
if not oedocking.OEReadReceptorFile(receptor, "receptor.oeb.gz"):
    oechem.OEThrow.Fatal("Unable to read receptor file")

# Object returns - docking returns new molecule
docked_mol = oechem.OEGraphMol()
dock.DockMultiConformerMolecule(docked_mol, input_mol)
if docked_mol.NumAtoms() == 0:
    print("Docking failed for molecule")

# Float returns - scoring functions
score_value = score.ScoreLigand(pose)
if score_value == float('inf'):
    print("Invalid score - likely clash or error")

# Result objects - POSIT returns structured results
result = posit.Dock(mol)
if result.GetProbability() < 0.1:
    print("Low confidence pose")
else:
    pose = result.GetPose()  # Extract molecule from result

# Iterator returns - multi-pose results
multi_result = posit.DockMulti(mol, 10)
for single_result in multi_result.GetSinglePoseResults():
    prob = single_result.GetProbability()
    pose = single_result.GetPose()
    # Process each pose

# File I/O error handling
ifs = oechem.oemolistream("input.sdf")
if not ifs.IsValid():
    oechem.OEThrow.Fatal("Cannot open input file")