Python API Examples

These examples demonstrate how to use OCDocker programmatically through the Python API.

Vina Docking

Complete example of using Vina for docking:

Vina docking example

#!/usr/bin/env python3
"""
Example 5: Python API - Vina docking
This example shows how to use OCDocker programmatically with Vina
"""

import os

from OCDocker.Docking.Vina import Vina
from OCDocker.Ligand import Ligand
from OCDocker.Receptor import Receptor

# Set configuration if needed
# os.environ['OCDOCKER_CONFIG'] = 'path/to/OCDocker.cfg'

# Create receptor object
receptor = Receptor(
    "./test_files/receptor.pdb",
    name="MyReceptor"
)

# Create ligand object
ligand = Ligand(
    "./test_files/compounds/ligands/ligand/ligand.smi",
    name="MyLigand"
)

# Define paths
ligand_path = "./test_files/compounds/ligands/ligand"
receptor_path = "./test_files"

# Create Vina docking object
vina = Vina(
    config_path=f"{ligand_path}/vinaFiles/conf_vina.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=f"{receptor_path}/prepared_receptor.pdbqt",
    ligand=ligand,
    prepared_ligand_path=f"{ligand_path}/prepared_ligand.pdbqt",
    vina_log=f"{ligand_path}/vinaFiles/vina.log",
    output_vina=f"{ligand_path}/vinaFiles/vina.pdbqt",
    name="Vina receptor-ligand"
)

# Prepare receptor (converts PDB to PDBQT)
vina.run_prepare_receptor()

# Prepare ligand (converts SMILES/SDF to PDBQT)
vina.run_prepare_ligand()

# Run docking
vina.run_docking()

# Split poses into individual files
vina.split_poses(f"{ligand_path}/vinaFiles", logFile="")

# Run rescoring (optional)
# Note: run_rescore requires both outPath and ligand parameters
# Use the output file from docking (contains all poses) for rescoring
vina.run_rescore(f"{ligand_path}/vinaFiles", vina.output_vina, skipDefaultScoring=True)

# Read docking results
docking_results = vina.read_log()
print("Docking results:", docking_results)

# Read rescoring results
rescoring_results = vina.read_rescore_logs(f"{ligand_path}/vinaFiles")
print("Rescoring results:", rescoring_results)

# Get docked poses
poses = vina.get_docked_poses()
print(f"Found {len(poses)} poses")

Smina Docking

Example of using Smina for docking and rescoring:

Smina docking example

#!/usr/bin/env python3
"""
Example 6: Python API - Smina docking
This example shows how to use OCDocker programmatically with Smina
"""

import os

from OCDocker.Docking.Smina import Smina
from OCDocker.Ligand import Ligand
from OCDocker.Receptor import Receptor

# Create receptor and ligand objects
receptor = Receptor("./test_files/receptor.pdb", name="MyReceptor")
ligand = Ligand("./test_files/compounds/ligands/ligand/ligand.smi", name="MyLigand")

# Define paths
ligand_path = "./test_files/compounds/ligands/ligand"
receptor_path = "./test_files"

# Create Smina docking object
smina = Smina(
    config_path=f"{ligand_path}/sminaFiles/conf_smina.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=f"{receptor_path}/prepared_receptor.pdbqt",
    ligand=ligand,
    prepared_ligand_path=f"{ligand_path}/prepared_ligand.pdbqt",
    smina_log=f"{ligand_path}/sminaFiles/smina.log",
    output_smina=f"{ligand_path}/sminaFiles/smina.pdbqt",
    name="Smina receptor-ligand"
)

# Prepare receptor (check if already prepared to avoid unnecessary work)
if not os.path.isfile(f"{receptor_path}/prepared_receptor.pdbqt"):
    smina.run_prepare_receptor()

# Prepare ligand
if not os.path.isfile(f"{ligand_path}/prepared_ligand.pdbqt"):
    smina.run_prepare_ligand()

# Run docking
smina.run_docking()

# Run rescoring with Smina
# Note: run_rescore requires both outPath and ligand parameters
# Use the output file from docking (contains all poses) for rescoring
smina.run_rescore(f"{ligand_path}/sminaFiles", smina.output_smina, skipDefaultScoring=True)

# Read results
docking_results = smina.read_log()
rescoring_results = smina.read_rescore_logs(f"{ligand_path}/sminaFiles")

print("Smina docking results:", docking_results)
print("Smina rescoring results:", rescoring_results)

