OCDocker.OCScore.Utils.FixedOuterSplit module

Fixed outer train/validation/test splits for the unified OCScore modeling protocol.

One outer split is created before replicas; feature reduction is fit only on the outer-train partition; all replicas reuse the same split assignments.

class OCDocker.OCScore.Utils.FixedOuterSplit.FixedOuterSplitAssignment(outer_split_id, outer_split_seed, pdbbind_train_indices, pdbbind_validation_indices, pdbbind_test_indices, dudez_train_indices, dudez_validation_indices, dudez_test_indices, pdbbind_train_indices_hash, pdbbind_validation_indices_hash, pdbbind_test_indices_hash, dudez_train_indices_hash, dudez_validation_indices_hash, dudez_test_indices_hash, outer_split_assignment_hash, feature_selection_scope='train_only', feature_selection_fit_split='train', feature_selection_fit_row_count=0, feature_selection_split_hash='', selected_features_hash='', removed_features_hash='', feature_reduction_artifact_path=None, replica_uses_fixed_outer_split=True, notes=<factory>)[source]

Bases: object

Frozen outer split shared by all replicas.

Parameters:

  • outer_split_id (str)

  • outer_split_seed (int)

  • pdbbind_train_indices (list[int])

  • pdbbind_validation_indices (list[int])

  • pdbbind_test_indices (list[int])

  • dudez_train_indices (list[int])

  • dudez_validation_indices (list[int])

  • dudez_test_indices (list[int])

  • pdbbind_train_indices_hash (str)

  • pdbbind_validation_indices_hash (str)

  • pdbbind_test_indices_hash (str)

  • dudez_train_indices_hash (str)

  • dudez_validation_indices_hash (str)

  • dudez_test_indices_hash (str)

  • outer_split_assignment_hash (str)

  • feature_selection_scope (str)

  • feature_selection_fit_split (str)

  • feature_selection_fit_row_count (int)

  • feature_selection_split_hash (str)

  • selected_features_hash (str)

  • removed_features_hash (str)

  • feature_reduction_artifact_path (str | None)

  • replica_uses_fixed_outer_split (bool)

  • notes (list[str])

outer_split_id: str
outer_split_seed: int
pdbbind_train_indices: list[int]
pdbbind_validation_indices: list[int]
pdbbind_test_indices: list[int]
dudez_train_indices: list[int]
dudez_validation_indices: list[int]
dudez_test_indices: list[int]
pdbbind_train_indices_hash: str
pdbbind_validation_indices_hash: str
pdbbind_test_indices_hash: str
dudez_train_indices_hash: str
dudez_validation_indices_hash: str
dudez_test_indices_hash: str
outer_split_assignment_hash: str
feature_selection_scope: str = 'train_only'
feature_selection_fit_split: str = 'train'
feature_selection_fit_row_count: int = 0
feature_selection_split_hash: str = ''
selected_features_hash: str = ''
removed_features_hash: str = ''
feature_reduction_artifact_path: str | None = None
replica_uses_fixed_outer_split: bool = True
notes: list[str]
to_dict()[source]

Serialize split assignments and integrity hashes for JSON export.

Returns:

Fixed outer split payload suitable for fixed_outer_split.json.

Return type:

dict[str, Any]

classmethod from_dict(payload)[source]

Reconstruct a split assignment from serialized JSON metadata.

Parameters:

payload (Mapping[str, Any]) – Dictionary previously produced by to_dict().

Returns:

Parsed assignment with unknown keys ignored.

Return type:

FixedOuterSplitAssignment

OCDocker.OCScore.Utils.FixedOuterSplit.build_fixed_outer_split_assignment(*, outer_split_seed, pdbbind_train_indices, pdbbind_validation_indices, pdbbind_test_indices, dudez_train_indices, dudez_validation_indices, dudez_test_indices, feature_selection_fit_row_count, selected_features, removed_features, feature_reduction_artifact_path=None, outer_split_id=None)[source]

Build a fixed outer split record with deterministic hashes.

Parameters:

  • outer_split_seed (int)

  • pdbbind_train_indices (Sequence[int] | ndarray)

  • pdbbind_validation_indices (Sequence[int] | ndarray)

  • pdbbind_test_indices (Sequence[int] | ndarray)

  • dudez_train_indices (Sequence[int] | ndarray)

  • dudez_validation_indices (Sequence[int] | ndarray)

  • dudez_test_indices (Sequence[int] | ndarray)

  • feature_selection_fit_row_count (int)

  • selected_features (Sequence[str])

  • removed_features (Sequence[str])

  • feature_reduction_artifact_path (str | None)

  • outer_split_id (str | None)

Return type:

FixedOuterSplitAssignment

OCDocker.OCScore.Utils.FixedOuterSplit.build_replica_split_alignment_metadata(fixed, *, replica_seed, replica_name, pdbbind_split_indices, selected_features, dudez_split_indices=None)[source]

Build per-replica split-alignment metadata for protocol logs.

Parameters:

  • fixed (FixedOuterSplitAssignment)

  • replica_seed (int)

  • replica_name (str)

  • pdbbind_split_indices (dict[str, list[int]])

  • selected_features (Sequence[str])

  • dudez_split_indices (dict[str, list[int]] | None)

Return type:

dict[str, Any]

OCDocker.OCScore.Utils.FixedOuterSplit.validate_protocol_integrity(*, feature_selection, fixed_outer_split, replica_alignments, raw_input_hashes=None)[source]

Validate unified OCScore training protocol metadata and fail on invalid runs.

Parameters:

  • feature_selection (dict[str, Any] | None) – Train-only feature-selection metadata from the modeling run.

  • fixed_outer_split (dict[str, Any] | FixedOuterSplitAssignment | None) – Fixed outer split metadata shared by all replicas.

  • replica_alignments (Sequence[dict[str, Any]]) – Per-replica split and selected-feature alignment records.

  • raw_input_hashes (dict[str, Any] | None, optional) – Content hashes for raw modeling inputs.

Returns:

Protocol metadata asserting a valid leakage-safe training run.

Return type:

dict[str, Any]

Raises:

ValueError – If train-only scope, split hashes, or replica alignment checks fail.

OCDocker.OCScore.Utils.FixedOuterSplit.load_fixed_outer_split(source)[source]

Load a fixed outer split assignment from a directory or JSON file.

Parameters:

source (str | Path)

Return type:

FixedOuterSplitAssignment

OCDocker.OCScore.Utils.FixedOuterSplit.validate_replica_split_alignment(fixed, *, replica_name, pdbbind_split_indices, selected_features, dudez_split_indices=None, strict=True)[source]

Validate that a replica reused the fixed outer split and selected features.

Parameters:

  • fixed (FixedOuterSplitAssignment)

  • replica_name (str)

  • pdbbind_split_indices (dict[str, list[int]])

  • selected_features (Sequence[str])

  • dudez_split_indices (dict[str, list[int]] | None)

  • strict (bool)

Return type:

None

OCDocker.OCScore.Utils.FixedOuterSplit.write_fixed_outer_split_json(output_dir, assignment)[source]

Write fixed_outer_split.json to output_dir.

Parameters:
Return type:

Path