Optional dependencies¶

Brief overview¶

OCDocker splits Python dependencies into a minimal core and optional extras. Install only what your workflow needs; add extras when a command or module requires heavier libraries.

Cheat sheet

pip install ocdocker                      # minimal core
pip install "ocdocker[docking]"           # vs / pipeline
pip install "ocdocker[db]"                # --store-db
pip install "ocdocker[ml]"                # OCScore ML
pip install "ocdocker[analysis]"          # plots / statistics
pip install "ocdocker[workflow]"          # Snakemake
pip install "ocdocker[all]"               # all runtime stacks
pip install "ocdocker[full]"              # all runtime + docs build
pip install "ocdocker[dev]"               # pytest, mypy, ruff
pip install -e ".[all,dev]"               # typical developer setup

Typical combinations

Single-engine docking → ocdocker[docking]
Multi-engine pipeline with dendrogram PNG → ocdocker[docking,analysis]
OCScore replication → ocdocker[ml] (often ocdocker[all] for full parity)
Editable development → pip install -e ".[all,dev]"

If a command fails with ModuleNotFoundError, the CLI suggests the matching extra (for example pip install "ocdocker[ml]" for missing torch).

See Installation for conda/system prerequisites and Usage for CLI workflows that depend on each extra.

Design and rationale¶

Why a lightweight core?¶

pip install ocdocker should work quickly in CI, headless servers, and environments where you only need configuration, manifests, or doctor checks. Scientific stacks (RDKit, PyTorch, matplotlib) are large, platform-sensitive, and not needed to import the base package or run ocdocker --help.

The core therefore includes only utilities shared across many code paths:

Core dependencies (always installed)¶
Package	Role in OCDocker
`configargparse`	CLI/config parsing helpers
`joblib`	Serialization for masks and sklearn-style artifacts in OCScore I/O
`packaging`	Version and distribution metadata
`pydantic`, `pydantic-settings`	Structured configuration (reserved for typed settings)
`pyyaml`	YAML configuration files (`OCDocker.yml`)
`requests`	HTTP downloads and remote resources
`rich`	Optional enhanced console logging (falls back to stdlib logging)
`tqdm`	Progress bars in processing and download utilities

Everything else is grouped by workflow into pip extras defined in pyproject.toml. Extras can overlap (numpy appears in docking, ml, and analysis); pip deduplicates installed packages.

Lazy imports and CLI hints¶

Optional modules are imported only when you run the matching command or import the matching submodule. If a dependency is missing, the CLI prints a short hint such as:

Error: missing optional dependency 'torch' required for OCScore pipeline.
Install with: pip install "ocdocker[ml]"

Plotting in RMSD clustering uses lazy matplotlib imports; clustering itself runs with [docking] only, while dendrogram PNG output needs [analysis].

Extra reference¶

Runtime extras¶

docking

Chemistry and the numeric stack for virtual screening and pipeline clustering.

Chemistry: rdkit, openbabel-wheel, biopython, spyrmsd
Numeric / clustering: numpy, pandas, scipy, scikit-learn

Required for ocdocker vs, ocdocker pipeline, and Python imports such as OCDocker.Ligand and OCDocker.Receptor.

db

SQLAlchemy and database drivers for PostgreSQL and MySQL.

sqlalchemy, sqlalchemy-utils, psycopg, pymysql

Required when using --store-db or OCDocker.DB against server backends. SQLite is recommended for development/testing/small local runs; PostgreSQL/MySQL are recommended for persistent, concurrent, or long-running workflows. Missing DB drivers report the install hint pip install "ocdocker[db]".

ml

OCScore machine-learning pipeline (PyTorch, XGBoost, Optuna).

Frameworks: torch, torchaudio, torchvision, xgboost
Tuning / viz: optuna, optuna-dashboard, optuna-integration, torchsummary, torchviz, visualtorch
Shared numeric stack: numpy, pandas, scipy, scikit-learn

Required for ocdocker ocscore and OCDocker.OCScore training/export paths.

analysis

Plotting, statistics, explainability, and extended scientific I/O.

Plotting: matplotlib, seaborn, graphviz
Statistics / explainability: statsmodels, pingouin, dcor, lime, shap
Graphs / imaging: networkx, rustworkx, scikit-image, h5py, imageio, pillow, tifffile
Notebook / symbolic: ipython, sympy, mpmath, gmpy2
Acceleration / utilities: numba, llvmlite, fsspec
Numeric (standalone analysis installs): numpy, pandas, scipy

Required for OCScore plotting/SHAP visualization, statistical reports, and pipeline dendrogram PNGs (clustering_dendrogram.png). Clustering math itself lives in [docking]; plots live in [analysis].

workflow

Snakemake integration and logging plugins. Also enables the vs_campaign job kind’s engine="snakemake" option (real DAG orchestration for multi-sample batches, see OCDocker.Workbench package and OCDocker.MCP package) — invoked as python -m snakemake against the same interpreter running ocdocker workbench serve, not a bare snakemake resolved from PATH.