# Alternative: Use Smina only for rescoring (if docking was done with Vina)
# from OCDocker.Docking.Vina import Vina
# vina = Vina(...)
# vina.run_docking()
# docking_poses = vina.get_docked_poses()
# 
# # Rescore Vina poses with Smina
# from OCDocker.Docking.Smina import run_rescore
# for scoring_function in smina_scoring_functions:
#     run_rescore(
#         smina.config,
#         docking_poses,
#         f"{ligand_path}/sminaFiles",
#         scoring_function,
#         splitLigand=False
#     )

PLANTS Docking

Example of using PLANTS for docking:

PLANTS docking example

#!/usr/bin/env python3
"""
Example 7: Python API - PLANTS docking
This example shows how to use OCDocker programmatically with PLANTS
"""

import os

from OCDocker.Docking.PLANTS import PLANTS
from OCDocker.Ligand import Ligand
from OCDocker.Receptor import Receptor

# Create receptor and ligand objects
receptor = Receptor("./test_files/receptor.pdb", name="MyReceptor")
ligand = Ligand("./test_files/compounds/ligands/ligand/ligand.smi", name="MyLigand")

# Define paths
ligand_path = "./test_files/compounds/ligands/ligand"
receptor_path = "./test_files"

# Create PLANTS docking object
# Note: PLANTS uses MOL2 format instead of PDBQT
plants = PLANTS(
    config_path=f"{ligand_path}/plantsFiles/conf_plants.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=f"{receptor_path}/prepared_receptor.mol2",
    ligand=ligand,
    prepared_ligand_path=f"{ligand_path}/prepared_ligand.mol2",
    plants_log=f"{ligand_path}/plantsFiles/plants.log",
    output_plants=f"{ligand_path}/plantsFiles",
    name="PLANTS receptor-ligand"
)

# Prepare receptor (converts to MOL2)
plants.run_prepare_receptor()

# Prepare ligand (converts to MOL2)
plants.run_prepare_ligand()

# Run docking
plants.run_docking()

# Read docking results
docking_results = plants.read_log(onlyBest=False)
print("PLANTS docking results:", docking_results)

# Get docked poses
docking_poses = plants.get_docked_poses()

# Write pose list for rescoring
pose_list = plants.write_pose_list()

# Run rescoring
plants.run_rescore(pose_list, logFile="", overwrite=False)

# Read rescoring results
rescoring_results = plants.read_rescore_logs(onlyBest=False)
print("PLANTS rescoring results:", rescoring_results)

ODDT Rescoring

Example of using ODDT for rescoring:

ODDT rescoring example

#!/usr/bin/env python3
"""
Example 8: Python API - ODDT rescoring
This example shows how to use ODDT for rescoring docked poses
Note: ODDT is used only for rescoring, so docking must be done first
"""

import os

from OCDocker.Docking.Vina import Vina
from OCDocker.Ligand import Ligand
from OCDocker.Receptor import Receptor
from OCDocker.Rescoring.ODDT import df_to_dict, run_oddt

# First, perform docking (using Vina as example)
receptor = Receptor("./test_files/receptor.pdb", name="MyReceptor")
ligand = Ligand("./test_files/compounds/ligands/ligand/ligand.smi", name="MyLigand")

ligand_path = "./test_files/compounds/ligands/ligand"
receptor_path = "./test_files"

# Create and run Vina docking
vina = Vina(
    config_path=f"{ligand_path}/vinaFiles/conf_vina.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=f"{receptor_path}/prepared_receptor.pdbqt",
    ligand=ligand,
    prepared_ligand_path=f"{ligand_path}/prepared_ligand.pdbqt",
    vina_log=f"{ligand_path}/vinaFiles/vina.log",
    output_vina=f"{ligand_path}/vinaFiles/vina.pdbqt",
    name="Vina receptor-ligand"
)

vina.run_prepare_receptor()
vina.run_prepare_ligand()
vina.run_docking()

# Get docked poses
docked_poses = vina.get_docked_poses()

# Run ODDT rescoring
# This will compute various scoring functions (RFScore, NNScore, PLEC, etc.)
# Note: run_oddt requires prepared receptor path, prepared ligand paths (list), ligand name, and output path
oddt_results_df = run_oddt(
    preparedReceptorPath=vina.prepared_receptor,
    preparedLigandPath=docked_poses,  # List of docked pose file paths
    ligandName=vina.input_ligand.name,
    outputPath=f"{ligand_path}/oddt"
)

# Convert DataFrame to dictionary if needed
oddt_results_dict = df_to_dict(oddt_results_df)

