OCDocker.Workbench.OCScoreLayout module

Strict OCScore workspace discovery

OCDocker.Workbench.OCScoreLayout is the supported dashboard data source for OCScore result control and comparison. It intentionally scans the OCScore output layout directly instead of building a generic gallery from every possible metric or artifact file.

The expected root layout is:

output/
  replica_1/
  replica_2/
  replica_3/
  replica_4/
  replica_5/
  ablation/
    no_shape/
      replica_1/
      replica_2/
      replica_3/
      replica_4/
      replica_5/

The scanner also accepts zero-padded replica names such as replica_001 and ablations/ as an alias for ablation/ so existing OCScore outputs can be inspected without being moved. If the served path is the broader OCScore output directory that contains train/, the scanner automatically uses train/ when that is where the replicas and ablations live.

The dashboard keeps a small curated metric set: BEDROC, ROC AUC, PR AUC, EF 1%, EF 5%, best validation metric, RMSE, MAE, and R2. Extra metric names can be requested explicitly through the API, but random numeric columns are not promoted by default.

Useful entry points

ocdocker workbench serve /path/to/ocscore/output --host 127.0.0.1 --port 8765

The local API exposes the strict payload at /api/ocscore-workspace. The browser dashboard at /app renders baseline replicas, ablation studies, study-level replica status, curated metric summaries, generated decision plots, and labeled figures. Figure discovery tags known datasets (dudez, pdbbind, casf, dekois, and lit_pcba), common roles such as SHAP beeswarm, SHAP importance, CV mean/std, CV heatmap, per-target validation, architecture, and performance plots, and curated metric names when they appear in figure filenames. The dashboard filters previews by dataset, role, figure metric, and artifact group so model-comparison plots stay separate from selected-model diagnostics. UI sources live under OCDocker/Workbench/static/ (index.html, app.css, app.js) and are served by OCDocker.Workbench.Web. Generated decision plots expose an explicit result scope selector for test metrics, validation metrics, or both together, and can be exported as SVG plus CSV for paper-ready review. The dashboard still caps large galleries and keeps generated comparison plots visible even when no source image files are present. It is read-only at this stage.

API

Strict OCScore output layout discovery for Workbench dashboards.

OCDocker.Workbench.OCScoreLayout.ablation_container_paths(root)[source]

Return supported ablation container directories under one OCScore layout root.

Parameters:

root (str or pathlib.Path) – User-provided OCScore output root.

Returns:

Existing ablation/ and ablations/ directories when present.

Return type:

tuple[pathlib.Path, …]

OCDocker.Workbench.OCScoreLayout.build_ocscore_workspace(root, *, expected_replica_count=None, max_depth=6, max_metric_file_bytes=1048576, metric_names=())[source]

Build a strict OCScore workspace summary from the canonical layout.

Parameters:

  • root (str or pathlib.Path) – OCScore output root. Baseline replicas are expected directly below this path, with ablation studies below ablation/ or ablations/.

  • expected_replica_count (int or None) – Expected number of replicas per study. When None, each study infers its own count from replica folders and protocol artifacts.

  • max_depth (int) – Maximum recursive depth inside each replica.

  • max_metric_file_bytes (int) – Maximum metric or log file size to inspect.

  • metric_names (tuple[str, ...]) – Optional extra metric names to keep in addition to the curated defaults.

Returns:

Strict OCScore workspace payload for the dashboard and API.

Return type:

WorkbenchOCScoreWorkspace

OCDocker.Workbench.OCScoreLayout.resolve_ocscore_layout_root(root)[source]

Resolve the directory that actually contains OCScore replicas.

Parameters:

root (str or pathlib.Path) – User-provided output root.

Returns:

Layout root used by strict discovery.

Return type:

pathlib.Path

OCDocker.Workbench.OCScoreLayout.resolve_optuna_dashboard_slot_count(root, *, override=None)[source]

Return the Optuna dashboard slot count for one served OCScore root.

When override is omitted, the count follows the baseline replica layout: the greater of detected replica_* directories and n_replicas from protocol artifacts, clamped to MIN_OPTUNA_DASHBOARD_SLOT_COUNT through MAX_OPTUNA_DASHBOARD_SLOT_COUNT.

Parameters:

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

  • override (int or None) – Optional explicit slot count from CLI or API configuration.

Returns:

Resolved Optuna dashboard slot count.

Return type:

int