CLI Examples¶
These examples demonstrate how to use OCDocker from the command line.
Basic Docking¶
Example of basic docking operations with Vina:
Basic Vina docking example¶
#!/bin/bash
# Example 1: Basic CLI docking with Vina
# This example shows how to run a simple docking job using the CLI
# Basic docking with Vina
ocdocker vs \
--engine vina \
--receptor ./test_files/test_ptn1/receptor.pdb \
--ligand ./test_files/test_ptn1/compounds/ligands/ligand/ligand.smi \
--box ./test_files/test_ptn1/compounds/ligands/ligand/boxes/box0.pdb \
--outdir ./docking_output \
--timeout 600
# Skip rescoring for faster execution
ocdocker vs \
--engine vina \
--receptor ./test_files/test_ptn1/receptor.pdb \
--ligand ./test_files/test_ptn1/compounds/ligands/ligand/ligand.smi \
--box ./test_files/test_ptn1/compounds/ligands/ligand/boxes/box0.pdb \
--skip-rescore \
--outdir ./docking_output
Multi-Engine Pipeline¶
Example of running a multi-engine docking pipeline:
Multi-engine docking pipeline¶
#!/bin/bash
# Example 2: Multi-engine docking pipeline
# This example shows how to run docking across multiple engines with clustering and rescoring
# Run pipeline with multiple engines
ocdocker pipeline \
--receptor ./test_files/test_ptn1/receptor.pdb \
--ligand ./test_files/test_ptn1/compounds/ligands/ligand/ligand.smi \
--box ./test_files/test_ptn1/compounds/ligands/ligand/boxes/box0.pdb \
--engines vina,smina,plants \
--outdir ./pipeline_output \
--timeout 900
# Pipeline with only Vina and Smina
ocdocker pipeline \
--receptor ./test_files/test_ptn1/receptor.pdb \
--ligand ./test_files/test_ptn1/compounds/ligands/ligand/ligand.smi \
--box ./test_files/test_ptn1/compounds/ligands/ligand/boxes/box0.pdb \
--engines vina,smina \
--outdir ./pipeline_output
# Pipeline with vina, plants, and rescore with all engines
ocdocker pipeline \
--receptor ./test_files/test_ptn1/receptor.pdb \
--ligand ./test_files/test_ptn1/compounds/ligands/ligand/ligand.smi \
--box ./test_files/test_ptn1/compounds/ligands/ligand/boxes/box0.pdb \
--engines vina,plants \
--rescoring-engines vina,smina,plants,oddt \
--outdir ./pipeline_output \
--multiprocess
Diagnostics¶
Example of running diagnostics to check your installation:
Diagnostics script¶
#!/bin/bash
# Example 3: Diagnostics and configuration
# This example shows how to check your OCDocker installation and create configuration files
# Run diagnostics to check installation
ocdocker doctor --conf OCDocker.cfg
# Create a new configuration file from example
ocdocker init-config --conf my_ocdocker.cfg
# Check version
ocdocker version
# Run with custom config file
ocdocker vs \
--conf my_ocdocker.cfg \
--engine vina \
--receptor ./test_files/test_ptn1/receptor.pdb \
--ligand ./test_files/test_ptn1/compounds/ligands/ligand/ligand.smi \
--box ./test_files/test_ptn1/compounds/ligands/ligand/boxes/box0.pdb
Interactive Console¶
Example of using the interactive console:
Interactive console example¶
#!/usr/bin/env python3
"""
Example 4: Using the interactive console
This example shows how to use the OCDocker interactive console for step-by-step workflows
"""
# To use the interactive console, run:
# ocdocker console --conf OCDocker.cfg
# The console provides:
# - Pre-imported OCDocker modules (Receptor, Ligand, Docking classes, etc.)
# - Tab completion for easier exploration
# - Step-by-step execution of docking workflows
# - Access to print_args() function to check configuration
# Example console session:
"""
$ ocdocker console --conf OCDocker.cfg
>>> print_args() # Check current configuration
>>> print_args('paths') # Check binary paths
>>> print_args('vina') # Check Vina parameters
>>> import OCDocker.Receptor as ocr
>>> receptor = ocr.Receptor("./test_files/test_ptn1/receptor.pdb", name="MyReceptor")
>>> import OCDocker.Ligand as ocl
>>> ligand = ocl.Ligand("./test_files/test_ptn1/compounds/ligands/ligand/ligand.smi", name="MyLigand")
>>> import OCDocker.Docking.Vina as ocvina
>>> vina = ocvina.Vina(*parameters)
>>> vina.run_prepare_receptor()
>>> vina.run_prepare_ligand()
>>> vina.run_docking()
"""
Snakemake Pipeline¶
Scheduler-friendly multi-engine pipeline template:
Snakemake multi-engine pipeline¶
# Description
###############################################################################
'''
Snakemake example for running OCDocker as a scheduler-friendly docking job.
Usage:
snakemake -s examples/19_Snakefile_ocdocker_pipeline.smk --cores 4
'''
# Imports
###############################################################################
import os
# License
###############################################################################
'''Copyright (c) Federal University of Rio de Janeiro (UFRJ), Artur Duque Rossi, and Pedro Henrique Monteiro Torres.
SPDX-License-Identifier: BSD-3-Clause
See the LICENSE file for full terms.
'''
# Rules
###############################################################################
SAMPLE = "example"
OCDOCKER_COMMAND = config.get("ocdocker_command", "ocdocker")
rule all:
input:
f"results/{SAMPLE}/summary.json",
f"results/{SAMPLE}/done.json",
rule ocdocker_pipeline:
input:
receptor="input/{sample}/receptor.pdbqt",
ligand="input/{sample}/ligand.pdbqt",
box="input/{sample}/box.txt",
output:
summary="results/{sample}/summary.json",
done="results/{sample}/done.json",
threads: 4
conda:
"envs/ocdocker.yml"
params:
outdir=lambda wildcards, output: os.path.dirname(output.summary),
engines="vina,smina,plants",
rescoring="oddt",
command=OCDOCKER_COMMAND,
resources:
tmpdir=lambda wildcards: f"tmp/{wildcards.sample}",
log:
"logs/{sample}.log",
shell:
r'''
mkdir -p "{resources.tmpdir}" "$(dirname "{log}")"
OCDOCKER_THREADS="{threads}" \
OCDOCKER_TMP_DIR="{resources.tmpdir}" \
{params.command} \
--threads "{threads}" \
--tmp-dir "{resources.tmpdir}" \
pipeline \
--receptor "{input.receptor}" \
--ligand "{input.ligand}" \
--box "{input.box}" \
--outdir "{params.outdir}" \
--engines "{params.engines}" \
--rescoring-engines "{params.rescoring}" \
--strict-engines \
--done-marker "{output.done}" \
--log-file "{log}" \
--no-stdout-log
test -s "{output.summary}"
test -s "{output.done}"
'''
Granular Snakemake Pipeline¶
Stage-granular scheduler template using prepare, dock, collect, cluster, rescore, and export rules:
Granular Snakemake multi-engine pipeline¶
# Description
###############################################################################
'''
Granular Snakemake example for running OCDocker pipeline stages.
Usage:
snakemake -s examples/20_Snakefile_ocdocker_granular_pipeline.smk --cores 12
snakemake -s examples/20_Snakefile_ocdocker_granular_pipeline.smk --cores 12 --config ocdocker_command=ocd
'''
# Imports
###############################################################################
import os
# License
###############################################################################
'''Copyright (c) Federal University of Rio de Janeiro (UFRJ), Artur Duque Rossi, and Pedro Henrique Monteiro Torres.
SPDX-License-Identifier: BSD-3-Clause
See the LICENSE file for full terms.
'''
# Rules
###############################################################################
SAMPLE = config.get("sample", "example")
OCDOCKER_COMMAND = config.get("ocdocker_command", "ocdocker")
DEFAULT_THREADS = int(config.get("threads", 4))
DEFAULT_TIMEOUT = int(config.get("timeout", 900))
RAW_ENGINES = config.get("engines", ["vina", "smina", "plants"])
ENGINES = [engine.strip() for engine in RAW_ENGINES.split(",")] if isinstance(RAW_ENGINES, str) else list(RAW_ENGINES)
RESCORING_ENGINES = config.get("rescoring", ",".join(ENGINES))
rule all:
input:
f"results/granular/{SAMPLE}/summary.json",
rule pipeline_prepare:
input:
receptor="input/{sample}/receptor.pdbqt",
ligand="input/{sample}/ligand.pdbqt",
box="input/{sample}/box.txt",
output:
manifest="results/granular/{sample}/prepare_manifest.json",
done="results/granular/{sample}/prepare.done.json",
threads: 1
conda:
"envs/ocdocker.yml"
params:
command=OCDOCKER_COMMAND,
outdir=lambda wildcards, output: os.path.dirname(output.manifest),
engines=",".join(ENGINES),
resources:
tmpdir=lambda wildcards: f"tmp/granular/{wildcards.sample}/prepare",
log:
"logs/granular/{sample}/prepare.log",
shell:
r'''
mkdir -p "{resources.tmpdir}" "$(dirname "{log}")"
OCDOCKER_THREADS="{threads}" OCDOCKER_TMP_DIR="{resources.tmpdir}" {params.command} --threads "{threads}" --tmp-dir "{resources.tmpdir}" pipeline prepare --receptor "{input.receptor}" --ligand "{input.ligand}" --box "{input.box}" --outdir "{params.outdir}" --engines "{params.engines}" --done-marker "{output.done}" --log-file "{log}" --no-stdout-log
test -s "{output.manifest}"
test -s "{output.done}"
'''
rule pipeline_dock_engine:
input:
prepared=rules.pipeline_prepare.output.manifest,
receptor="input/{sample}/receptor.pdbqt",
ligand="input/{sample}/ligand.pdbqt",
box="input/{sample}/box.txt",
output:
manifest="results/granular/{sample}/{engine}Files/dock_manifest.json",
done="results/granular/{sample}/dock_{engine}.done.json",
threads: DEFAULT_THREADS
conda:
"envs/ocdocker.yml"
params:
command=OCDOCKER_COMMAND,
outdir=lambda wildcards, output: str(os.path.dirname(os.path.dirname(output.manifest))),
timeout=DEFAULT_TIMEOUT,
resources:
tmpdir=lambda wildcards: f"tmp/granular/{wildcards.sample}/dock/{wildcards.engine}",
gpu=lambda wildcards: 1 if wildcards.engine == "gnina" else 0,
log:
"logs/granular/{sample}/dock_{engine}.log",
shell:
r'''
mkdir -p "{resources.tmpdir}" "$(dirname "{log}")"
OCDOCKER_THREADS="{threads}" OCDOCKER_TMP_DIR="{resources.tmpdir}" {params.command} --threads "{threads}" --tmp-dir "{resources.tmpdir}" pipeline dock --receptor "{input.receptor}" --ligand "{input.ligand}" --box "{input.box}" --outdir "{params.outdir}" --engines "{wildcards.engine}" --strict-engines --done-marker "{output.done}" --timeout "{params.timeout}" --log-file "{log}" --no-stdout-log
test -s "{output.manifest}"
test -s "{output.done}"
'''
rule pipeline_collect:
input:
manifests=expand("results/granular/{sample}/{engine}Files/dock_manifest.json", sample=SAMPLE, engine=ENGINES),
output:
inventory="results/granular/{sample}/pose_inventory.csv",
manifest="results/granular/{sample}/collect_manifest.json",
done="results/granular/{sample}/collect.done.json",
threads: 1
conda:
"envs/ocdocker.yml"
params:
command=OCDOCKER_COMMAND,
outdir=lambda wildcards, output: os.path.dirname(output.inventory),
resources:
tmpdir=lambda wildcards: f"tmp/granular/{wildcards.sample}/collect",
log:
"logs/granular/{sample}/collect.log",
shell:
r'''
mkdir -p "{resources.tmpdir}" "$(dirname "{log}")"
{params.command} --threads "{threads}" --tmp-dir "{resources.tmpdir}" pipeline collect --outdir "{params.outdir}" --done-marker "{output.done}" --log-file "{log}" --no-stdout-log
test -s "{output.inventory}"
test -s "{output.manifest}"
test -s "{output.done}"
'''
rule pipeline_cluster:
input:
inventory=rules.pipeline_collect.output.inventory,
output:
manifest="results/granular/{sample}/cluster_manifest.json",
representative="results/granular/{sample}/representative.mol2",
done="results/granular/{sample}/cluster.done.json",
threads: DEFAULT_THREADS
conda:
"envs/ocdocker.yml"
params:
command=OCDOCKER_COMMAND,
outdir=lambda wildcards, output: os.path.dirname(output.manifest),
resources:
tmpdir=lambda wildcards: f"tmp/granular/{wildcards.sample}/cluster",
log:
"logs/granular/{sample}/cluster.log",
shell:
r'''
mkdir -p "{resources.tmpdir}" "$(dirname "{log}")"
{params.command} --threads "{threads}" --tmp-dir "{resources.tmpdir}" pipeline cluster --outdir "{params.outdir}" --done-marker "{output.done}" --log-file "{log}" --no-stdout-log
test -s "{output.manifest}"
test -s "{output.representative}"
test -s "{output.done}"
'''
rule pipeline_rescore:
input:
cluster=rules.pipeline_cluster.output.manifest,
representative=rules.pipeline_cluster.output.representative,
dock_manifests=expand("results/granular/{sample}/{engine}Files/dock_manifest.json", sample=SAMPLE, engine=ENGINES),
output:
results="results/granular/{sample}/rescore_results.json",
done="results/granular/{sample}/rescore.done.json",
threads: DEFAULT_THREADS
conda:
"envs/ocdocker.yml"
params:
command=OCDOCKER_COMMAND,
outdir=lambda wildcards, output: os.path.dirname(output.results),
rescoring=RESCORING_ENGINES,
resources:
tmpdir=lambda wildcards: f"tmp/granular/{wildcards.sample}/rescore",
log:
"logs/granular/{sample}/rescore.log",
shell:
r'''
mkdir -p "{resources.tmpdir}" "$(dirname "{log}")"
{params.command} --threads "{threads}" --tmp-dir "{resources.tmpdir}" pipeline rescore --outdir "{params.outdir}" --rescoring-engines "{params.rescoring}" --done-marker "{output.done}" --log-file "{log}" --no-stdout-log
test -s "{output.results}"
test -s "{output.done}"
'''
rule pipeline_export:
input:
rescore=rules.pipeline_rescore.output.results,
output:
summary="results/granular/{sample}/summary.json",
done="results/granular/{sample}/export.done.json",
threads: 1
conda:
"envs/ocdocker.yml"
params:
command=OCDOCKER_COMMAND,
outdir=lambda wildcards, output: os.path.dirname(output.summary),
resources:
tmpdir=lambda wildcards: f"tmp/granular/{wildcards.sample}/export",
log:
"logs/granular/{sample}/export.log",
shell:
r'''
mkdir -p "{resources.tmpdir}" "$(dirname "{log}")"
{params.command} --threads "{threads}" --tmp-dir "{resources.tmpdir}" pipeline export --outdir "{params.outdir}" --done-marker "{output.done}" --log-file "{log}" --no-stdout-log
test -s "{output.summary}"
test -s "{output.done}"
'''