| ---
|
| configs:
|
| - config_name: chains
|
| data_files:
|
| - split: train
|
| path: chains/train-*
|
| - split: valid
|
| path: chains/valid-*
|
| - split: test
|
| path: chains/test-*
|
| - config_name: complexes
|
| data_files:
|
| - split: train
|
| path: complexes/train-*
|
| - split: valid
|
| path: complexes/valid-*
|
| - split: test
|
| path: complexes/test-*
|
| ---
|
|
|
| # PDB-Chain-Complex-Benchmark-Rigor
|
|
|
| Rigor rebuild of `Synthyra/PDB-Chain-Complex-Benchmark` with split assignments
|
| recomputed from the published chain and complex parquet artifacts.
|
|
|
| ## Split Policy
|
|
|
| Splits are assigned by connected components over exact sequence, sequence hash,
|
| 30% sequence cluster, structure cluster, source split component, same-PDB
|
| asymmetric-unit membership, chain assembly membership, and biological assembly
|
| co-membership from the complex rows. The target is 90/5/5 by component count.
|
|
|
| The rebuild hard-fails before upload if any chain or complex member leaks across
|
| train, validation, and test by chain UID, sequence, sequence hash, 30% sequence
|
| cluster, structure cluster, or recomputed split component.
|
|
|
| Chains shorter than `min_sequence_length` or containing `X` residues when
|
| `exclude_sequences_with_x=true` are removed before graph construction. Biological
|
| assembly rows containing any removed member chain are dropped rather than
|
| published as partial complexes.
|
|
|
| Complex list-valued payload columns are regenerated from the chain table during
|
| the rebuild, then asserted directly from the emitted payloads, including
|
| `asymmetric_unit_chain_uids`.
|
|
|
| After writing parquet, the builder reloads the emitted chain and complex shards
|
| and reruns split-routing, payload-consistency, and disjointness checks from the
|
| serialized files.
|
|
|
| This artifact-only rebuild does not rerun Foldseek or MMseqs2. It enforces and
|
| verifies the published cluster labels plus optional external sequence
|
| verification edges when supplied.
|
|
|
| ## Cluster-Balanced PyTorch Sampling
|
|
|
| The training split can be loaded with `streaming=False` and sampled as one
|
| random row per sequence-cluster group per epoch. Chain mode groups by
|
| `sequence_cluster_30`. Complex mode defaults to one sample per member sequence
|
| cluster from `sequence_clusters_30`; set `complex_grouping="cluster_set"` to
|
| sample one row per unique complex cluster signature instead.
|
|
|
| ```python
|
| import collections
|
| import random
|
| from typing import Any, Mapping, Optional
|
|
|
| from datasets import load_dataset
|
| from torch.utils.data import DataLoader, Dataset
|
|
|
|
|
| DEFAULT_REPO_ID = "Synthyra/PDB-Chain-Complex-Benchmark-Rigor"
|
|
|
|
|
| class PDBClusteredDataset(Dataset):
|
| """One randomly selected row per sequence-cluster group per epoch."""
|
|
|
| def __init__(
|
| self,
|
| repo_id: str = DEFAULT_REPO_ID,
|
| mode: str = "chains",
|
| split: str = "train",
|
| seed: int = 0,
|
| epoch: int = 0,
|
| cluster_key: Optional[str] = None,
|
| complex_grouping: str = "member_cluster",
|
| load_kwargs: Optional[Mapping[str, Any]] = None,
|
| ) -> None:
|
| mode_to_config = {
|
| "single": "chains",
|
| "chains": "chains",
|
| "complex": "complexes",
|
| "complexes": "complexes",
|
| }
|
| self.config = mode_to_config[mode]
|
| self.seed = int(seed)
|
| self.cluster_key = cluster_key or (
|
| "sequence_cluster_30" if self.config == "chains" else "sequence_clusters_30"
|
| )
|
| self.complex_grouping = complex_grouping
|
| self.dataset = load_dataset(
|
| repo_id,
|
| self.config,
|
| split=split,
|
| streaming=False,
|
| **dict(load_kwargs or {}),
|
| )
|
| self.groups = self._build_groups()
|
| self.group_keys = sorted(self.groups)
|
| self.set_epoch(epoch)
|
|
|
| def _group_keys_for_value(self, value: Any) -> tuple[tuple[str, ...], ...]:
|
| if self.config == "chains":
|
| return ((str(value),),)
|
|
|
| clusters = tuple(sorted({str(cluster) for cluster in value if str(cluster)}))
|
| if not clusters:
|
| raise ValueError("complex row has no sequence cluster labels")
|
| if self.complex_grouping == "cluster_set":
|
| return (clusters,)
|
| if self.complex_grouping == "member_cluster":
|
| return tuple((cluster,) for cluster in clusters)
|
| raise ValueError("complex_grouping must be 'member_cluster' or 'cluster_set'")
|
|
|
| def _build_groups(self) -> dict[tuple[str, ...], list[int]]:
|
| groups = collections.defaultdict(list)
|
| for row_idx, value in enumerate(self.dataset[self.cluster_key]):
|
| for key in self._group_keys_for_value(value):
|
| groups[key].append(row_idx)
|
| if not groups:
|
| raise ValueError("dataset split contains no rows")
|
| return dict(groups)
|
|
|
| def set_epoch(self, epoch: int) -> None:
|
| self.epoch = int(epoch)
|
| rng = random.Random(self.seed + self.epoch)
|
| self.indices = [rng.choice(self.groups[key]) for key in self.group_keys]
|
|
|
| def __len__(self) -> int:
|
| return len(self.indices)
|
|
|
| def __getitem__(self, index: int) -> Mapping[str, Any]:
|
| return self.dataset[self.indices[index]]
|
|
|
|
|
| def identity_collate(batch: list[Mapping[str, Any]]) -> list[Mapping[str, Any]]:
|
| return batch
|
|
|
|
|
| chains = PDBClusteredDataset(mode="single", split="train", seed=42)
|
| complexes = PDBClusteredDataset(mode="complex", split="train", seed=42)
|
|
|
| chains_loader = DataLoader(chains, batch_size=8, shuffle=False, collate_fn=identity_collate)
|
| complex_loader = DataLoader(complexes, batch_size=2, shuffle=False, collate_fn=identity_collate)
|
|
|
| for epoch in range(3):
|
| chains.set_epoch(epoch)
|
| complexes.set_epoch(epoch)
|
| first_chain_batch = next(iter(chains_loader))
|
| first_complex_batch = next(iter(complex_loader))
|
| ```
|
|
|
| ## Build Metadata
|
|
|
| ```json
|
| {
|
| "batch_size": 16384,
|
| "chain_scan": {
|
| "assembly_membership_edges_seen": 1105293,
|
| "asymmetric_unit_membership_edges_seen": 1037226,
|
| "chains_excluded_contains_x": 24118,
|
| "chains_excluded_too_short": 13084,
|
| "chains_excluded_total": 32222,
|
| "chains_retained": 1037226,
|
| "chains_scanned": 1069448
|
| },
|
| "chain_write": {
|
| "file_counts": {
|
| "test": 1,
|
| "train": 21,
|
| "valid": 1
|
| },
|
| "row_counts": {
|
| "test": 302,
|
| "train": 1036622,
|
| "valid": 302
|
| }
|
| },
|
| "complex_edge_scan": {
|
| "complex_member_edges_seen": 642454,
|
| "complexes_dropped_by_filtered_member": 18838,
|
| "complexes_scanned_for_edges": 344745,
|
| "source_complex_rows_seen": 363583
|
| },
|
| "complex_write": {
|
| "complexes_dropped_by_filtered_member": 18838,
|
| "file_counts": {
|
| "test": 1,
|
| "train": 7,
|
| "valid": 1
|
| },
|
| "member_chain_rows": 987199,
|
| "member_fields": {
|
| "asymmetric_unit_chain_uids": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 923757
|
| },
|
| "chain_uid": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 921450
|
| },
|
| "sequence_clusters_30": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 41718
|
| },
|
| "sequence_hashes": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 166930
|
| },
|
| "sequences": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 166930
|
| },
|
| "split_components": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 6019
|
| },
|
| "structure_clusters": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 44485
|
| }
|
| },
|
| "row_counts": {
|
| "test": 301,
|
| "train": 344140,
|
| "valid": 304
|
| }
|
| },
|
| "component_stats": {
|
| "split_component_count": 6033,
|
| "test_component_count": 302,
|
| "train_component_count": 5429,
|
| "valid_component_count": 302
|
| },
|
| "cpu_count": 32,
|
| "dropped_complex_membership_keys": 18838,
|
| "elapsed_seconds": 77.882,
|
| "exclude_sequences_with_x": true,
|
| "filtered_chain_rows": 32222,
|
| "filtered_complex_rows": 18838,
|
| "foldseek_path": "",
|
| "include_source_split_component_edges": true,
|
| "max_rows_per_shard": 50000,
|
| "min_sequence_length": 10,
|
| "mmseqs_path": "",
|
| "nvidia-smi_path": "C:\\Windows\\system32\\nvidia-smi.EXE",
|
| "nvidia-smi_version": "Mon Jul 6 14:22:11 2026 \n+-----------------------------------------------------------------------------------------+\n| NVIDIA-SMI 580.88 Driver Version: 580.88 CUDA Version: 13.0 |\n+-----------------------------------------+------------------------+----------------------+\n| GPU Name Driver-Model | Bus-Id Disp.A | Volatile Uncorr. ECC |\n| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |\n| | | MIG M. |\n|=========================================+========================+======================|\n| 0 NVIDIA GeForce RTX 4070 ... WDDM | 00000000:01:00.0 On | N/A |\n| N/A 43C P5 8W / 123W | 866MiB / 8188MiB | 26% Default |\n| | | N/A |\n+-----------------------------------------+------------------------+----------------------+\n\n+-----------------------------------------------------------------------------------------+\n| Processes: |\n| GPU GI CI PID Type Process name GPU Memory |\n| ID ID Usage |\n|=========================================================================================|\n| 0 N/A N/A 6516 C+G ...p\\app-3.6.2\\GitHubDesktop.exe N/A |\n| 0 N/A N/A 8844 C+G ...indows\\System32\\ShellHost.exe N/A |\n| 0 N/A N/A 10456 C+G ..._cw5n1h2txyewy\\SearchHost.exe N/A |\n| 0 N/A N/A 13212 C+G ...5n1h2txyewy\\TextInputHost.exe N/A |\n| 0 N/A N/A 21252 C+G ...__2p2nqsd0c76g0\\app\\Codex.exe N/A |\n| 0 N/A N/A 36048 C+G ...Chrome\\Application\\chrome.exe N/A |\n| 0 N/A N/A 41088 C+G ...ntrolPanel\\SystemSettings.exe N/A |\n| 0 N/A N/A 63696 C+G ...8bbwe\\PhoneExperienceHost.exe N/A |\n| 0 N/A N/A 72372 C+G ...y\\StartMenuExperienceHost.exe N/A |\n| 0 N/A N/A 84244 C+G ...xyewy\\ShellExperienceHost.exe N/A |\n| 0 N/A N/A 104536 C+G C:\\Windows\\explorer.exe N/A |\n| 0 N/A N/A 152648 C+G ....0.4022.80\\msedgewebview2.exe N/A |\n| 0 N/A N/A 152984 C+G ...e Experience\\NVIDIA Share.exe N/A |\n| 0 N/A N/A 155976 C+G ...em32\\ApplicationFrameHost.exe N/A |\n| 0 N/A N/A 196292 C+G ...Chrome\\Application\\chrome.exe N/A |\n| 0 N/A N/A 206536 C+G ...2txyewy\\CrossDeviceResume.exe N/A |\n| 0 N/A N/A 221536 C+G ...Files\\Notepad++\\notepad++.exe N/A |\n+-----------------------------------------------------------------------------------------+",
|
| "platform": "Windows-11-10.0.26200-SP0",
|
| "python": "3.12.13",
|
| "quality_filter": {
|
| "drop_complexes_with_filtered_members": true,
|
| "exclude_sequences_with_x": true,
|
| "min_sequence_length": 10
|
| },
|
| "retained_chain_rows": 1037226,
|
| "retained_complex_rows": 344745,
|
| "seed": 42,
|
| "sequence_verification_max_unknown_fraction": 0.0,
|
| "source_chain_rows": 1069448,
|
| "source_complex_rows": 363583,
|
| "source_repo_id": "Synthyra/PDB-Chain-Complex-Benchmark",
|
| "source_snapshot_dir": "C:\\tmp\\hf_pdb_chain_complex_cache\\datasets--Synthyra--PDB-Chain-Complex-Benchmark\\snapshots\\3eb55ee7289dfedfbddf0cde48b68c5395783ccf",
|
| "target_repo_id": "Synthyra/PDB-Chain-Complex-Benchmark-Rigor",
|
| "test_frac": 0.05,
|
| "valid_frac": 0.05
|
| }
|
| ```
|
|
|
| ## Leakage Assertions
|
|
|
| ```json
|
| {
|
| "chains": {
|
| "fields": {
|
| "chain_uid": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 1037226
|
| },
|
| "seqs": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 175111
|
| },
|
| "sequence_cluster_30": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 43208
|
| },
|
| "sequence_hash": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 175111
|
| },
|
| "split_component": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 6033
|
| },
|
| "structure_cluster": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 47196
|
| }
|
| },
|
| "post_write": {
|
| "fields": {
|
| "chain_uid": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 1037226
|
| },
|
| "seqs": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 175111
|
| },
|
| "sequence_cluster_30": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 43208
|
| },
|
| "sequence_hash": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 175111
|
| },
|
| "split_component": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 6033
|
| },
|
| "structure_cluster": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 47196
|
| }
|
| },
|
| "rows": 1037226,
|
| "split_counts": {
|
| "test": 302,
|
| "train": 1036622,
|
| "valid": 302
|
| }
|
| },
|
| "rows": 1037226,
|
| "sequence_verification_edges": {
|
| "checked_edges": 0,
|
| "cross_split_edges": 0,
|
| "provided": false,
|
| "skipped_self_edges": 0,
|
| "skipped_unknown_edges": 0,
|
| "total_edges": 0
|
| },
|
| "split_counts": {
|
| "test": 302,
|
| "train": 1036622,
|
| "valid": 302
|
| }
|
| },
|
| "complexes": {
|
| "member_chain_rows": 987199,
|
| "member_fields": {
|
| "asymmetric_unit_chain_uids": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 923757
|
| },
|
| "chain_uid": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 921450
|
| },
|
| "sequence_clusters_30": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 41718
|
| },
|
| "sequence_hashes": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 166930
|
| },
|
| "sequences": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 166930
|
| },
|
| "split_components": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 6019
|
| },
|
| "structure_clusters": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 44485
|
| }
|
| },
|
| "member_split_consistency": "passed",
|
| "payload_columns_regenerated_from_chains": true,
|
| "post_write": {
|
| "asymmetric_unit_chain_rows": 1541919,
|
| "member_chain_rows": 987199,
|
| "member_fields": {
|
| "asymmetric_unit_chain_uids": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 923757
|
| },
|
| "chain_uid": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 921450
|
| },
|
| "sequence_clusters_30": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 41718
|
| },
|
| "sequence_hashes": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 166930
|
| },
|
| "sequences": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 166930
|
| },
|
| "split_components": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 6019
|
| },
|
| "structure_clusters": {
|
| "crossing_values": 0,
|
| "max_pairwise_overlap": 0,
|
| "unique_values": 44485
|
| }
|
| },
|
| "payload_columns_match_chain_rows": true,
|
| "rows": 344745,
|
| "shard_split_routing": "passed",
|
| "split_counts": {
|
| "test": 301,
|
| "train": 344140,
|
| "valid": 304
|
| }
|
| },
|
| "rows": 344745,
|
| "split_counts": {
|
| "test": 301,
|
| "train": 344140,
|
| "valid": 304
|
| }
|
| }
|
| }
|
| ```
|
|
|