print("ODDT rescoring results (DataFrame):")
print(oddt_results_df)
print("\nODDT rescoring results (Dictionary):")
print(oddt_results_dict)

RMSD Clustering

Example of clustering poses from multiple engines:

RMSD clustering example

#!/usr/bin/env python3
"""
Example 9: Python API - RMSD clustering
This example shows how to cluster docked poses from multiple engines using RMSD
"""

import os
from OCDocker.Docking.PLANTS import PLANTS
from OCDocker.Docking.Vina import Vina
from OCDocker.Ligand import Ligand
from OCDocker.Processing.Preprocessing.RmsdClustering import cluster_rmsd, get_medoids
from OCDocker.Receptor import Receptor
from OCDocker.Toolbox.MoleculeProcessing import get_rmsd_matrix

# Perform docking with multiple engines
receptor = Receptor("./test_files/receptor.pdb", name="MyReceptor")
ligand = Ligand("./test_files/compounds/ligands/ligand/ligand.smi", name="MyLigand")

ligand_path = "./test_files/compounds/ligands/ligand"
receptor_path = "./test_files"

# Run Vina docking
vina = Vina(
    config_path=f"{ligand_path}/vinaFiles/conf_vina.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=f"{receptor_path}/prepared_receptor.pdbqt",
    ligand=ligand,
    prepared_ligand_path=f"{ligand_path}/prepared_ligand.pdbqt",
    vina_log=f"{ligand_path}/vinaFiles/vina.log",
    output_vina=f"{ligand_path}/vinaFiles/vina.pdbqt",
    name="Vina receptor-ligand"
)

vina.run_prepare_receptor()
vina.run_prepare_ligand()
vina.run_docking()
vina_docking_results = vina.read_log()
vina_poses = vina.get_docked_poses()

# Run PLANTS docking
plants = PLANTS(
    config_path=f"{ligand_path}/plantsFiles/conf_plants.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=f"{receptor_path}/prepared_receptor.mol2",
    ligand=ligand,
    prepared_ligand_path=f"{ligand_path}/prepared_ligand.mol2",
    plants_log=f"{ligand_path}/plantsFiles/plants.log",
    output_plants=f"{ligand_path}/plantsFiles",
    name="PLANTS receptor-ligand"
)

plants.run_prepare_receptor()
plants.run_prepare_ligand()
plants.run_docking()
plants_docking_results = plants.read_log(onlyBest=False)
plants_poses = plants.get_docked_poses()

# Combine poses from all engines
all_poses = vina_poses + plants_poses

# Calculate RMSD matrix
rmsd_matrix = get_rmsd_matrix(all_poses)

# Perform clustering
clusters = cluster_rmsd(
    rmsd_matrix,
    algorithm='agglomerativeClustering',
    outputPlot="./clustering_plot.png"  # Optional: save visualization
)

# Get medoids (representative poses from each cluster)
medoids = get_medoids(rmsd_matrix, clusters, onlyBiggest=True)

print(f"Found {len(clusters)} clusters")
print(f"Selected {len(medoids)} medoids")

# Create dictionary mapping medoids to their docking scores
medoids_dict = {}
for medoid in medoids:
    if medoid in vina_poses:
        # Find index of medoid in vina_poses
        medoid_idx = vina_poses.index(medoid)
        medoids_dict[medoid] = {
            'engine': 'vina',
            'score': vina_docking_results[medoid_idx]
        }
    elif medoid in plants_poses:
        medoid_idx = plants_poses.index(medoid)
        medoids_dict[medoid] = {
            'engine': 'plants',
            'score': plants_docking_results[medoid_idx]
        }

print("\nMedoids with scores:")
for pose, info in medoids_dict.items():
    print(f"{pose}: {info}")

Complete Workflow

End-to-end workflow example combining multiple operations:

Complete workflow example

#!/usr/bin/env python3
"""
Example 10: Complete workflow - Multi-engine docking, clustering, and rescoring
This example demonstrates a complete virtual screening workflow
"""

import os
from OCDocker.Docking.Smina import Smina
from OCDocker.Docking.Vina import Vina
from OCDocker.Ligand import Ligand
from OCDocker.Processing.Preprocessing.RmsdClustering import cluster_rmsd, get_medoids
from OCDocker.Receptor import Receptor
from OCDocker.Toolbox.MoleculeProcessing import get_rmsd_matrix

# Step 1: Create receptor and ligand objects
receptor = Receptor("./test_files/receptor.pdb", name="MyReceptor")
ligand = Ligand("./test_files/compounds/ligands/ligand/ligand.smi", name="MyLigand")

