Usage

This section summarizes common CLI tasks, options, and environment variables.

CLI overview

ocdocker --help
ocdocker <command> --help

Commands

  • Optional dependencies: see Optional dependencies for the install cheat sheet and full extra reference. Minimal commands:

    pip install "ocdocker[docking]"    # vs / pipeline
pip install "ocdocker[db]"         # --store-db
pip install "ocdocker[ml]"         # OCScore ML

  • vs: Dock a single receptor/ligand/box with one engine (vina/smina/plants)

    ocdocker vs \\
  --engine vina \\
  --receptor path/to/receptor.pdb \\
  --ligand path/to/ligand.smi \\
  --box path/to/box0.pdb \\
  --timeout 600 \\
  --store-db

  • pipeline: Multi-engine docking + clustering + rescoring

    ocdocker pipeline \\
  --receptor path/to/receptor.pdb \\
  --ligand path/to/ligand.sdf \\
  --box path/to/box0.pdb \\
  --engines vina,smina,plants \\
  --outdir runs/exp1 \\
  --timeout 900 \\
  --store-db

  • ocscore: Staged OCScore ML pipeline (raw preparation -> train-only feature reduction -> Optuna -> export tools)

    Requires pip install "ocdocker[ml]".

    Full step-by-step replication guide: OCScore replication guide (also OCSCORE_REPLICATION.md in the repo root).

    Bundled protocol YAML and feature-policy data: Bundled OCScore protocol data.

    Minimal commands:

    # Raw input preparation - inputs: .csv, directory, or tar.gz (PDBbind.csv / DUDEz.csv / pipeline_results.csv)
ocdocker ocscore reduce \\
  --pdbbind-archive path/to/PDBbind.csv \\
  --dudez-archive path/to/DUDEz.csv \\
  --output-dir path/to/raw_prepare

# Staged Optuna (development protocol)
ocdocker ocscore train \\
  --protocol development \\
  --raw-input-dir path/to/raw_prepare \\
  --output-dir path/to/optuna_out

# Feature-policy ablation; bundled .yml policies live in OCDocker/OCScore/Protocols/Ablations/
ocdocker ocscore train \
  --protocol production \
  --raw-input-dir path/to/raw_prepare \
  --feature-policy ligand_plus_scoring_function_no_pmi \
  --feature-policy ligand_plus_scoring_function_no_plants \
  --feature-policy ligand_plus_scoring_function_no_shape_size_no_autocorr2d \
  --feature-policy ligand_plus_scoring_function_clean_receptor \
  --output-dir path/to/new_ablations

# Same workflow through the full-pipeline shell runner; the policies above
# are listed in examples/18_run_full_pipeline.sh::FEATURE_POLICY_ABLATIONS.
./examples/18_run_full_pipeline.sh

# Score new pipeline data with an exported best_model bundle
ocdocker ocscore score \\
  --export-dir path/to/replica_000/dudez_optuna/best_model \\
  --raw-archive path/to/new_pipeline.csv \\
  --output-csv path/to/predictions.csv

ocdocker ocscore --help

  • console: Interactive console with tab-completion and history

    Launch via ocdocker console or python -m OCDocker.Console. Importing OCDocker.Console is side-effect-free. API reference: OCDocker.Console package.

    ocdocker console --conf OCDocker.cfg
ocdocker console --conf OCDocker.cfg --ipython

    Inside the console:

    >>> print_args()                 # environment overview
>>> print_args('all')            # all sections
>>> print_args('vina')           # also: smina, plants, gnina, oddt, db, paths

  • doctor: Diagnostics for binaries/deps/DB

    ocdocker doctor --conf OCDocker.cfg

  • init-config: Create a starter OCDocker.cfg or OCDocker.yml from the example

    ocdocker init-config --conf OCDocker.cfg
# or:
ocdocker init-config --conf OCDocker.yml

  • workbench: Validate specs, preflight specs, build run bundles, prepare launch plans, export publication scaffolds, emit starter templates and JSON Schemas, and serve a strict OCScore dashboard over output roots with direct baseline replicas and ablation/ or ablations/ studies. The dashboard reports curated metrics as sortable ablation-table columns, replica status, ablation summaries, dataset/role/metric-filtered figure previews, explicit test/validation/combined generated metric-delta, rank, and replica-stability plots with SVG/CSV export, separated model-comparison versus selected-model figure sections, and a Design tab for composing custom feature-policy ablations without leaving the browser. Design preview and planning stay read-only in the shipped dashboard: the UI emits policy YAML and ocdocker ocscore train commands but does not launch runs itself. The underlying API can launch runs directly via bearer-token-gated /api/jobs* endpoints (vs, pipeline, ocscore train, ocscore reduce) for non-UI/automation clients; see OCDocker.Workbench.Jobs.

    ocdocker workbench template ocscore_study --output study.yml
