Name model-selection splits validation in drug tasks

Use validation terminology in both drug tasks, tutorials and documentation. Add validation_label_file and validation_cell_file options with legacy aliases, and write the validation prediction field while retaining notebook support for older outputs. Keep data partitions, training behavior, dataset paths, weights and PKL files unchanged.

BioMod/README.md

@@ -15,8 +15,8 @@ files, and plotting helpers.
 | Annotation | Supervised cell-type annotation workflows |
 | Integration | Zero-shot batch integration and UMAP/scIB-style reporting |
 | Perturbation | Norman gene-perturbation tutorial and smoke workflow |
-| Drug response | Single-drug response prediction with GDSC/CCLE data |
-| Drug combinations | Drug-combination synergy prediction with independent-set evaluation |
+| Drug response | Single-drug response prediction with GDSC/CCLE data and validation-based model selection |
+| Drug combinations | Drug-combination synergy prediction with validation-based model selection |
 | Figures | Notebook-level PDF/PNG/SVG plotting cells for paper and GitHub display |
 
 ## Repository Layout

BioMod/drug_combination/README.md

@@ -27,10 +27,13 @@ data_summary/
 |-- new_cell_features_954.csv    # Training cell features (30 cell lines x 954 genes)
 |-- smiles_0_10.csv              # Drug SMILES
 `-- test_data/
-    |-- independent_input.csv              # Independent test labels (668 samples)
-    `-- independent_cell_features_954.csv  # Test cell features (1020 cell lines x 954 genes)
+    |-- independent_input.csv              # Validation labels (668 samples)
+    `-- independent_cell_features_954.csv  # Validation cell features (1020 cell lines x 954 genes)
 ```
 
+The directory name `test_data/` is retained for compatibility. These files are
+used as the validation set for checkpoint selection.
+
 ## Dependencies
 
 - PyTorch
@@ -106,11 +109,13 @@ python train_drug_combination_performer_module.py \
 | `--hyper_params_path` | Required | Path to the PerformerModule hyper-parameter pkl file |
 | `--module_data_dir` | None | Directory containing module data files |
 | `--data_dir` | `./data_summary` | Data directory |
+| `--validation_label_file` | `test_data/independent_input.csv` | Validation labels for checkpoint selection; legacy alias: `--test_label_file` |
+| `--validation_cell_file` | `test_data/independent_cell_features_954.csv` | Validation cell features; legacy alias: `--test_cell_file` |
 | `--batch_size` | 256 | Training batch size |
 | `--lr` | 1e-4 | Learning rate |
 | `--epochs` | 100 | Number of training epochs |
 | `--n_folds` | 5 | Number of folds |
-| `--domain_gen` | True | Domain generalization mode: train on the full training set and evaluate on the independent test set |
+| `--domain_gen` | True | Domain generalization mode: train on the full training set and select checkpoints using a separate validation set |
 | `--eval_interval` | 5 | Evaluate every N epochs |
 | `--pool_method` | mean | PerformerModule pooling method (`mean`, `max`, or `concat`) |
 | `--cache_emb` | True | Cache cell embeddings to a `.npy` file |
@@ -120,11 +125,18 @@ python train_drug_combination_performer_module.py \
 
 Results are saved under `--output_dir` (default: `./results/`):
 
-- `best_model_fold{i}.pt` - best model weights for each fold
-- `fpr_tpr_fold{i}.pkl` - FPR/TPR curve data for drawing ROC curves
+- `best_model_fold{i}.pt` - model weights selected by the highest validation AUC for each fold
+- `fpr_tpr_fold{i}.pkl` - validation FPR/TPR curve data for drawing ROC curves
 - `cell_emb_cache_{pool_method}.npy` - cached PerformerModule cell embeddings
 
 ## Evaluation Metrics
 
 Every `--eval_interval` epochs, the script evaluates AUC, PR_AUC, ACC, BACC,