snakemake, snakemake-logger-plugin-snkmt

cloud

Optional cloud storage backends.

boto3, google-cloud-storage, dropbox

gpu

GPU array acceleration (non-macOS).

cupy-cuda11x (platform marker excludes Darwin)

api

FastAPI/uvicorn stack for the Workbench HTTP API.

fastapi, uvicorn

Required for ocdocker workbench serve. The Workbench browser dashboard and JSON API are unavailable without this extra.

mcp

MCP server exposing the Workbench API to LLM clients (Claude Code, Claude Desktop, …) over stdio.

mcp

Required for ocdocker mcp serve. Requires a running ocdocker workbench serve instance to connect to.

Aggregate and tooling extras¶

all: Union of runtime extras: docking + db + ml + analysis + workflow + cloud + gpu + api + mcp. Use when you want every runtime feature without documentation build tools.
full: all plus docs (Sphinx, Furo, MyST, themes). Use to build this documentation locally with make -C docs html.
docs: Sphinx documentation build only (subset of full).
dev: Developer tooling: pytest, pytest-cov, pytest-order, coverage, mypy, ruff, pre-commit, detect-secrets. Combine with runtime extras, e.g. pip install -e ".[all,dev]".
build: PyPI release tooling: build, twine, wheel, setuptools.

Command and feature map¶

User action	Recommended install	Notes
`import OCDocker` / `ocdocker version`	core only	No scientific stack required
`ocdocker doctor` (basic)	core; add extras for full dep checks	Doctor reports missing optional imports
`ocdocker vs`	`[docking]`	RDKit/OpenBabel at ligand import time
`ocdocker pipeline` (clustering only)	`[docking]`	RMSD clustering uses sklearn/scipy
`ocdocker pipeline` (dendrogram PNG)	`[docking,analysis]`	Matplotlib loaded lazily when plotting
`ocdocker vs\|pipeline --store-db`	add `[db]`	SQLAlchemy + driver for your backend
`ocdocker ocscore …`	`[ml]`	PyTorch/Optuna/XGBoost stack
OCScore plots / SHAP exports	`[ml,analysis]` or `[all]`	Seaborn/matplotlib in analysis modules
Snakemake workflows	`[workflow]`	External `snakemake` CLI still required on PATH
`ocdocker workbench serve`	`[api]`	FastAPI/uvicorn; dashboard is unavailable without it
`ocdocker mcp serve`	`[mcp]`	Connects to a running `ocdocker workbench serve`; needs `[api]` there too
Local Sphinx docs	`[full]` or `[docs]` + runtime as needed	See Installation
Running the test suite	`[all,dev]` (typical CI layout)	Tests import docking/db/ml modules

Combining extras¶

List multiple extras in one install command:

pip install "ocdocker[docking,db,ml]"

Editable installs from a git checkout use the same syntax:

pip install -e ".[docking,analysis]"

Upgrading from older installs¶

Earlier releases installed many scientific packages as core dependencies. Current releases move them into extras:

Previously in core	Now install via
`numpy`, `pandas`, `scipy`, `scikit-learn`	`[docking]` and/or `[ml]`
`matplotlib`, `seaborn`, `statsmodels`, `shap`, …	`[analysis]`
`torch`, `optuna`, `xgboost`, …	`[ml]` (unchanged extra name)
`rdkit`, `openbabel-wheel`, …	`[docking]` (unchanged)
`sqlalchemy`, …	`[db]` (unchanged)

If scripts break after upgrading, install the extras your workflow used implicitly before, or switch to [all] for parity with a full historical environment.

requirements.txt in the repository root mirrors core only; optional stacks are selected via pip extras, not a monolithic requirements file. Packaged YAML protocols and Workbench static assets are declared under [tool.setuptools.package-data] in pyproject.toml (see Bundled OCScore protocol data).

Troubleshooting¶

``ModuleNotFoundError`` after upgrade: Install the extra suggested in the CLI message. For Python API use, import the submodule only after installing the matching extra.
Pipeline runs but no dendrogram PNG: Install [analysis]. Without matplotlib, clustering completes but plot generation is skipped with a warning.
``ocdocker –help`` works but docking fails: Expected: help does not require RDKit. Run pip install "ocdocker[docking]".
CI / reproducible environments: Pin extras explicitly in your environment file, e.g. pip install "ocdocker[all,dev]", rather than relying on transitive pins from an old monolithic core.
Source of truth: Extras and version constraints are defined in pyproject.toml under [project.dependencies] and [project.optional-dependencies]. Packaging tests in tests/cli/test_packaging_metadata.py keep requirements.txt aligned with the core list.

Contributor formatting rules (line length 120, multiline TOML, long Python list constants) are in Development conventions.