OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots module

Cross-validation figure generation for exported OCScore models.

Plot cross-validation artifacts written by save_cross_validation_result().

Usage:

from OCDocker.OCScore.Analysis.Plotting import CrossValidationPlots as occvplot

occvplot.save_cross_validation_figures("/path/to/best_model/cross_validation")

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.aggregate_cv_per_target_metrics(per_target)

Average per-receptor metrics across CV folds for plotting.

CV exports one row per (fold_index, group, scorer); this collapses folds into a single row per (group, scorer, scorer_type) with mean metrics.

Parameters:

per_target (DataFrame)

Return type:

DataFrame

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.load_cross_validation_artifacts(cv_dir)

Load JSON/CSV artifacts from a cross-validation output directory.

Parameters:

cv_dir (str | Path) – Cross-validation directory (see resolve_cross_validation_dir()).

Returns:

Keys: cv_dir, results, mean_std, fold_comparison, ocscore_wins, per_target (DataFrames may be empty if files are missing).

Return type:

dict[str, Any]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_fold_metric_heatmap(fold_comparison, metric, *, top_n=25, reference_scorer='OCScore', size=(10, 8))

Heatmap of validation metric values (scorers × folds).

Parameters:

• fold_comparison (pd.DataFrame) – cross_validation_fold_comparison.csv contents.

• metric (str) – Metric name (e.g. BEDROC).

• top_n (int | None, optional) – Limit scorers by mean across folds. Default: 25.

• reference_scorer (str, optional) – Always-included scorer. Default: OCScore.

• size (tuple[float, float], optional) – Figure size in inches.

Return type:

(Figure, Axes)

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_fold_metric_bars(fold_comparison, metric, *, scorers=None, top_n=15, reference_scorer='OCScore', size=(8, 5))

Grouped bar chart of per-fold metric values plus cross-fold mean ± std.

Each x-axis group is one CV fold, except the final group which shows the mean across folds per scorer with standard-deviation error bars.

Parameters:

• fold_comparison (pd.DataFrame) – cross_validation_fold_comparison.csv contents.

• metric (str) – Metric name.

• scorers (Sequence[str] | None, optional) – Explicit scorer list. When None, uses top_n best by mean.

• top_n (int | None, optional) – Used when scorers is None. Default: 15.

• reference_scorer (str, optional) – Highlighted scorer. Default: OCScore.

• size (tuple[float, float], optional) – Figure size in inches.

Return type:

(Figure, Axes)

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_fold_metric_lines(fold_comparison, metric, *, scorers=None, top_n=15, reference_scorer='OCScore', size=(8, 5))

Backward-compatible alias for plot_fold_metric_bars().

Parameters:

• fold_comparison (DataFrame)

• metric (str)

• scorers (Sequence[str] | None)

• top_n (int | None)

• reference_scorer (str)

• size (tuple[float, float])

Return type:

tuple[Figure, Axes]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_mean_std_bars(mean_std, metric, *, top_n=25, reference_scorer='OCScore', width=8.0)

Bar chart of mean ± std per scorer for one metric.

Parameters:

• mean_std (pd.DataFrame) – cross_validation_scorer_mean_std.csv contents.

• metric (str) – Metric name (e.g. BEDROC).

• top_n (int | None, optional) – Maximum scorers to show (OCScore is always included). Default: 25.

• reference_scorer (str, optional) – Highlighted scorer name. Default: OCScore.

• width (float, optional) – Figure width in inches; height scales with the number of scorers.

Return type:

(Figure, Axes)

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_ocscore_wins(ocscore_wins, *, size=(7, 4))

Bar chart of how often OCScore ranked first per metric.

Parameters:

• ocscore_wins (pd.DataFrame) – cross_validation_ocscore_wins.csv contents.

• size (tuple[float, float])

Return type:

(Figure, Axes)

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_per_target_boxplot(per_target, metric, *, split='test', top_n=15, reference_scorer='OCScore', size=(10, 5))

Boxplot of per-receptor metric values for selected scorers.

Parameters:

• per_target (DataFrame)

• metric (str)

• split (str | None)

• top_n (int | None)

• reference_scorer (str)

• size (tuple[float, float])

Return type:

