OCDocker.OCScore.Utils.DUDEzSplit module

Receptor- and kind-aware train/validation/test splitting for DUDEz screening.

Strategies:

  • receptor_heldout_complete (staged OCScore default): assigns complete receptor cases (all ligands + all decoys) to train, validation, or test. No receptor appears in more than one split. Validation and test are used for grouped early-enrichment metrics on unseen receptors.

  • receptor_stratified_kind: splits ligands and decoys separately within each receptor (historical row-wise stratification per receptor).

  • receptor_held_out: fraction-based receptor hold-out (historical).

  • random_row: global row shuffle (not recommended for grouped metrics).

class OCDocker.OCScore.Utils.DUDEzSplit.DUDEzSplitConfig(strategy='receptor_stratified_kind', receptor_column='receptor', kind_column='kind', positive_kind='ligands', negative_kind='decoys', train_size=0.6, validation_size=0.2, test_size=0.2, random_seed=42, relaxed_split=False, min_kind_per_split=1, train_receptors=None, validation_receptors=None, test_receptors=None, n_train_receptors=31, n_validation_receptors=6, n_test_receptors=6, balance_by='ligands', shuffle_within_splits=True)[source]

Bases: object

Configuration for DUDEz train/validation/test splitting.

Parameters:

  • strategy (str, optional) – Split strategy. See DUDEZ_SPLIT_STRATEGIES. Default is receptor_stratified_kind for backward compatibility when constructing this dataclass directly; staged OCScore uses receptor_heldout_complete.

  • receptor_column (str, optional) – Receptor/target column, by default "receptor".

  • kind_column (str, optional) – Ligand/decoy kind column, by default "kind".

  • positive_kind (str, optional) – Canonical positive kind label for logging, by default "ligands".

  • negative_kind (str, optional) – Canonical negative kind label for logging, by default "decoys".

  • train_size (float, optional) – Training fraction for fraction-based strategies, by default 0.6.

  • validation_size (float, optional) – Validation fraction for fraction-based strategies, by default 0.2.

  • test_size (float, optional) – Test fraction for fraction-based strategies, by default 0.2.

  • random_seed (int, optional) – Random seed for deterministic splits, by default 42.

  • relaxed_split (bool, optional) – When False, raise if validity constraints cannot be met. When True, apply documented fallbacks, by default False.

  • min_kind_per_split (int, optional) – Minimum samples per kind in a receptor split when possible (stratified strategy only), by default 1.

  • train_receptors (list[str] | None, optional) – Explicit training receptors for receptor_heldout_complete.

  • validation_receptors (list[str] | None, optional) – Explicit validation receptors for receptor_heldout_complete.

  • test_receptors (list[str] | None, optional) – Explicit test receptors for receptor_heldout_complete.

  • n_train_receptors (int, optional) – Target training receptor count when lists are not provided, by default 31.

  • n_validation_receptors (int, optional) – Target validation receptor count, by default 6.

  • n_test_receptors (int, optional) – Target test receptor count, by default 6.

  • balance_by (str, optional) – Receptor ordering key for greedy assignment: "ligands" (default), "decoys", or "rows".

  • shuffle_within_splits (bool, optional) – Shuffle rows within each split after receptor assignment, by default True.

strategy: str = 'receptor_stratified_kind'
receptor_column: str = 'receptor'
kind_column: str = 'kind'
positive_kind: str = 'ligands'
negative_kind: str = 'decoys'
train_size: float = 0.6
validation_size: float = 0.2
test_size: float = 0.2
random_seed: int = 42
relaxed_split: bool = False
min_kind_per_split: int = 1
train_receptors: list[str] | None = None
validation_receptors: list[str] | None = None
test_receptors: list[str] | None = None
n_train_receptors: int = 31
n_validation_receptors: int = 6
n_test_receptors: int = 6
balance_by: str = 'ligands'
shuffle_within_splits: bool = True
class OCDocker.OCScore.Utils.DUDEzSplit.DUDEzSplitResult(train_idx, val_idx, test_idx, diagnostics=<factory>)[source]

Bases: object

Indices and diagnostics from a DUDEz split.

Parameters:

  • train_idx (np.ndarray) – Training row indices.

  • val_idx (np.ndarray) – Validation row indices.

  • test_idx (np.ndarray) – Test row indices.

  • diagnostics (dict[str, Any]) – JSON-compatible split diagnostics and constraint reporting.

train_idx: ndarray
val_idx: ndarray
test_idx: ndarray
diagnostics: dict[str, Any]
OCDocker.OCScore.Utils.DUDEzSplit.dudez_receptor_heldout_complete_config(random_seed=42, *, n_train_receptors=31, n_validation_receptors=6, n_test_receptors=6, receptor_column='receptor', kind_column='kind', train_receptors=None, validation_receptors=None, test_receptors=None, relaxed_split=False, balance_by='ligands')[source]

Return a DUDEzSplitConfig for complete receptor hold-out splitting.

Parameters:

  • random_seed (int, optional) – Random seed, by default 42.

  • n_train_receptors (int, optional) – Training receptor count when lists are omitted, by default 31.

  • n_validation_receptors (int, optional) – Validation receptor count, by default 6.

  • n_test_receptors (int, optional) – Test receptor count, by default 6.

  • receptor_column (str, optional) – Receptor column name, by default "receptor".

  • kind_column (str, optional) – Kind column name, by default "kind".

  • train_receptors (list[str] | None, optional) – Explicit training receptors.

  • validation_receptors (list[str] | None, optional) – Explicit validation receptors.

  • test_receptors (list[str] | None, optional) – Explicit test receptors.

  • relaxed_split (bool, optional) – Allow incomplete receptors to be excluded, by default False.

  • balance_by (str, optional) – Greedy balancing key, by default "ligands".

Returns:

Configured split definition for staged DUDEz Optuna.

Return type:

DUDEzSplitConfig

OCDocker.OCScore.Utils.DUDEzSplit.split_dudez_by_receptor_and_kind(df, config=None, *, receptor_column=None, kind_column=None, positive_kind=None, negative_kind=None, train_size=None, validation_size=None, test_size=None, random_seed=None, relaxed_split=None)[source]

Split a DUDEz dataframe by receptor and ligand/decoy kind.

Parameters:

  • df (pd.DataFrame) – DUDEz dataframe with receptor and kind columns.

  • config (DUDEzSplitConfig | None, optional) – Split configuration. Individual keyword arguments override fields when both are provided.

  • receptor_column (str | None, optional) – Override for config.receptor_column.

  • kind_column (str | None, optional) – Override for config.kind_column.

  • positive_kind (str | None, optional) – Override for config.positive_kind (logging only).

  • negative_kind (str | None, optional) – Override for config.negative_kind (logging only).

  • train_size (float | None, optional) – Override for config.train_size.

  • validation_size (float | None, optional) – Override for config.validation_size.

  • test_size (float | None, optional) – Override for config.test_size.

  • random_seed (int | None, optional) – Override for config.random_seed.

  • relaxed_split (bool | None, optional) – Override for config.relaxed_split.

Returns:

Train/validation/test indices and diagnostics.

Return type:

DUDEzSplitResult

Raises:

ValueError – If fractions are invalid, required columns are missing, or strict validity constraints cannot be satisfied.