ligand_path = "./test_files/compounds/ligands/ligand"
receptor_path = "./test_files"

# Step 2: Prepare receptor (only once, can be reused)
receptor_pdbqt = f"{receptor_path}/prepared_receptor.pdbqt"
if not os.path.isfile(receptor_pdbqt):
    # Use Vina to prepare receptor (any engine can do this)
    temp_vina = Vina(
        config_path=f"{ligand_path}/vinaFiles/conf_vina.txt",
        box_file=f"{ligand_path}/boxes/box.pdb",
        receptor=receptor,
        prepared_receptor_path=receptor_pdbqt,
        ligand=ligand,
        prepared_ligand_path=f"{ligand_path}/prepared_ligand.pdbqt",
        vina_log=f"{ligand_path}/vinaFiles/temp.log",
        output_vina=f"{ligand_path}/vinaFiles/temp.pdbqt",
        name="temp"
    )
    temp_vina.run_prepare_receptor()

# Step 3: Prepare ligand
ligand_pdbqt = f"{ligand_path}/prepared_ligand.pdbqt"
if not os.path.isfile(ligand_pdbqt):
    temp_vina = Vina(
        config_path=f"{ligand_path}/vinaFiles/conf_vina.txt",
        box_file=f"{ligand_path}/boxes/box.pdb",
        receptor=receptor,
        prepared_receptor_path=receptor_pdbqt,
        ligand=ligand,
        prepared_ligand_path=ligand_pdbqt,
        vina_log=f"{ligand_path}/vinaFiles/temp.log",
        output_vina=f"{ligand_path}/vinaFiles/temp.pdbqt",
        name="temp"
    )
    temp_vina.run_prepare_ligand()

# Step 4: Run docking with Vina
print("Running Vina docking...")
vina = Vina(
    config_path=f"{ligand_path}/vinaFiles/conf_vina.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=receptor_pdbqt,
    ligand=ligand,
    prepared_ligand_path=ligand_pdbqt,
    vina_log=f"{ligand_path}/vinaFiles/vina.log",
    output_vina=f"{ligand_path}/vinaFiles/vina.pdbqt",
    name="Vina receptor-ligand"
)
vina.run_docking()
vina_results = vina.read_log()
vina_poses = vina.get_docked_poses()
print(f"Vina: Found {len(vina_poses)} poses")

# Step 5: Run docking with Smina
print("Running Smina docking...")
smina = Smina(
    config_path=f"{ligand_path}/sminaFiles/conf_smina.txt",
    box_file=f"{ligand_path}/boxes/box.pdb",
    receptor=receptor,
    prepared_receptor_path=receptor_pdbqt,
    ligand=ligand,
    prepared_ligand_path=ligand_pdbqt,
    smina_log=f"{ligand_path}/sminaFiles/smina.log",
    output_smina=f"{ligand_path}/sminaFiles/smina.pdbqt",
    name="Smina receptor-ligand"
)
smina.run_docking()
smina_results = smina.read_log()
smina_poses = smina.get_docked_poses()
print(f"Smina: Found {len(smina_poses)} poses")

# Step 6: Combine poses and cluster by RMSD
print("Clustering poses by RMSD...")
all_poses = vina_poses + smina_poses
rmsd_matrix = get_rmsd_matrix(all_poses)
clusters = cluster_rmsd(
    rmsd_matrix,
    algorithm='agglomerativeClustering',
    outputPlot="./workflow_clustering.png"
)

# Step 7: Get medoids (representative poses)
medoids = get_medoids(rmsd_matrix, clusters, onlyBiggest=True)
print(f"Found {len(medoids)} representative poses (medoids)")

# Step 8: Rescore medoids with Smina
print("Rescoring medoids with Smina...")
# Note: run_rescore requires both outPath and ligand parameters
smina.run_rescore(f"{ligand_path}/sminaFiles", smina.output_smina, skipDefaultScoring=True)
rescoring_results = smina.read_rescore_logs(f"{ligand_path}/sminaFiles")

# Step 9: Summary
print("\n=== Workflow Summary ===")
print(f"Total poses from all engines: {len(all_poses)}")
print(f"Number of clusters: {len(set(clusters.values()))}")
print(f"Selected medoids: {len(medoids)}")
print(f"Best Vina score: {min(vina_results) if vina_results else 'N/A'}")
print(f"Best Smina score: {min(smina_results) if smina_results else 'N/A'}")

print("\nWorkflow completed successfully!")