tuple[Figure, Axes]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_per_target_heatmap(per_target, metric, *, split='test', top_n=15, max_groups=None, groups=None, reference_scorer='OCScore', size=(12, 8), annotate=None, annotation_cell_limit=80, title_suffix='', transpose=None)

Heatmap of a metric with scorers on rows and receptors on columns.

Parameters:

• per_target (DataFrame)

• metric (str)

• split (str | None)

• top_n (int | None)

• max_groups (int | None)

• groups (Sequence[str] | None)

• reference_scorer (str)

• size (tuple[float, float])

• annotate (bool | None)

• annotation_cell_limit (int)

• title_suffix (str)

• transpose (bool | None)

Return type:

tuple[Figure, Axes]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.plot_per_target_ocscore_wins(per_target, metric='BEDROC', *, split='test', reference_scorer='OCScore', size=(8, 5))

Bar chart: receptors where OCScore beats each other scorer on metric.

Parameters:

• per_target (DataFrame)

• metric (str)

• split (str | None)

• reference_scorer (str)

• size (tuple[float, float])

Return type:

tuple[Figure, Axes]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.resolve_cross_validation_dir(path)

Resolve a cross-validation directory from an export or CV path.

Parameters:

path (str | Path) – Either <export>/cross_validation or <export>/best_model (or any directory containing cross_validation_results.json).

Returns:

Directory with cross-validation artifacts.

Return type:

Path

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.save_baseline_comparison_figures(comparison_csv, figures_dir=None, *, split='test', metrics=None, top_n=25, dpi=150)

Plot DUDEz baseline comparison CSV from example 19.

Parameters:

• comparison_csv (str | Path) – Path to dudez_sf_baseline_comparison.csv.

• figures_dir (str | Path | None, optional) – Output directory. Default: <csv-parent>/figures.

• split (str, optional) – Split to plot, by default test.

• metrics (Sequence[str] | None, optional) – Metrics to plot. Default: BEDROC and ROC-AUC when present.

• top_n (int | None, optional) – Max scorers per chart. Default: 25.

• dpi (int, optional) – PNG resolution. Default: 150.

Returns:

Map of plot label to written file path.

Return type:

dict[str, str]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.save_calibration_reliability_figures(y_true, logits, figures_dir, *, split='test', calibrator=None, dpi=150)

Write reliability diagrams for OCScore sigmoid and optional calibrated probabilities.

Parameters:

• y_true (np.ndarray) – Binary labels for the split.

• logits (np.ndarray) – Classifier logits.

• figures_dir (str | Path) – Output directory for PNG files.

• split (str, optional) – Split label used in filenames, by default test.

• calibrator (Any | None, optional) – Fitted ProbabilityCalibrator.

• dpi (int, optional) – PNG resolution.

Returns:

Map of plot label to written path.

Return type:

dict[str, str]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.save_cross_validation_figures(cv_dir, figures_dir=None, *, metrics=None, top_n=25, dpi=150)

Generate standard PNG plots from a cross-validation output directory.

Parameters:

• cv_dir (str | Path) – Cross-validation or export directory.

• figures_dir (str | Path | None, optional) – Destination for PNG files. Default: <cv_dir>/figures.

• metrics (Sequence[str] | None, optional) – Metrics to plot. Default: ranking metrics from results JSON (excludes raw TP/TN/FP/FN counts).

• top_n (int | None, optional) – Maximum scoring functions per chart (OCScore always shown). Default: 25.

• dpi (int, optional) – PNG resolution. Default: 150.

Returns:

Map of plot label to written file path.

Return type:

dict[str, str]

OCDocker.OCScore.Analysis.Plotting.CrossValidationPlots.save_per_target_figures(per_target_source, figures_dir, *, split='test', metrics=None, top_n=15, heatmap_top_n=None, max_groups=None, dpi=150)

Generate per-receptor heatmap, boxplot, and OCScore-win charts.

Parameters:

• per_target_source (str | Path | pd.DataFrame) – Path to a per-target CSV or an in-memory table.

• figures_dir (str | Path)

• split (str | None)

• metrics (Sequence[str] | None)

• top_n (int | None)

• heatmap_top_n (int | None)

• max_groups (int | None)

• dpi (int)

Return type:

dict[str, str]