-PREC, TPR, and KAPPA, matching scLong.
+PREC, TPR, and KAPPA on the validation set, matching scLong's metric definitions.
+The checkpoint with the highest validation AUC is saved for each fold. In
+`--no_domain_gen` mode, each held-out fold serves as the validation set.
+
+This naming update preserves the data, splits, checkpoint-selection behavior,
+output filenames, metric column names, and legacy dataset cache IDs. It does not
+create or evaluate an independent final test set; the reported values are
+validation results used during model selection, not final test estimates.

BioMod/drug_combination/train_drug_combination_performer_module.py

@@ -610,10 +610,14 @@ def main():
                         default=os.path.join(SCRIPT_DIR, 'data_summary'))
     parser.add_argument('--label_file', type=str, default='new_labels_0_10.csv')
     parser.add_argument('--cell_file', type=str, default='new_cell_features_954.csv')
-    parser.add_argument('--test_label_file', type=str,
-                        default='test_data/independent_input.csv')
-    parser.add_argument('--test_cell_file', type=str,
-                        default='test_data/independent_cell_features_954.csv')
+    parser.add_argument('--validation_label_file', '--test_label_file',
+                        dest='validation_label_file', type=str,
+                        default='test_data/independent_input.csv',
+                        help='Validation labels used for checkpoint selection; --test_label_file is a legacy alias')
+    parser.add_argument('--validation_cell_file', '--test_cell_file',
+                        dest='validation_cell_file', type=str,
+                        default='test_data/independent_cell_features_954.csv',
+                        help='Validation cell features; --test_cell_file is a legacy alias')
 
     # Training args
     parser.add_argument('--batch_size', type=int, default=256)
@@ -621,7 +625,7 @@ def main():
     parser.add_argument('--epochs', type=int, default=100)
     parser.add_argument('--n_folds', type=int, default=5)
     parser.add_argument('--domain_gen', action='store_true', default=True,
-                        help='Domain generalization: train full set, test on independent set')
+                        help='Domain generalization: train full set, validate on a separate set for checkpoint selection')
     parser.add_argument('--no_domain_gen', dest='domain_gen', action='store_false')
     parser.add_argument('--eval_interval', type=int, default=5)
     parser.add_argument('--output_dir', type=str,
@@ -651,12 +655,12 @@ def main():
     train_cell_df = load_cell_features(train_cell_file)
     print_sys(f'Loaded train cell features: {train_cell_df.shape}')
 
-    test_cell_file = os.path.join(args.data_dir, args.test_cell_file)
-    test_cell_df = load_cell_features(test_cell_file)
-    print_sys(f'Loaded test cell features: {test_cell_df.shape}')
+    validation_cell_file = os.path.join(args.data_dir, args.validation_cell_file)
+    validation_cell_df = load_cell_features(validation_cell_file)
+    print_sys(f'Loaded validation cell features: {validation_cell_df.shape}')
 
     # Combine all cell lines and remove duplicates
-    all_cell_df = pd.concat([train_cell_df, test_cell_df])
+    all_cell_df = pd.concat([train_cell_df, validation_cell_df])
     all_cell_df = all_cell_df[~all_cell_df.index.duplicated(keep='first')]
     print_sys(f'Total unique cell lines: {len(all_cell_df)}')
 
@@ -691,13 +695,13 @@ def main():
     train_labels = pd.read_csv(train_label_path)
     print_sys(f'Train labels: {len(train_labels)} samples')
 
-    test_label_path = os.path.join(args.data_dir, args.test_label_file)
-    test_labels = pd.read_csv(test_label_path)
-    print_sys(f'Test labels: {len(test_labels)} samples')
+    validation_label_path = os.path.join(args.data_dir, args.validation_label_file)
+    validation_labels = pd.read_csv(validation_label_path)
+    print_sys(f'Validation labels: {len(validation_labels)} samples')
 
     all_smiles = set(
         train_labels['drug1'].tolist() + train_labels['drug2'].tolist()
-        + test_labels['drug1'].tolist() + test_labels['drug2'].tolist()
+        + validation_labels['drug1'].tolist() + validation_labels['drug2'].tolist()
     )
     smile_graph = {}
     failed = []
@@ -737,20 +741,21 @@ def main():
         cell_emb_dict=cell_emb_dict, smile_graph=smile_graph,
     )
 