ocdocker workbench validate study.yml
ocdocker workbench check study.yml
ocdocker workbench build study.yml runs/run-001 --run-id run-001
ocdocker workbench launch-plan runs/run-001 --script-output runs/run-001/run.sh
ocdocker workbench export runs/run-001/run_manifest.yml exports/run-001
# Serve an OCScore output root shaped as train/replica_* plus train/ablations/<study>/replica_*.
# Requires the `api` extra: pip install "ocdocker[api]" (FastAPI/uvicorn).
ocdocker workbench serve /data/hd4tb/OCDocker/data/ocdb2/OCScore/output --host 127.0.0.1 --port 8765
# Open http://127.0.0.1:8765/app after forwarding the port over SSH.
# Dashboard UI sources: OCDocker/Workbench/static/ (index.html, app.css, app.js).
# Old adopted Workbench run_manifest.yml smoke folders are reported as unsupported.
# The dashboard reads /api/ocscore-workspace and stays read-only.
# Use the Design tab or POST /api/ablation-design/features to load descriptor columns
# from raw PDBbind/DUDEz inputs (metadata stripped) and preview custom policies.
ocdocker workbench schema ocscore_study --output ocscore_study.schema.json
ocdocker workbench plan study.yml --run-id run-001 --output plan.json

  • mcp: Serve OCDocker over the Model Context Protocol (MCP) for LLM clients (Claude Code, Claude Desktop, …), proxying tool calls to a running ocdocker workbench serve API over stdio. Workspace inspection, ablation design preview/plan, and job listing/logs are always-available read tools; run_job/cancel_job require the Workbench job bearer token and an explicit confirmation from the calling LLM before anything is launched or cancelled. See OCDocker.MCP.

    # Requires the `mcp` extra: pip install "ocdocker[mcp]".
# Start the Workbench API first, in another terminal:
ocdocker workbench serve /path/to/OCScore/output
# Then, point an MCP client (e.g. Claude Code) at:
ocdocker mcp serve

  • manifest: Generate reproducibility manifest JSON with version metadata

    ocdocker manifest --conf OCDocker.cfg --output reproducibility_manifest.json

    Programmatic API:

    import OCDocker.Toolbox.Reproducibility as ocrepro
manifest = ocrepro.generate_reproducibility_manifest(include_python_packages=False)
_ = ocrepro.write_reproducibility_manifest("reproducibility_manifest.json")

  • script: Run a Python script with OCDocker pre-loaded (requires explicit trust opt-in)

    ocdocker script --conf OCDocker.cfg --allow-unsafe-exec script.py --arg1 value

  • version: Print installed version

    ocdocker version

Global options

All commands accept the following global options:

  • --conf: path to OCDocker.cfg or OCDocker.yml

  • --multiprocess: enable multiprocessing for compatible tasks

  • --no-multiprocess: disable multiprocessing for compatible tasks

  • --update-databases: run DB updates at startup

  • --output-level: control log level (0-5)

  • --overwrite: allow overwriting outputs when applicable

  • --log-file: write logs to a file

  • --no-stdout-log: disable logging to stdout

  • --threads: scheduler-provided worker count; also accepts OCDOCKER_THREADS or SNAKEMAKE_THREADS

  • --tmp-dir: job-local temporary directory; also accepts OCDOCKER_TMP_DIR

Scheduler and Snakemake usage

For workflow managers, prefer explicit per-job resources instead of host autodetection:

ocdocker \
  --threads 4 \
  --tmp-dir tmp/sample_001 \
  pipeline \
  --receptor input/sample_001/receptor.pdbqt \
  --ligand input/sample_001/ligand.pdbqt \
  --box input/sample_001/box.txt \
  --outdir results/sample_001 \
  --engines vina,smina,plants \
  --strict-engines \
  --done-marker results/sample_001/done.json \
  --log-file logs/sample_001.log \
  --no-stdout-log

--strict-engines makes the command fail if any requested docking engine fails. --done-marker writes a small JSON completion marker atomically after summary.json is written. The example Snakefile is available at examples/19_Snakefile_ocdocker_pipeline.smk and can run either native ocdocker or the Docker wrapper ocd through --config ocdocker_command=ocd. The Snakefile also declares examples/envs/ocdocker.yml for --use-conda runs.

For stage-level scheduling, use examples/20_Snakefile_ocdocker_granular_pipeline.smk. It calls ocdocker pipeline prepare, per-engine dock, collect, cluster, rescore, and export as separate Snakemake rules.

Bootstrap & environment

  • Imports are side-effect-free. CLI/application code calls explicit bootstrap before runtime state is used.

  • Environment variables:

    • OCDOCKER_CONFIG: config file path

    • OCDOCKER_DB_BACKEND / DB_BACKEND: select backend (postgresql, mysql, sqlite)

    • OCDOCKER_SQLITE_PATH: explicit SQLite database file path

    • OCDOCKER_TIMEOUT: default timeout (seconds) for external tools

    • OCDOCKER_SKIP_ODDT: skip importing ODDT during bootstrap

    • OCDOCKER_ALLOW_SCRIPT_EXEC: allow trusted in-process script execution

    • OCDOCKER_ALLOW_UNSAFE_DESERIALIZATION: allow trusted pickle/joblib/torch deserialization

  • For trusted scripts that need deserialization, use:

    from OCDocker.Toolbox.Security import allow_unsafe_runtime
allow_unsafe_runtime(deserialization=True, script_exec=False)

Database storage with --store-db explicitly initializes DB access and creates tables. Missing PostgreSQL/MySQL databases are created only through explicit setup intent; SQLite remains the recommended backend for tests and quick local runs.

See OCDocker.Initialise module for details.

Further reading