OCDocker.Workbench.VSDesign module

Design assistant for virtual-screening runs (ocdocker vs and ocdocker pipeline): discover receptor/ligand/box candidates, validate a draft selection, and plan the exact command to run — for one target (*_vs_design*) or a multi-sample batch (*_vs_campaign*). Mirrors OCDocker.Workbench.AblationDesign, but for docking runs instead of OCScore training. Read-only: nothing here writes files or executes commands — the plan output is handed to OCDocker.Workbench.Jobs.JobManager.launch() (via run_job/plan_job) to actually run.

OCDocker.Workbench.VSDesign.discover_vs_campaign_candidates(root, *, input_dir=None, sample_scan_depth=3)[source]

Discover a draft multi-sample manifest from an input/{sample}/... layout.

Matches the convention used by examples/19_Snakefile_ocdocker_pipeline.smk and examples/20_Snakefile_ocdocker_granular_pipeline.smk: one subdirectory per sample directly under the scan root, each containing a receptor/ligand/box file. Best-effort — a workspace not organized this way yields an empty manifest with an explanatory issue, not an error; the caller can still hand-author a manifest directly.

Parameters:

  • root (str or pathlib.Path) – Served Workbench root.

  • input_dir (str, pathlib.Path, or None) – Optional subdirectory to scan instead of the whole served root (typically an input/ directory containing one folder per sample). When omitted, root/input is used automatically if present, otherwise root itself.

  • sample_scan_depth (int) – Maximum directory depth below each sample directory to descend while looking for its receptor/ligand/box files.

Returns:

JSON-safe payload: manifest (list of draft rows), scan_root, issues.

Return type:

dict[str, Any]

OCDocker.Workbench.VSDesign.discover_vs_design_candidates(root, *, input_dir=None, max_depth=6)[source]

Discover receptor/ligand/box candidates under a workspace.

Best-effort, depth-limited scan by filename/extension heuristics — there is no single fixed input layout in OCDocker, unlike OCScore’s raw_prepare/. Results are candidates for the caller to choose from, never a hard requirement; an empty or ambiguous scan is not an error.

Parameters:

  • root (str or pathlib.Path) – Served Workbench root.

  • input_dir (str, pathlib.Path, or None) – Optional subdirectory to scan instead of the whole served root.

  • max_depth (int) – Maximum directory depth below the scan root to descend.

Returns:

JSON-safe payload: candidates (receptors, ligands, boxes), scan_root, issues.

Return type:

dict[str, Any]

OCDocker.Workbench.VSDesign.plan_vs_campaign(root, body)[source]

Build the vs_campaign job payload for a valid draft manifest.

Parameters:

  • root (str or pathlib.Path) – Served Workbench root, used to resolve relative paths.

  • body (dict[str, Any]) – Same manifest shape as preview_vs_campaign(), plus optional common settings: engine ("shell" default, or "snakemake" for real DAG orchestration — see OCDocker.Workbench.Jobs.build_campaign_snakemake_command()), cores (engine="snakemake" only, default OCDocker.Workbench.Jobs.DEFAULT_CAMPAIGN_CORES), outdir (shared base output directory — every row still writes to its own <outdir>/<sample>, never a single shared directory), timeout, store_db, and cwd (the campaign job’s working directory).

Returns:

{"kind": "vs_campaign", "engine", "manifest", "args", "cwd", "shell_command"} (plus "cores" for engine="snakemake") — ready to pass directly to OCDocker.Workbench.Jobs.JobManager.launch() (or the run_job/plan_job API and MCP tools).

Return type:

dict[str, Any]

Raises:

ValueError – If the draft is not valid (call preview_vs_campaign() first) or engine is unrecognized.

OCDocker.Workbench.VSDesign.plan_vs_design(root, body)[source]

Build the exact ocdocker vs/pipeline argv for a valid draft.

Parameters:

  • root (str or pathlib.Path) – Served Workbench root, used to resolve relative paths.

  • body (dict[str, Any]) – Same draft shape as preview_vs_design(), plus optional all_boxes, name, outdir, timeout, store_db, and (vs only) skip_rescore/skip_split, or (pipeline only) cluster_min/cluster_max/cluster_step/strict_engines.

Returns:

{"kind", "args", "cwd", "shell_command"} — args and kind are ready to pass directly to OCDocker.Workbench.Jobs.JobManager.launch() (or the run_job/plan_job API and MCP tools).

Return type:

dict[str, Any]

Raises:

ValueError – If the draft is not valid (call preview_vs_design() first).

OCDocker.Workbench.VSDesign.preview_vs_campaign(root, body)[source]

Validate a draft multi-sample VS campaign manifest without running anything.

Parameters:

  • root (str or pathlib.Path) – Served Workbench root, used to resolve relative paths.

  • body (dict[str, Any]) – Draft campaign: manifest — a non-empty list of rows, each shaped like discover_vs_campaign_candidates()’s output rows (sample, row_kind, receptor, ligand, box, engines, optional rescoring_engines).

Returns:

{"valid", "errors", "warnings", "resolved": {"rows": [...]}}.

Return type:

dict[str, Any]

OCDocker.Workbench.VSDesign.preview_vs_design(root, body)[source]

Validate one draft VS design without running anything.

Parameters:

  • root (str or pathlib.Path) – Served Workbench root, used to resolve relative paths.

  • body (dict[str, Any]) – Draft design: kind ("vs" or "pipeline"), receptor, ligand, box (paths), plus kind-specific fields — engine (vs) or engines/rescoring_engines (pipeline).

Returns:

{"valid", "errors", "warnings", "resolved"}.

Return type:

dict[str, Any]