-    # Test datasets (independent set)
-    drug1_test = test_labels['drug1'].tolist()
-    drug2_test = test_labels['drug2'].tolist()
-    cells_test = test_labels['cell'].tolist()
-    labels_test = test_labels['label'].tolist()
+    # Validation datasets (separate set used for checkpoint selection)
+    # Preserve legacy test_* cache IDs to reuse existing preprocessed datasets.
+    drug1_validation = validation_labels['drug1'].tolist()
+    drug2_validation = validation_labels['drug2'].tolist()
+    cells_validation = validation_labels['cell'].tolist()
+    labels_validation = validation_labels['label'].tolist()
 
-    test_d1_dataset = TestbedDataset(
+    validation_d1_dataset = TestbedDataset(
         root=args.data_dir, dataset='test_drug1_performer_module',
-        xd=drug1_test, xt=cells_test, y=labels_test,
+        xd=drug1_validation, xt=cells_validation, y=labels_validation,
         cell_emb_dict=cell_emb_dict, smile_graph=smile_graph,
     )
-    test_d2_dataset = TestbedDataset(
+    validation_d2_dataset = TestbedDataset(
         root=args.data_dir, dataset='test_drug2_performer_module',
-        xd=drug2_test, xt=cells_test, y=labels_test,
+        xd=drug2_validation, xt=cells_validation, y=labels_validation,
         cell_emb_dict=cell_emb_dict, smile_graph=smile_graph,
     )
 
@@ -766,33 +771,33 @@ def main():
         print_sys(f'{"=" * 60}')
 
         if args.domain_gen:
-            # Domain generalization: train on full train set, test on independent set
+            # Domain generalization: train on full training set, select on validation set
             d1_train_data = train_d1_dataset
-            d1_test_data = test_d1_dataset
+            d1_validation_data = validation_d1_dataset
             d2_train_data = train_d2_dataset
-            d2_test_data = test_d2_dataset
+            d2_validation_data = validation_d2_dataset
         else:
             # Standard k-fold cross-validation
-            test_num = random_num[pot * fold_i : pot * (fold_i + 1)]
+            validation_num = random_num[pot * fold_i : pot * (fold_i + 1)]
             train_num = (
                 random_num[: pot * fold_i] + random_num[pot * (fold_i + 1) :]
             )
             d1_train_data = train_d1_dataset[train_num]
-            d1_test_data = train_d1_dataset[test_num]
+            d1_validation_data = train_d1_dataset[validation_num]
             d2_train_data = train_d2_dataset[train_num]
-            d2_test_data = train_d2_dataset[test_num]
+            d2_validation_data = train_d2_dataset[validation_num]
 
         d1_loader_train = DataLoader(
             d1_train_data, batch_size=args.batch_size, shuffle=None, pin_memory=True,
         )
-        d1_loader_test = DataLoader(
-            d1_test_data, batch_size=args.batch_size, shuffle=None, pin_memory=True,
+        d1_loader_validation = DataLoader(
+            d1_validation_data, batch_size=args.batch_size, shuffle=None, pin_memory=True,
         )
         d2_loader_train = DataLoader(
             d2_train_data, batch_size=args.batch_size, shuffle=None, pin_memory=True,
         )
-        d2_loader_test = DataLoader(
-            d2_test_data, batch_size=args.batch_size, shuffle=None, pin_memory=True,
+        d2_loader_validation = DataLoader(
+            d2_validation_data, batch_size=args.batch_size, shuffle=None, pin_memory=True,
         )
 
         model = GCNNet(cell_emb_dim=cell_emb_dim).to(device)
@@ -819,7 +824,7 @@ def main():
             loss_history.append(avg_loss)
 
             if epoch % args.eval_interval == 0:
-                T, S, Y = predict(model, device, d1_loader_test, d2_loader_test)
+                T, S, Y = predict(model, device, d1_loader_validation, d2_loader_validation)
                 m = evaluate_metrics(T, S, Y)
                 metric_history.append({'epoch': epoch, **m})
 
@@ -830,10 +835,10 @@ def main():
                         args.output_dir, f'best_model_fold{fold_i}.pt'
                     )
                     torch.save(model.state_dict(), save_path)
-                    print_sys(f'** New best AUROC: {best_auc:.4f} (saved)')
+                    print_sys(f'** New best validation AUROC: {best_auc:.4f} (saved)')
 
                 print_sys(
-                    f'Epoch {epoch} | '
+                    f'Epoch {epoch} | Validation | '
                     f'AUROC: {m["AUC"]:.4f}  PR_AUC: {m["PR_AUC"]:.4f}  '
                     f'ACC: {m["ACC"]:.4f}  BACC: {m["BACC"]:.4f}  '
                     f'PREC: {m["PREC"]:.4f}  TPR: {m["TPR"]:.4f}  '
@@ -856,12 +861,12 @@ def main():
         fig.savefig(os.path.join(args.output_dir, f'loss_curve_fold{fold_i}.png'), dpi=150)
         plt.close(fig)
 
-        # Save metrics history
+        # Save validation metrics history (retain the existing CSV schema)
         if metric_history:
             metric_df = pd.DataFrame(metric_history)
             metric_df.to_csv(os.path.join(args.output_dir, f'metrics_fold{fold_i}.csv'), index=False)
 
-        # Plot ROC curve (using best model's predictions)
+        # Plot validation ROC curve (using the selected model's predictions)
         fig, ax = plt.subplots(figsize=(6, 6))
         ax.plot(best_fpr, best_tpr, linewidth=2, label=f'AUROC = {best_auc:.4f}')
         ax.plot([0, 1], [0, 1], 'k--', linewidth=1, alpha=0.5)
@@ -869,7 +874,7 @@ def main():
         ax.set_ylim([0, 1.02])
         ax.set_xlabel('False Positive Rate')
         ax.set_ylabel('True Positive Rate')
-        ax.set_title(f'ROC Curve - Fold {fold_i + 1}')
+        ax.set_title(f'Validation ROC Curve - Fold {fold_i + 1}')
         ax.legend(loc='lower right')
         ax.grid(True, alpha=0.3)
         fig.tight_layout()
@@ -881,13 +886,13 @@ def main():
         with open(fpr_tpr_path, 'wb') as fp:
             pickle.dump((best_fpr, best_tpr), fp)
 
-        print_sys(f'Fold {fold_i + 1} best AUROC: {best_auc:.4f}')
+        print_sys(f'Fold {fold_i + 1} best validation AUROC: {best_auc:.4f}')
         all_fold_aucs.append(best_auc)
 
     # Summary
     print_sys(f'\n{"=" * 60}')
-    print_sys(f'All folds AUROC: {all_fold_aucs}')
-    print_sys(f'Mean AUROC: {np.mean(all_fold_aucs):.4f} +/- {np.std(all_fold_aucs):.4f}')
+    print_sys(f'All folds validation AUROC: {all_fold_aucs}')
+    print_sys(f'Mean validation AUROC: {np.mean(all_fold_aucs):.4f} +/- {np.std(all_fold_aucs):.4f}')
     print_sys('Training complete.')
 
 

BioMod/drug_response/train_drug_performer_module.py

@@ -471,18 +471,18 @@ def metadata_generate(
 
 
 def data_split(data_idx: list, ratio: float = 0.95):
-    """Stratified by cancer type"""
-    train_idx, test_idx = [], []
+    """Return training and validation splits stratified by cancer type."""
+    train_idx, validation_idx = [], []
     for each_type in TCGA_LABEL_SET:
         data_subtype_idx = [item for item in data_idx if item[-1] == each_type]
         if len(data_subtype_idx) == 0:
             continue
         k = max(1, int(ratio * len(data_subtype_idx)))
         train_list = random.sample(data_subtype_idx, k)
-        test_list = [item for item in data_subtype_idx if item not in train_list]
+        validation_list = [item for item in data_subtype_idx if item not in train_list]
         train_idx += train_list
-        test_idx += test_list
-    return train_idx, test_idx
+        validation_idx += validation_list
+    return train_idx, validation_idx
 
 
 def feature_extract(
@@ -924,18 +924,18 @@ def main():
         seed=args.shuffle_seed,
     )
 
-    # 3) Divide the data set
+    # 3) Split training and validation data; validation is used for model selection
     print_sys("\n[Step 3/6] Splitting dataset...")
-    train_idx, test_idx = data_split(data_idx)
-    print_sys(f"Train samples: {len(train_idx)}, Test samples: {len(test_idx)}")
+    train_idx, validation_idx = data_split(data_idx)
+    print_sys(f"Train samples: {len(train_idx)}, Validation samples: {len(validation_idx)}")
 
     # 4) Extract features
     print_sys("\n[Step 4/6] Extracting features...")
     X_drug_train, Y_train, train_cancer_info, train_index_list = feature_extract(
         train_idx, drug_feature, args.max_atoms
     )
-    X_drug_test, Y_test, test_cancer_info, test_index_list = feature_extract(
-        test_idx, drug_feature, args.max_atoms
+    X_drug_validation, Y_validation, validation_cancer_info, validation_index_list = feature_extract(
+        validation_idx, drug_feature, args.max_atoms
     )
 
     # 5) Build a data set
@@ -943,8 +943,8 @@ def main():
     train_ds = DrugPerformerModuleDataset(
         X_drug_train, Y_train, train_index_list, cell_emb_dict
     )
-    test_ds = DrugPerformerModuleDataset(
-        X_drug_test, Y_test, test_index_list, cell_emb_dict
+    validation_ds = DrugPerformerModuleDataset(
+        X_drug_validation, Y_validation, validation_index_list, cell_emb_dict
     )
 
     drug_dim = X_drug_train[0][0].shape[-1]
@@ -957,8 +957,8 @@ def main():
         num_workers=num_workers,
         pin_memory=torch.cuda.is_available(),
     )
-    test_loader = DataLoader(
-        test_ds,
+    validation_loader = DataLoader(
+        validation_ds,
         batch_size=args.batch_size,
         shuffle=False,
         num_workers=num_workers,
@@ -1002,7 +1002,7 @@ def main():
 
     for epoch in range(1, args.epochs + 1):
         train_loss = train_epoch(model, train_loader, optimizer, criterion, device)
-        preds, trues, pcc = eval_epoch(model, test_loader, device)
+        preds, trues, pcc = eval_epoch(model, validation_loader, device)
 
         scheduler.step()
         current_lr = optimizer.param_groups[0]["lr"]
@@ -1010,7 +1010,7 @@ def main():
         print_sys(
             f"Epoch {epoch:03d}/{args.epochs} | "
             f"train_loss={train_loss:.4f} | "
-            f"val_pcc={pcc:.4f} | "
+            f"validation_pcc={pcc:.4f} | "
             f"lr={current_lr:.6f}"
         )
 
@@ -1021,7 +1021,7 @@ def main():
             best_epoch = epoch
             patience_counter = 0
 
-            # Save the best model
+            # Save the best model selected by validation PCC
             model_save_path = os.path.join(args.save_dir, "best_model.pth")
             torch.save(
                 {
@@ -1035,7 +1035,7 @@ def main():
                 },
                 model_save_path,
             )
-            print_sys(f"  → Best model saved! PCC improved to {best_pcc:.4f}")
+            print_sys(f"  → Best model saved! Validation PCC improved to {best_pcc:.4f}")
         else:
             patience_counter += 1
             if patience_counter >= args.patience:
@@ -1049,12 +1049,12 @@ def main():
     print_sys("Training completed!")
     print_sys("=" * 70)
     print_sys(f"Best epoch: {best_epoch}")
-    print_sys(f"Best PCC: {best_pcc:.4f}")
+    print_sys(f"Best validation PCC: {best_pcc:.4f}")
 
     if best_pred is not None:
         result_path = os.path.join(args.save_dir, "predictions.npz")
-        np.savez(result_path, pred=best_pred, test=best_true)
-        print_sys(f"Predictions saved to: {result_path}")
+        np.savez(result_path, pred=best_pred, validation=best_true)
+        print_sys(f"Validation predictions saved to: {result_path}")
 
     print_sys(f"Best model saved to: {os.path.join(args.save_dir, 'best_model.pth')}")
     print_sys("=" * 70)

BioMod/toturials/drug_combination.ipynb

@@ -8,7 +8,10 @@
     "\n",
     "This notebook prepares a runnable demo command for `drug_combination/train_drug_combination_performer_module.py` using configurable absolute paths.\n",
     "\n",
-    "The drug-combination data are not present in the current project yet, so `RUN_TRAINING` is set to `False` by default. After placing `data_summary/` under the task directory, switch `RUN_TRAINING = True` in the command cell to start training."
+    "The drug-combination data are not present in the current project yet, so `RUN_TRAINING` is set to `False` by default. After placing `data_summary/` under the task directory, switch `RUN_TRAINING = True` in the command cell to start training.\n",
+    "\n",
+    "The validation set is used for checkpoint selection. Reported metrics describe\n",
+    "validation performance; this workflow does not produce a separate final test evaluation.\n"
    ]
   },
   {
@@ -124,8 +127,8 @@
     "    'train_labels': DATA_DIR / 'new_labels_0_10.csv',\n",
     "    'train_cell_features': DATA_DIR / 'new_cell_features_954.csv',\n",
     "    'drug_smiles': DATA_DIR / 'smiles_0_10.csv',\n",
-    "    'independent_test_labels': DATA_DIR / 'test_data' / 'independent_input.csv',\n",
-    "    'independent_test_cell_features': DATA_DIR / 'test_data' / 'independent_cell_features_954.csv',\n",
+    "    'validation_labels': DATA_DIR / 'test_data' / 'independent_input.csv',\n",
+    "    'validation_cell_features': DATA_DIR / 'test_data' / 'independent_cell_features_954.csv',\n",
     "}\n",
     "\n",
     "def status_table(paths):\n",
@@ -378,7 +381,7 @@
     "\n",
     "\n",
     "data_overview = []\n",
-    "train_labels = test_labels = None\n",
+    "train_labels = validation_labels = None\n",
     "if expected_data_files['train_labels'].exists():\n",
     "    train_labels = read_label_table(expected_data_files['train_labels'])\n",
     "    data_overview.append({\n",
@@ -391,17 +394,17 @@
     "        'unique_drug2': train_labels['drug2'].nunique(),\n",
     "        'unique_pairs': train_labels[['drug1', 'drug2']].drop_duplicates().shape[0],\n",
     "    })\n",
-    "if expected_data_files['independent_test_labels'].exists():\n",
-    "    test_labels = read_label_table(expected_data_files['independent_test_labels'])\n",
+    "if expected_data_files['validation_labels'].exists():\n",
+    "    validation_labels = read_label_table(expected_data_files['validation_labels'])\n",
     "    data_overview.append({\n",
-    "        'split': 'independent_test',\n",
-    "        'rows': len(test_labels),\n",
-    "        'positive': int((test_labels['label'] == 1).sum()),\n",
-    "        'negative': int((test_labels['label'] == 0).sum()),\n",
-    "        'unique_cells': test_labels['cell'].nunique(),\n",
-    "        'unique_drug1': test_labels['drug1'].nunique(),\n",
-    "        'unique_drug2': test_labels['drug2'].nunique(),\n",
-    "        'unique_pairs': test_labels[['drug1', 'drug2']].drop_duplicates().shape[0],\n",
+    "        'split': 'validation',\n",
+    "        'rows': len(validation_labels),\n",
+    "        'positive': int((validation_labels['label'] == 1).sum()),\n",
+    "        'negative': int((validation_labels['label'] == 0).sum()),\n",
+    "        'unique_cells': validation_labels['cell'].nunique(),\n",
+    "        'unique_drug1': validation_labels['drug1'].nunique(),\n",
+    "        'unique_drug2': validation_labels['drug2'].nunique(),\n",
+    "        'unique_pairs': validation_labels[['drug1', 'drug2']].drop_duplicates().shape[0],\n",
     "    })\n",
     "\n",
     "data_overview_df = pd.DataFrame(data_overview)\n",
@@ -414,8 +417,8 @@
     "    label_rows = []\n",
     "    if train_labels is not None:\n",
     "        label_rows.extend([{'split': 'train', 'label': int(k), 'count': int(v)} for k, v in train_labels['label'].value_counts().sort_index().items()])\n",
-    "    if test_labels is not None:\n",
-    "        label_rows.extend([{'split': 'independent_test', 'label': int(k), 'count': int(v)} for k, v in test_labels['label'].value_counts().sort_index().items()])\n",
+    "    if validation_labels is not None:\n",
+    "        label_rows.extend([{'split': 'validation', 'label': int(k), 'count': int(v)} for k, v in validation_labels['label'].value_counts().sort_index().items()])\n",
     "    label_df = pd.DataFrame(label_rows)\n",
     "    label_df.to_csv(PLOT_DIR / 'drug_combination_label_counts.csv', index=False)\n",
     "\n",
@@ -748,4 +751,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 5
-}
+}

BioMod/toturials/drug_response_prediction.ipynb

@@ -8,7 +8,10 @@
     "\n",
     "This notebook is a tutorial version of the drug-response launcher based on `train_drug_performer_module.py`. It uses the weight0407 PerformerModule backbone, drug graph features, and CCLE/GDSC response data.\n",
     "\n",
-    "By default, the notebook does not relaunch the full 300-epoch training job. It checks the inputs, builds the exact command, reads the existing `weight0407/drug` outputs, computes metrics, and writes a small tutorial scatter plot. To retrain, set `RUN_TRAINING = True` in the training cell."
+    "By default, the notebook does not relaunch the full 300-epoch training job. It checks the inputs, builds the exact command, reads the existing `weight0407/drug` outputs, computes metrics, and writes a small tutorial scatter plot. To retrain, set `RUN_TRAINING = True` in the training cell.\n",
+    "\n",
+    "The validation set is used for checkpoint selection. Reported metrics describe\n",
+    "validation performance; this workflow does not produce a separate final test evaluation.\n"
    ]
   },
   {
@@ -325,13 +328,19 @@
     "print('prediction keys:', pred_npz.files)\n",
     "\n",
     "pred = pred_npz['pred'] if 'pred' in pred_npz.files else pred_npz['preds']\n",
-    "true = pred_npz['test'] if 'test' in pred_npz.files else pred_npz['true']\n",
+    "# Prefer the validation key; accept historical output files as well.\n",
+    "if 'validation' in pred_npz.files:\n",
+    "    true = pred_npz['validation']\n",
+    "elif 'test' in pred_npz.files:\n",
+    "    true = pred_npz['test']\n",
+    "else:\n",
+    "    true = pred_npz['true']\n",
     "\n",
     "pcc = pearsonr(pred, true)[0]\n",
     "mae = np.mean(np.abs(pred - true))\n",
     "rmse = np.sqrt(np.mean((pred - true) ** 2))\n",
     "summary = pd.DataFrame([{\n",
-    "    'n_test': len(pred),\n",
+    "    'n_validation': len(pred),\n",
     "    'pcc': pcc,\n",
     "    'mae': mae,\n",
     "    'rmse': rmse,\n",
@@ -388,8 +397,8 @@
     "    }\n",
     "\n",
     "\n",
-    "def reconstruct_test_metadata(data_root: Path, n_expected: int, ratio: float = 0.95, seed: int = 0) -> pd.DataFrame:\n",
-    "    \"\"\"Rebuild the test split metadata using the same deterministic split as the training script.\"\"\"\n",
+    "def reconstruct_validation_metadata(data_root: Path, n_expected: int, ratio: float = 0.95, seed: int = 0) -> pd.DataFrame:\n",
+    "    \"\"\"Rebuild the validation split metadata using the same deterministic split as the training script.\"\"\"\n",
     "    drug_info_file = data_root / 'GDSC' / '1.Drug_listMon Jun 24 09_00_55 2019.csv'\n",
     "    cell_line_info_file = data_root / 'CCLE' / 'Cell_lines_annotations_20181226.txt'\n",
     "    drug_feature_dir = data_root / 'GDSC' / 'drug_graph_feat'\n",
@@ -435,16 +444,16 @@
     "            data_idx.append((each_cellline, pubchem_id, float(value), cellline2cancertype[each_cellline]))\n",
     "\n",
     "    rng = random.Random(seed)\n",
-    "    test_idx = []\n",
+    "    validation_idx = []\n",
     "    for each_type in TCGA_LABEL_SET:\n",
     "        subtype = [item for item in data_idx if item[-1] == each_type]\n",
     "        if not subtype:\n",
     "            continue\n",
     "        k = max(1, int(ratio * len(subtype)))\n",
     "        train_list = rng.sample(subtype, k)\n",
-    "        test_idx.extend([item for item in subtype if item not in train_list])\n",
+    "        validation_idx.extend([item for item in subtype if item not in train_list])\n",
     "\n",
-    "    reconstructed = pd.DataFrame(test_idx, columns=['cell_line_id', 'drug_id', 'true_from_metadata', 'cancer_type'])\n",
+    "    reconstructed = pd.DataFrame(validation_idx, columns=['cell_line_id', 'drug_id', 'true_from_metadata', 'cancer_type'])\n",
     "    if len(reconstructed) != n_expected:\n",
     "        raise ValueError(f'Reconstructed {len(reconstructed)} rows, but predictions contain {n_expected} rows.')\n",
     "    return reconstructed[['drug_id', 'cell_line_id', 'cancer_type']]\n",
@@ -462,10 +471,10 @@
     "\n",
     "if metadata_missing:\n",
     "    try:\n",
-    "        recovered_meta = reconstruct_test_metadata(DATA_ROOT, n_expected=len(analysis_df), ratio=0.95, seed=0)\n",
+    "        recovered_meta = reconstruct_validation_metadata(DATA_ROOT, n_expected=len(analysis_df), ratio=0.95, seed=0)\n",
     "        for col in metadata_cols:\n",
     "            analysis_df[col] = recovered_meta[col].to_numpy()\n",
-    "        print('Recovered test metadata from the original GDSC/CCLE split.')\n",
+    "        print('Recovered validation metadata from the original GDSC/CCLE split.')\n",
     "    except Exception as exc:\n",
     "        print('Metadata recovery skipped:', repr(exc))\n",
     "        for col in metadata_cols:\n",