workbench 0.8.231__py3-none-any.whl → 0.8.236__py3-none-any.whl

workbench/model_scripts/chemprop/generated_model_script.py

@@ -20,6 +20,7 @@ import torch
 from chemprop import data, models
 
 from model_script_utils import (
+    cap_std_outliers,
     expand_proba_column,
     input_fn,
     output_fn,
@@ -43,6 +44,12 @@ DEFAULT_HYPERPARAMETERS = {
     "ffn_num_layers": 2,
     # Loss function for regression (mae, mse)
     "criterion": "mae",
+    # Split strategy: "random", "scaffold", or "butina"
+    # - random: Standard random split
+    # - scaffold: Bemis-Murcko scaffold-based grouping
+    # - butina: Morgan fingerprint clustering (recommended for ADMET)
+    "split_strategy": "butina",
+    "butina_cutoff": 0.4,  # Tanimoto distance cutoff for Butina clustering
     # Random seed
     "seed": 42,
     # Foundation model support
@@ -58,11 +65,11 @@ DEFAULT_HYPERPARAMETERS = {
 # Template parameters (filled in by Workbench)
 TEMPLATE_PARAMS = {
     "model_type": "uq_regressor",
-    "targets": ['udm_asy_res_value'],
+    "targets": ['logd'],
     "feature_list": ['smiles'],
-    "id_column": "udm_mol_bat_id",
-    "model_metrics_s3_path": "s3://ideaya-sageworks-bucket/models/logd-value-reg-chemprop-1-dt/training",
-    "hyperparameters": {},
+    "id_column": "molecule_name",
+    "model_metrics_s3_path": "s3://sandbox-sageworks-artifacts/models/logd-chemprop-split-butina/training",
+    "hyperparameters": {'split_strategy': 'butina'},
 }
 
 
@@ -245,6 +252,7 @@ def predict_fn(df: pd.DataFrame, model_dict: dict) -> pd.DataFrame:
     preds_std = np.std(np.stack(all_preds), axis=0)
     if preds.ndim == 1:
         preds, preds_std = preds.reshape(-1, 1), preds_std.reshape(-1, 1)
+    preds_std = cap_std_outliers(preds_std)
 
     print(f"Inference complete: {preds.shape[0]} predictions")
 
@@ -303,6 +311,7 @@ if __name__ == "__main__":
         check_dataframe,
         compute_classification_metrics,
         compute_regression_metrics,
+        get_split_indices,
         print_classification_metrics,
         print_confusion_matrix,
         print_regression_metrics,
@@ -516,22 +525,29 @@ if __name__ == "__main__":
     n_folds = hyperparameters["n_folds"]
     batch_size = hyperparameters["batch_size"]
 
-    if n_folds == 1:
-        if "training" in all_df.columns:
-            print("Using 'training' column for train/val split")
-            train_idx = np.where(all_df["training"])[0]
-            val_idx = np.where(~all_df["training"])[0]
-        else:
-            print("WARNING: No 'training' column, using random 80/20 split")
-            train_idx, val_idx = train_test_split(np.arange(len(all_df)), test_size=0.2, random_state=42)
+    # Get split strategy parameters
+    split_strategy = hyperparameters.get("split_strategy", "random")
+    butina_cutoff = hyperparameters.get("butina_cutoff", 0.4)
+
+    # Check for pre-defined training column (overrides split strategy)
+    if n_folds == 1 and "training" in all_df.columns:
+        print("Using 'training' column for train/val split")
+        train_idx = np.where(all_df["training"])[0]
+        val_idx = np.where(~all_df["training"])[0]
         folds = [(train_idx, val_idx)]
     else:
-        if model_type == "classifier":
-            kfold = StratifiedKFold(n_splits=n_folds, shuffle=True, random_state=42)
-            folds = list(kfold.split(all_df, all_df[target_columns[0]]))
-        else:
-            kfold = KFold(n_splits=n_folds, shuffle=True, random_state=42)
-            folds = list(kfold.split(all_df))
+        # Use unified split interface (auto-detects 'smiles' column for scaffold/butina)
+        target_col = target_columns[0] if model_type == "classifier" else None
+        folds = get_split_indices(
+            all_df,
+            n_splits=n_folds,
+            strategy=split_strategy,
+            target_column=target_col,
+            test_size=0.2,
+            random_state=42,
+            butina_cutoff=butina_cutoff,
+        )
+        print(f"Split strategy: {split_strategy}")
 
     print(f"Training {'single model' if n_folds == 1 else f'{n_folds}-fold ensemble'}...")
 
@@ -701,6 +717,7 @@ if __name__ == "__main__":
             preds_std = np.std(np.stack(all_ens_preds), axis=0)
             if preds_std.ndim == 1:
                 preds_std = preds_std.reshape(-1, 1)
+            preds_std = cap_std_outliers(preds_std)
 
         print("\n--- Per-target metrics ---")
         for t_idx, t_name in enumerate(target_columns):

workbench/model_scripts/chemprop/model_script_utils.py

@@ -16,6 +16,7 @@ from sklearn.metrics import (
     r2_score,
     root_mean_squared_error,
 )
+from sklearn.model_selection import GroupKFold, GroupShuffleSplit
 from scipy.stats import spearmanr
 
 
@@ -367,3 +368,227 @@ def print_confusion_matrix(y_true: np.ndarray, y_pred: np.ndarray, label_names:
         for j, col_name in enumerate(label_names):
             value = conf_mtx[i, j]
             print(f"ConfusionMatrix:{row_name}:{col_name} {value}")
+
+
+# =============================================================================
+# Dataset Splitting Utilities for Molecular Data
+# =============================================================================
+def get_scaffold(smiles: str) -> str:
+    """Extract Bemis-Murcko scaffold from a SMILES string.
+
+    Args:
+        smiles: SMILES string of the molecule
+
+    Returns:
+        SMILES string of the scaffold, or empty string if molecule is invalid
+    """
+    from rdkit import Chem
+    from rdkit.Chem.Scaffolds import MurckoScaffold
+
+    mol = Chem.MolFromSmiles(smiles)
+    if mol is None:
+        return ""
+    try:
+        scaffold = MurckoScaffold.GetScaffoldForMol(mol)
+        return Chem.MolToSmiles(scaffold)
+    except Exception:
+        return ""
+
+
+def get_scaffold_groups(smiles_list: list[str]) -> np.ndarray:
+    """Assign each molecule to a scaffold group.
+
+    Args:
+        smiles_list: List of SMILES strings
+
+    Returns:
+        Array of group indices (same scaffold = same group)
+    """
+    scaffold_to_group = {}
+    groups = []
+
+    for smi in smiles_list:
+        scaffold = get_scaffold(smi)
+        if scaffold not in scaffold_to_group:
+            scaffold_to_group[scaffold] = len(scaffold_to_group)
+        groups.append(scaffold_to_group[scaffold])
+
+    n_scaffolds = len(scaffold_to_group)
+    print(f"Found {n_scaffolds} unique scaffolds from {len(smiles_list)} molecules")
+    return np.array(groups)
+
+
+def get_butina_clusters(smiles_list: list[str], cutoff: float = 0.4) -> np.ndarray:
+    """Cluster molecules using Butina algorithm on Morgan fingerprints.
+
+    Uses RDKit's Butina clustering with Tanimoto distance on Morgan fingerprints.
+    This is Pat Walters' recommended approach for creating diverse train/test splits.
+
+    Args:
+        smiles_list: List of SMILES strings
+        cutoff: Tanimoto distance cutoff for clustering (default 0.4)
+               Lower values = more clusters = more similar molecules per cluster
+
+    Returns:
+        Array of cluster indices
+    """
+    from rdkit import Chem, DataStructs
+    from rdkit.Chem.rdFingerprintGenerator import GetMorganGenerator
+    from rdkit.ML.Cluster import Butina
+
+    # Create Morgan fingerprint generator
+    fp_gen = GetMorganGenerator(radius=2, fpSize=2048)
+
+    # Generate Morgan fingerprints
+    fps = []
+    valid_indices = []
+    for i, smi in enumerate(smiles_list):
+        mol = Chem.MolFromSmiles(smi)
+        if mol is not None:
+            fp = fp_gen.GetFingerprint(mol)
+            fps.append(fp)
+            valid_indices.append(i)
+
+    if len(fps) == 0:
+        raise ValueError("No valid molecules found for clustering")
+
+    # Compute distance matrix (upper triangle only for efficiency)
+    n = len(fps)
+    dists = []
+    for i in range(1, n):
+        sims = DataStructs.BulkTanimotoSimilarity(fps[i], fps[:i])
+        dists.extend([1 - s for s in sims])
+
+    # Butina clustering
+    clusters = Butina.ClusterData(dists, n, cutoff, isDistData=True)
+
+    # Map back to original indices
+    cluster_labels = np.zeros(len(smiles_list), dtype=int)
+    for cluster_idx, cluster in enumerate(clusters):
+        for mol_idx in cluster:
+            original_idx = valid_indices[mol_idx]
+            cluster_labels[original_idx] = cluster_idx
+
+    # Assign invalid molecules to their own clusters
+    next_cluster = len(clusters)
+    for i in range(len(smiles_list)):
+        if i not in valid_indices:
+            cluster_labels[i] = next_cluster
+            next_cluster += 1
+
+    n_clusters = len(set(cluster_labels))
+    print(f"Butina clustering: {n_clusters} clusters from {len(smiles_list)} molecules (cutoff={cutoff})")
+    return cluster_labels
+
+
+def _find_smiles_column(columns: list[str]) -> str | None:
+    """Find SMILES column (case-insensitive match for 'smiles').
+
+    Args:
+        columns: List of column names
+
+    Returns:
+        The matching column name, or None if not found
+    """
+    return next((c for c in columns if c.lower() == "smiles"), None)
+
+
+def get_split_indices(
+    df: pd.DataFrame,
+    n_splits: int = 5,
+    strategy: str = "random",
+    smiles_column: str | None = None,
+    target_column: str | None = None,
+    test_size: float = 0.2,
+    random_state: int = 42,
+    butina_cutoff: float = 0.4,
+) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Get train/validation split indices using various strategies.
+
+    This is a unified interface for generating splits that can be used across
+    all model templates (XGBoost, PyTorch, ChemProp).
+
+    Args:
+        df: DataFrame containing the data
+        n_splits: Number of CV folds (1 = single train/val split)
+        strategy: Split strategy - one of:
+            - "random": Standard random split (default sklearn behavior)
+            - "scaffold": Bemis-Murcko scaffold-based grouping
+            - "butina": Morgan fingerprint clustering (recommended for ADMET)
+        smiles_column: Column containing SMILES. If None, auto-detects 'smiles' (case-insensitive)
+        target_column: Column containing target values (for stratification, optional)
+        test_size: Fraction for validation set when n_splits=1 (default 0.2)
+        random_state: Random seed for reproducibility
+        butina_cutoff: Tanimoto distance cutoff for Butina clustering (default 0.4)
+
+    Returns:
+        List of (train_indices, val_indices) tuples
+
+    Note:
+        If scaffold/butina strategy is requested but no SMILES column is found,
+        automatically falls back to random split with a warning message.
+
+    Example:
+        >>> folds = get_split_indices(df, n_splits=5, strategy="scaffold")
+        >>> for train_idx, val_idx in folds:
+        ...     X_train, X_val = df.iloc[train_idx], df.iloc[val_idx]
+    """
+    from sklearn.model_selection import KFold, StratifiedKFold, train_test_split
+
+    n_samples = len(df)
+
+    # Random split (original behavior)
+    if strategy == "random":
+        if n_splits == 1:
+            indices = np.arange(n_samples)
+            train_idx, val_idx = train_test_split(indices, test_size=test_size, random_state=random_state)
+            return [(train_idx, val_idx)]
+        else:
+            if target_column and df[target_column].dtype in ["object", "category", "bool"]:
+                kfold = StratifiedKFold(n_splits=n_splits, shuffle=True, random_state=random_state)
+                return list(kfold.split(df, df[target_column]))
+            else:
+                kfold = KFold(n_splits=n_splits, shuffle=True, random_state=random_state)
+                return list(kfold.split(df))
+
+    # Scaffold or Butina split requires SMILES - auto-detect if not provided
+    if smiles_column is None:
+        smiles_column = _find_smiles_column(df.columns.tolist())
+
+    # Fall back to random split if no SMILES column available
+    if smiles_column is None or smiles_column not in df.columns:
+        print(f"No 'smiles' column found for strategy='{strategy}', falling back to random split")
+        return get_split_indices(
+            df,
+            n_splits=n_splits,
+            strategy="random",
+            target_column=target_column,
+            test_size=test_size,
+            random_state=random_state,
+        )
+
+    smiles_list = df[smiles_column].tolist()
+
+    # Get group assignments
+    if strategy == "scaffold":
+        groups = get_scaffold_groups(smiles_list)
+    elif strategy == "butina":
+        groups = get_butina_clusters(smiles_list, cutoff=butina_cutoff)
+    else:
+        raise ValueError(f"Unknown strategy: {strategy}. Use 'random', 'scaffold', or 'butina'")
+
+    # Generate splits using GroupKFold or GroupShuffleSplit
+    if n_splits == 1:
+        # Single split: use GroupShuffleSplit
+        splitter = GroupShuffleSplit(n_splits=1, test_size=test_size, random_state=random_state)
+        return list(splitter.split(df, groups=groups))
+    else:
+        # K-fold: use GroupKFold (ensures no group appears in both train and val)
+        # Note: GroupKFold doesn't shuffle, so we shuffle group order first
+        unique_groups = np.unique(groups)
+        rng = np.random.default_rng(random_state)
+        shuffled_group_map = {g: i for i, g in enumerate(rng.permutation(unique_groups))}
+        shuffled_groups = np.array([shuffled_group_map[g] for g in groups])
+
+        gkf = GroupKFold(n_splits=n_splits)
+        return list(gkf.split(df, groups=shuffled_groups))

workbench/model_scripts/pytorch_model/generated_model_script.py

@@ -53,19 +53,25 @@ DEFAULT_HYPERPARAMETERS = {
     "use_batch_norm": True,
     # Loss function for regression (L1Loss=MAE, MSELoss=MSE, HuberLoss, SmoothL1Loss)
     "loss": "L1Loss",
+    # Split strategy: "random", "scaffold", or "butina"
+    # - random: Standard random split
+    # - scaffold: Bemis-Murcko scaffold-based grouping (requires 'smiles' column in data)
+    # - butina: Morgan fingerprint clustering (requires 'smiles' column, recommended for ADMET)
+    "split_strategy": "butina",
+    "butina_cutoff": 0.4,  # Tanimoto distance cutoff for Butina clustering
     # Random seed
     "seed": 42,
 }
 
 # Template parameters (filled in by Workbench)
 TEMPLATE_PARAMS = {
-    "model_type": "classifier",
-    "target": "class",
+    "model_type": "uq_regressor",
+    "target": "logd",
     "features": ['chi2v', 'fr_sulfone', 'chi1v', 'bcut2d_logplow', 'fr_piperzine', 'kappa3', 'smr_vsa1', 'slogp_vsa5', 'fr_ketone_topliss', 'fr_sulfonamd', 'fr_imine', 'fr_benzene', 'fr_ester', 'chi2n', 'labuteasa', 'peoe_vsa2', 'smr_vsa6', 'bcut2d_chglo', 'fr_sh', 'peoe_vsa1', 'fr_allylic_oxid', 'chi4n', 'fr_ar_oh', 'fr_nh0', 'fr_term_acetylene', 'slogp_vsa7', 'slogp_vsa4', 'estate_vsa1', 'vsa_estate4', 'numbridgeheadatoms', 'numheterocycles', 'fr_ketone', 'fr_morpholine', 'fr_guanido', 'estate_vsa2', 'numheteroatoms', 'fr_nitro_arom_nonortho', 'fr_piperdine', 'nocount', 'numspiroatoms', 'fr_aniline', 'fr_thiophene', 'slogp_vsa10', 'fr_amide', 'slogp_vsa2', 'fr_epoxide', 'vsa_estate7', 'fr_ar_coo', 'fr_imidazole', 'fr_nitrile', 'fr_oxazole', 'numsaturatedrings', 'fr_pyridine', 'fr_hoccn', 'fr_ndealkylation1', 'numaliphaticheterocycles', 'fr_phenol', 'maxpartialcharge', 'vsa_estate5', 'peoe_vsa13', 'minpartialcharge', 'qed', 'fr_al_oh', 'slogp_vsa11', 'chi0n', 'fr_bicyclic', 'peoe_vsa12', 'fpdensitymorgan1', 'fr_oxime', 'molwt', 'fr_dihydropyridine', 'smr_vsa5', 'peoe_vsa5', 'fr_nitro', 'hallkieralpha', 'heavyatommolwt', 'fr_alkyl_halide', 'peoe_vsa8', 'fr_nhpyrrole', 'fr_isocyan', 'bcut2d_chghi', 'fr_lactam', 'peoe_vsa11', 'smr_vsa9', 'tpsa', 'chi4v', 'slogp_vsa1', 'phi', 'bcut2d_logphi', 'avgipc', 'estate_vsa11', 'fr_coo', 'bcut2d_mwhi', 'numunspecifiedatomstereocenters', 'vsa_estate10', 'estate_vsa8', 'numvalenceelectrons', 'fr_nh2', 'fr_lactone', 'vsa_estate1', 'estate_vsa4', 'numatomstereocenters', 'vsa_estate8', 'fr_para_hydroxylation', 'peoe_vsa3', 'fr_thiazole', 'peoe_vsa10', 'fr_ndealkylation2', 'slogp_vsa12', 'peoe_vsa9', 'maxestateindex', 'fr_quatn', 'smr_vsa7', 'minestateindex', 'numaromaticheterocycles', 'numrotatablebonds', 'fr_ar_nh', 'fr_ether', 'exactmolwt', 'fr_phenol_noorthohbond', 'slogp_vsa3', 'fr_ar_n', 'sps', 'fr_c_o_nocoo', 'bertzct', 'peoe_vsa7', 'slogp_vsa8', 'numradicalelectrons', 'molmr', 'fr_tetrazole', 'numsaturatedcarbocycles', 'bcut2d_mrhi', 'kappa1', 'numamidebonds', 'fpdensitymorgan2', 'smr_vsa8', 'chi1n', 'estate_vsa6', 'fr_barbitur', 'fr_diazo', 'kappa2', 'chi0', 'bcut2d_mrlow', 'balabanj', 'peoe_vsa4', 'numhacceptors', 'fr_sulfide', 'chi3n', 'smr_vsa2', 'fr_al_oh_notert', 'fr_benzodiazepine', 'fr_phos_ester', 'fr_aldehyde', 'fr_coo2', 'estate_vsa5', 'fr_prisulfonamd', 'numaromaticcarbocycles', 'fr_unbrch_alkane', 'fr_urea', 'fr_nitroso', 'smr_vsa10', 'fr_c_s', 'smr_vsa3', 'fr_methoxy', 'maxabspartialcharge', 'slogp_vsa9', 'heavyatomcount', 'fr_azide', 'chi3v', 'smr_vsa4', 'mollogp', 'chi0v', 'fr_aryl_methyl', 'fr_nh1', 'fpdensitymorgan3', 'fr_furan', 'fr_hdrzine', 'fr_arn', 'numaromaticrings', 'vsa_estate3', 'fr_azo', 'fr_halogen', 'estate_vsa9', 'fr_hdrzone', 'numhdonors', 'fr_alkyl_carbamate', 'fr_isothiocyan', 'minabspartialcharge', 'fr_al_coo', 'ringcount', 'chi1', 'estate_vsa7', 'fr_nitro_arom', 'vsa_estate9', 'minabsestateindex', 'maxabsestateindex', 'vsa_estate6', 'estate_vsa10', 'estate_vsa3', 'fr_n_o', 'fr_amidine', 'fr_thiocyan', 'fr_phos_acid', 'fr_c_o', 'fr_imide', 'numaliphaticrings', 'peoe_vsa6', 'vsa_estate2', 'nhohcount', 'numsaturatedheterocycles', 'slogp_vsa6', 'peoe_vsa14', 'fractioncsp3', 'bcut2d_mwlow', 'numaliphaticcarbocycles', 'fr_priamide', 'nacid', 'nbase', 'naromatom', 'narombond', 'sz', 'sm', 'sv', 'sse', 'spe', 'sare', 'sp', 'si', 'mz', 'mm', 'mv', 'mse', 'mpe', 'mare', 'mp', 'mi', 'xch_3d', 'xch_4d', 'xch_5d', 'xch_6d', 'xch_7d', 'xch_3dv', 'xch_4dv', 'xch_5dv', 'xch_6dv', 'xch_7dv', 'xc_3d', 'xc_4d', 'xc_5d', 'xc_6d', 'xc_3dv', 'xc_4dv', 'xc_5dv', 'xc_6dv', 'xpc_4d', 'xpc_5d', 'xpc_6d', 'xpc_4dv', 'xpc_5dv', 'xpc_6dv', 'xp_0d', 'xp_1d', 'xp_2d', 'xp_3d', 'xp_4d', 'xp_5d', 'xp_6d', 'xp_7d', 'axp_0d', 'axp_1d', 'axp_2d', 'axp_3d', 'axp_4d', 'axp_5d', 'axp_6d', 'axp_7d', 'xp_0dv', 'xp_1dv', 'xp_2dv', 'xp_3dv', 'xp_4dv', 'xp_5dv', 'xp_6dv', 'xp_7dv', 'axp_0dv', 'axp_1dv', 'axp_2dv', 'axp_3dv', 'axp_4dv', 'axp_5dv', 'axp_6dv', 'axp_7dv', 'c1sp1', 'c2sp1', 'c1sp2', 'c2sp2', 'c3sp2', 'c1sp3', 'c2sp3', 'c3sp3', 'c4sp3', 'hybratio', 'fcsp3', 'num_stereocenters', 'num_unspecified_stereocenters', 'num_defined_stereocenters', 'num_r_centers', 'num_s_centers', 'num_stereobonds', 'num_e_bonds', 'num_z_bonds', 'stereo_complexity', 'frac_defined_stereo'],
-    "id_column": "udm_mol_bat_id",
-    "compressed_features": [],
-    "model_metrics_s3_path": "s3://ideaya-sageworks-bucket/models/caco2-er-class-pytorch-1-fr/training",
-    "hyperparameters": {},
+    "id_column": "molecule_name",
+    "compressed_features": ['fingerprint'],
+    "model_metrics_s3_path": "s3://sandbox-sageworks-artifacts/models/logd-pytorch-split-butina/training",
+    "hyperparameters": {'split_strategy': 'butina'},
 }
 
 
@@ -234,6 +240,7 @@ if __name__ == "__main__":
         check_dataframe,
         compute_classification_metrics,
         compute_regression_metrics,
+        get_split_indices,
         print_classification_metrics,
         print_confusion_matrix,
         print_regression_metrics,
@@ -337,22 +344,29 @@ if __name__ == "__main__":
     # Get categorical cardinalities
     categorical_cardinalities = [len(category_mappings.get(col, {})) for col in categorical_cols]
 
-    if n_folds == 1:
-        if "training" in all_df.columns:
-            print("Using 'training' column for train/val split")
-            train_idx = np.where(all_df["training"])[0]
-            val_idx = np.where(~all_df["training"])[0]
-        else:
-            print("WARNING: No 'training' column found, using random 80/20 split")
-            train_idx, val_idx = train_test_split(np.arange(len(all_df)), test_size=0.2, random_state=42)
+    # Get split strategy parameters
+    split_strategy = hyperparameters.get("split_strategy", "random")
+    butina_cutoff = hyperparameters.get("butina_cutoff", 0.4)
+
+    # Check for pre-defined training column (overrides split strategy)
+    if n_folds == 1 and "training" in all_df.columns:
+        print("Using 'training' column for train/val split")
+        train_idx = np.where(all_df["training"])[0]
+        val_idx = np.where(~all_df["training"])[0]
         folds = [(train_idx, val_idx)]
     else:
-        if model_type == "classifier":
-            kfold = StratifiedKFold(n_splits=n_folds, shuffle=True, random_state=42)
-            folds = list(kfold.split(all_df, all_df[target]))
-        else:
-            kfold = KFold(n_splits=n_folds, shuffle=True, random_state=42)
-            folds = list(kfold.split(all_df))
+        # Use unified split interface (auto-detects 'smiles' column for scaffold/butina)
+        target_col = target if model_type == "classifier" else None
+        folds = get_split_indices(
+            all_df,
+            n_splits=n_folds,
+            strategy=split_strategy,
+            target_column=target_col,
+            test_size=0.2,
+            random_state=42,
+            butina_cutoff=butina_cutoff,
+        )
+        print(f"Split strategy: {split_strategy}")
 
     print(f"Training {'single model' if n_folds == 1 else f'{n_folds}-fold ensemble'}...")
 

workbench/model_scripts/pytorch_model/model_script_utils.py

@@ -16,6 +16,7 @@ from sklearn.metrics import (
     r2_score,
     root_mean_squared_error,
 )
+from sklearn.model_selection import GroupKFold, GroupShuffleSplit
 from scipy.stats import spearmanr
 
 
@@ -367,3 +368,227 @@ def print_confusion_matrix(y_true: np.ndarray, y_pred: np.ndarray, label_names:
         for j, col_name in enumerate(label_names):
             value = conf_mtx[i, j]
             print(f"ConfusionMatrix:{row_name}:{col_name} {value}")
+
+
+# =============================================================================
+# Dataset Splitting Utilities for Molecular Data
+# =============================================================================
+def get_scaffold(smiles: str) -> str:
+    """Extract Bemis-Murcko scaffold from a SMILES string.
+
+    Args:
+        smiles: SMILES string of the molecule
+
+    Returns:
+        SMILES string of the scaffold, or empty string if molecule is invalid
+    """
+    from rdkit import Chem
+    from rdkit.Chem.Scaffolds import MurckoScaffold
+
+    mol = Chem.MolFromSmiles(smiles)
+    if mol is None:
+        return ""
+    try:
+        scaffold = MurckoScaffold.GetScaffoldForMol(mol)
+        return Chem.MolToSmiles(scaffold)
+    except Exception:
+        return ""
+
+
+def get_scaffold_groups(smiles_list: list[str]) -> np.ndarray:
+    """Assign each molecule to a scaffold group.
+
+    Args:
+        smiles_list: List of SMILES strings
+
+    Returns:
+        Array of group indices (same scaffold = same group)
+    """
+    scaffold_to_group = {}
+    groups = []
+
+    for smi in smiles_list:
+        scaffold = get_scaffold(smi)
+        if scaffold not in scaffold_to_group:
+            scaffold_to_group[scaffold] = len(scaffold_to_group)
+        groups.append(scaffold_to_group[scaffold])
+
+    n_scaffolds = len(scaffold_to_group)
+    print(f"Found {n_scaffolds} unique scaffolds from {len(smiles_list)} molecules")
+    return np.array(groups)
+
+
+def get_butina_clusters(smiles_list: list[str], cutoff: float = 0.4) -> np.ndarray:
+    """Cluster molecules using Butina algorithm on Morgan fingerprints.
+
+    Uses RDKit's Butina clustering with Tanimoto distance on Morgan fingerprints.
+    This is Pat Walters' recommended approach for creating diverse train/test splits.
+
+    Args:
+        smiles_list: List of SMILES strings
+        cutoff: Tanimoto distance cutoff for clustering (default 0.4)
+               Lower values = more clusters = more similar molecules per cluster
+
+    Returns:
+        Array of cluster indices
+    """
+    from rdkit import Chem, DataStructs
+    from rdkit.Chem.rdFingerprintGenerator import GetMorganGenerator
+    from rdkit.ML.Cluster import Butina
+
+    # Create Morgan fingerprint generator
+    fp_gen = GetMorganGenerator(radius=2, fpSize=2048)
+
+    # Generate Morgan fingerprints
+    fps = []
+    valid_indices = []
+    for i, smi in enumerate(smiles_list):
+        mol = Chem.MolFromSmiles(smi)
+        if mol is not None:
+            fp = fp_gen.GetFingerprint(mol)
+            fps.append(fp)
+            valid_indices.append(i)
+
+    if len(fps) == 0:
+        raise ValueError("No valid molecules found for clustering")
+
+    # Compute distance matrix (upper triangle only for efficiency)
+    n = len(fps)
+    dists = []
+    for i in range(1, n):
+        sims = DataStructs.BulkTanimotoSimilarity(fps[i], fps[:i])
+        dists.extend([1 - s for s in sims])
+
+    # Butina clustering
+    clusters = Butina.ClusterData(dists, n, cutoff, isDistData=True)
+
+    # Map back to original indices
+    cluster_labels = np.zeros(len(smiles_list), dtype=int)
+    for cluster_idx, cluster in enumerate(clusters):
+        for mol_idx in cluster:
+            original_idx = valid_indices[mol_idx]
+            cluster_labels[original_idx] = cluster_idx
+
+    # Assign invalid molecules to their own clusters
+    next_cluster = len(clusters)
+    for i in range(len(smiles_list)):
+        if i not in valid_indices:
+            cluster_labels[i] = next_cluster
+            next_cluster += 1
+
+    n_clusters = len(set(cluster_labels))
+    print(f"Butina clustering: {n_clusters} clusters from {len(smiles_list)} molecules (cutoff={cutoff})")
+    return cluster_labels
+
+
+def _find_smiles_column(columns: list[str]) -> str | None:
+    """Find SMILES column (case-insensitive match for 'smiles').
+
+    Args:
+        columns: List of column names
+
+    Returns:
+        The matching column name, or None if not found
+    """
+    return next((c for c in columns if c.lower() == "smiles"), None)
+
+
+def get_split_indices(
+    df: pd.DataFrame,
+    n_splits: int = 5,
+    strategy: str = "random",
+    smiles_column: str | None = None,
+    target_column: str | None = None,
+    test_size: float = 0.2,
+    random_state: int = 42,
+    butina_cutoff: float = 0.4,
+) -> list[tuple[np.ndarray, np.ndarray]]:
+    """Get train/validation split indices using various strategies.
+
+    This is a unified interface for generating splits that can be used across
+    all model templates (XGBoost, PyTorch, ChemProp).
+
+    Args:
+        df: DataFrame containing the data
+        n_splits: Number of CV folds (1 = single train/val split)
+        strategy: Split strategy - one of:
+            - "random": Standard random split (default sklearn behavior)
+            - "scaffold": Bemis-Murcko scaffold-based grouping
+            - "butina": Morgan fingerprint clustering (recommended for ADMET)
+        smiles_column: Column containing SMILES. If None, auto-detects 'smiles' (case-insensitive)
+        target_column: Column containing target values (for stratification, optional)
+        test_size: Fraction for validation set when n_splits=1 (default 0.2)
+        random_state: Random seed for reproducibility
+        butina_cutoff: Tanimoto distance cutoff for Butina clustering (default 0.4)
+
+    Returns:
+        List of (train_indices, val_indices) tuples
+
+    Note:
+        If scaffold/butina strategy is requested but no SMILES column is found,
+        automatically falls back to random split with a warning message.
+
+    Example:
+        >>> folds = get_split_indices(df, n_splits=5, strategy="scaffold")
+        >>> for train_idx, val_idx in folds:
+        ...     X_train, X_val = df.iloc[train_idx], df.iloc[val_idx]
+    """
+    from sklearn.model_selection import KFold, StratifiedKFold, train_test_split
+
+    n_samples = len(df)
+
+    # Random split (original behavior)
+    if strategy == "random":
+        if n_splits == 1:
+            indices = np.arange(n_samples)
+            train_idx, val_idx = train_test_split(indices, test_size=test_size, random_state=random_state)
+            return [(train_idx, val_idx)]
+        else:
+            if target_column and df[target_column].dtype in ["object", "category", "bool"]:
+                kfold = StratifiedKFold(n_splits=n_splits, shuffle=True, random_state=random_state)
+                return list(kfold.split(df, df[target_column]))
+            else:
+                kfold = KFold(n_splits=n_splits, shuffle=True, random_state=random_state)
+                return list(kfold.split(df))
+
+    # Scaffold or Butina split requires SMILES - auto-detect if not provided
+    if smiles_column is None:
+        smiles_column = _find_smiles_column(df.columns.tolist())
+
+    # Fall back to random split if no SMILES column available
+    if smiles_column is None or smiles_column not in df.columns:
+        print(f"No 'smiles' column found for strategy='{strategy}', falling back to random split")
+        return get_split_indices(
+            df,
+            n_splits=n_splits,
+            strategy="random",
+            target_column=target_column,
+            test_size=test_size,
+            random_state=random_state,
+        )
+
+    smiles_list = df[smiles_column].tolist()
+
+    # Get group assignments
+    if strategy == "scaffold":
+        groups = get_scaffold_groups(smiles_list)
+    elif strategy == "butina":
+        groups = get_butina_clusters(smiles_list, cutoff=butina_cutoff)
+    else:
+        raise ValueError(f"Unknown strategy: {strategy}. Use 'random', 'scaffold', or 'butina'")
+
+    # Generate splits using GroupKFold or GroupShuffleSplit
+    if n_splits == 1:
+        # Single split: use GroupShuffleSplit
+        splitter = GroupShuffleSplit(n_splits=1, test_size=test_size, random_state=random_state)
+        return list(splitter.split(df, groups=groups))
+    else:
+        # K-fold: use GroupKFold (ensures no group appears in both train and val)
+        # Note: GroupKFold doesn't shuffle, so we shuffle group order first
+        unique_groups = np.unique(groups)
+        rng = np.random.default_rng(random_state)
+        shuffled_group_map = {g: i for i, g in enumerate(rng.permutation(unique_groups))}
+        shuffled_groups = np.array([shuffled_group_map[g] for g in groups])
+
+        gkf = GroupKFold(n_splits=n_splits)
+        return list(gkf.split(df, groups=shuffled_groups))