"""Interpretability analysis for MACO models. Two-part analysis: A) Global interpretability: - Functional-group reactivity and attention heatmaps - XGBoost SHAP global analysis (summary + dependence) - Functional-group-level pH attention statistics B) Case-level interpretability: - Molecular attention visualization (atom coloring) - XGB SHAP waterfall for selected molecules """ from __future__ import annotations import json import warnings from pathlib import Path from typing import Dict, List, Optional, Tuple import joblib import matplotlib.pyplot as plt import matplotlib.colors as mcolors import numpy as np import pandas as pd import shap import torch from matplotlib.patches import FancyBboxPatch from rdkit import Chem from rdkit.Chem import Draw, AllChem, Descriptors from PIL import Image import io from .train_pipeline import ( setup_plot_style, OXIDANT_COLORS, OXIDANT_DISPLAY, OXIDANT_LABEL, FIGURE_BG, GRID_COLOR, FIGURE_EXPORT_FORMATS, ) warnings.filterwarnings("ignore", category=FutureWarning) # --------------------------------------------------------------------------- # Functional group SMARTS definitions # --------------------------------------------------------------------------- FUNCTIONAL_GROUPS = { "Aromatic ring": "[c]", "Phenol": "[OX2H][c]", "Amine (−NH₂)": "[NX3H2;!$(NC=O)]", "Secondary amine": "[NX3H1;!$(NC=O)]", "Tertiary amine": "[NX3H0;!$(NC=O);!$([NX3](=O)=O)]", "Amide": "[NX3][CX3](=[OX1])", "Carboxylic acid": "[CX3](=O)[OX2H1]", "Ester": "[CX3](=O)[OX2][#6]", "Ketone": "[CX3](=[OX1])([#6])[#6]", "Aldehyde": "[CX3H1](=O)", "Alcohol": "[OX2H][CX4]", "Ether": "[OD2]([#6])[#6]", "Alkene": "[CX3]=[CX3]", "Alkyne": "[CX2]#[CX2]", "Nitrile": "[CX2]#[NX1]", "Nitro": "[$([NX3](=O)=O)]", "Sulfide (−S−)": "[#16X2]([#6])[#6]", "Sulfoxide": "[#16X3](=[OX1])([#6])[#6]", "Sulfone": "[#16X4](=[OX1])(=[OX1])([#6])[#6]", "Halogen (F)": "[F]", "Halogen (Cl)": "[Cl]", "Halogen (Br)": "[Br]", "Halogen (I)": "[I]", "Pyridine": "c1ccncc1", "Imidazole": "c1cnc[nH]1", "Indole": "c1ccc2[nH]ccc2c1", "Heterocyclic N": "[nR]", "Phosphate": "[PX4](=O)([OX2])([OX2])[OX2]", "Thiol": "[SX2H]", "Acyl halide": "[CX3](=[OX1])[F,Cl,Br,I]", } FG_DISPLAY_LABELS = { "Aromatic ring": "Aromatic\nring", "Phenol": "Phenol", "Amine (−NH₂)": "1° amine", "Secondary amine": "2° amine", "Tertiary amine": "3° amine", "Amide": "Amide", "Carboxylic acid": "Carboxylic\nacid", "Ester": "Ester", "Ketone": "Ketone", "Aldehyde": "Aldehyde", "Alcohol": "Alcohol", "Ether": "Ether", "Alkene": "Alkene", "Alkyne": "Alkyne", "Nitrile": "Nitrile", "Nitro": "Nitro", "Sulfide (−S−)": "Sulfide", "Sulfoxide": "Sulfoxide", "Sulfone": "Sulfone", "Halogen (F)": "F", "Halogen (Cl)": "Cl", "Halogen (Br)": "Br", "Halogen (I)": "I", "Pyridine": "Pyridine", "Imidazole": "Imidazole", "Indole": "Indole", "Heterocyclic N": "Heterocyclic\nN", "Phosphate": "Phosphate", "Thiol": "Thiol", "Acyl halide": "Acyl\nhalide", } DISPLAY_TOP_N = 14 def _detect_functional_groups(smiles: str) -> Dict[str, int]: """Detect functional groups in a molecule.""" mol = Chem.MolFromSmiles(smiles) if mol is None: return {name: 0 for name in FUNCTIONAL_GROUPS} result = {} for name, smarts in FUNCTIONAL_GROUPS.items(): pattern = Chem.MolFromSmarts(smarts) if pattern is None: result[name] = 0 continue matches = mol.GetSubstructMatches(pattern) result[name] = len(matches) return result def _detect_functional_group_atoms(smiles: str) -> Dict[str, List[int]]: """Map each functional group to the unique atom indices it covers.""" mol = Chem.MolFromSmiles(smiles) if mol is None: return {} fg_atoms: Dict[str, List[int]] = {} for name, smarts in FUNCTIONAL_GROUPS.items(): pattern = Chem.MolFromSmarts(smarts) if pattern is None: continue atom_idx_set = set() for match in mol.GetSubstructMatches(pattern): atom_idx_set.update(int(atom_idx) for atom_idx in match) if atom_idx_set: fg_atoms[name] = sorted(atom_idx_set) return fg_atoms def _short_fg_label(name: str) -> str: return FG_DISPLAY_LABELS.get(name, name) def _aggregate_fg_records(attn_df: pd.DataFrame) -> pd.DataFrame: """Collapse fold-level functional-group attention to molecule level.""" if attn_df.empty: return pd.DataFrame() grouped = attn_df.groupby(["row_id", "smiles", "oxidant", "functional_group"], as_index=False).agg( attn_ox_mean=("attn_ox", "mean"), attn_pH_mean=("attn_pH", "mean"), attn_ox_std=("attn_ox", "std"), attn_pH_std=("attn_pH", "std"), n_fg_atoms=("n_fg_atoms", "first"), logk=("logk", "first"), ) return grouped def _select_display_functional_groups( mol_fg_df: pd.DataFrame, top_n: int = DISPLAY_TOP_N, ) -> List[str]: """Choose the most supported functional groups for main-text figures.""" if mol_fg_df.empty: return [] support = mol_fg_df.groupby("functional_group").agg( n_molecules=("row_id", "nunique"), n_oxidants=("oxidant", "nunique"), ) support = support[support["n_oxidants"] >= 2].sort_values( ["n_molecules", "n_oxidants"], ascending=[False, False] ) selected = support.head(top_n).index.tolist() return [fg for fg in FUNCTIONAL_GROUPS.keys() if fg in selected] def _build_fg_reactivity_summary(df: pd.DataFrame) -> pd.DataFrame: records = [] for row_id, row in df.reset_index(drop=True).iterrows(): smi = row.get("canonical_smiles", row.get("SMILES", "")) fg_counts = _detect_functional_groups(smi) for fg, count in fg_counts.items(): if count > 0: records.append({ "row_id": int(row_id), "oxidant": row["oxidant"], "functional_group": fg, "logk": float(row.get("logk_val", row.get("logk", np.nan))), }) if not records: return pd.DataFrame() records_df = pd.DataFrame(records) return records_df.groupby(["oxidant", "functional_group"], as_index=False).agg( mean_logk=("logk", "mean"), n_molecules=("row_id", "nunique"), ) def _build_fg_attention_summary(mol_fg_df: pd.DataFrame) -> pd.DataFrame: if mol_fg_df.empty: return pd.DataFrame() return mol_fg_df.groupby(["oxidant", "functional_group"], as_index=False).agg( attn_ox_mean=("attn_ox_mean", "mean"), attn_pH_mean=("attn_pH_mean", "mean"), attn_pH_sd=("attn_pH_mean", "std"), n_molecules=("row_id", "nunique"), ) def _build_heatmap_matrix( summary_df: pd.DataFrame, fg_names: List[str], oxidants: List[str], value_col: str, count_col: str = "n_molecules", min_count: int = 3, ) -> Tuple[np.ndarray, np.ndarray]: values = np.full((len(oxidants), len(fg_names)), np.nan) counts = np.zeros((len(oxidants), len(fg_names)), dtype=int) for i, ox in enumerate(oxidants): for j, fg in enumerate(fg_names): row = summary_df[(summary_df["oxidant"] == ox) & (summary_df["functional_group"] == fg)] if row.empty: continue count = int(row[count_col].iloc[0]) if count < min_count: continue values[i, j] = float(row[value_col].iloc[0]) counts[i, j] = count return values, counts def _style_heatmap_axes(ax: plt.Axes, fg_names: List[str], oxidant_labels: List[str]) -> None: ax.set_xticks(range(len(fg_names))) ax.set_xticklabels([_short_fg_label(fg) for fg in fg_names], rotation=38, ha="right", fontsize=12.2) ax.set_yticks(range(len(oxidant_labels))) ax.set_yticklabels(oxidant_labels, fontsize=15) ax.set_xticks(np.arange(len(fg_names) + 1) - 0.5, minor=True) ax.set_yticks(np.arange(len(oxidant_labels) + 1) - 0.5, minor=True) ax.grid(which="minor", color="white", linestyle="-", linewidth=1.0, alpha=0.75) ax.tick_params(which="minor", bottom=False, left=False) for spine in ax.spines.values(): spine.set_visible(False) def _annotate_heatmap( ax: plt.Axes, values: np.ndarray, counts: np.ndarray, value_fmt: str, big_font: float, small_font: float, cmap=None, norm=None, ) -> None: for i in range(values.shape[0]): for j in range(values.shape[1]): value = values[i, j] if np.isnan(value): continue if cmap is not None and norm is not None: r, g, b, _ = cmap(norm(value)) luminance = 0.299 * r + 0.587 * g + 0.114 * b text_color = "#222222" if luminance > 0.62 else "white" else: text_color = "#222222" ax.text( j, i - 0.08, format(value, value_fmt), ha="center", va="center", fontsize=big_font, color=text_color, fontweight="bold", ) ax.text( j, i + 0.18, f"n={counts[i, j]}", ha="center", va="center", fontsize=small_font, color=text_color, alpha=0.95, ) def _save_fig(fig: plt.Figure, fig_dir: Path, name: str): for fmt in FIGURE_EXPORT_FORMATS: fig.savefig(fig_dir / f"{name}.{fmt}", bbox_inches="tight", dpi=700 if fmt == "png" else None) plt.close(fig) # --------------------------------------------------------------------------- # 2A.1: Functional Group × Oxidant Reactivity # --------------------------------------------------------------------------- def plot_functional_group_heatmap( df: pd.DataFrame, fig_dir: Path, prefix: str, ) -> pd.DataFrame: """Legacy fallback heatmap of mean logk by functional group × oxidant.""" setup_plot_style() # Detect functional groups for all molecules fg_records = [] for _, row in df.iterrows(): smi = row.get("canonical_smiles", row.get("SMILES", "")) fg_counts = _detect_functional_groups(smi) fg_counts["oxidant"] = row["oxidant"] fg_counts["logk"] = row.get("logk_val", row.get("logk", np.nan)) fg_records.append(fg_counts) fg_df = pd.DataFrame(fg_records) # Compute mean logk for molecules containing each functional group per oxidant oxidants = ["OH", "SO4", "CO3"] fg_names = list(FUNCTIONAL_GROUPS.keys()) heatmap_data = np.full((len(oxidants), len(fg_names)), np.nan) count_data = np.zeros((len(oxidants), len(fg_names)), dtype=int) for i, ox in enumerate(oxidants): ox_df = fg_df[fg_df["oxidant"] == ox] for j, fg in enumerate(fg_names): mask = ox_df[fg] > 0 if mask.sum() >= 3: heatmap_data[i, j] = ox_df.loc[mask, "logk"].mean() count_data[i, j] = int(mask.sum()) # Filter: keep FGs that have data for at least 2 oxidants valid_cols = np.sum(~np.isnan(heatmap_data), axis=0) >= 2 heatmap_data = heatmap_data[:, valid_cols] count_data = count_data[:, valid_cols] fg_names_filtered = [fg_names[i] for i in range(len(fg_names)) if valid_cols[i]] if len(fg_names_filtered) == 0: return pd.DataFrame() fig, ax = plt.subplots(figsize=(max(12, len(fg_names_filtered) * 0.6), 5)) # Custom colormap cmap = plt.cm.YlOrRd.copy() cmap.set_bad(color="#f0f0f0") im = ax.imshow(heatmap_data, cmap=cmap, aspect="auto", interpolation="nearest") # Annotate cells for i in range(len(oxidants)): for j in range(len(fg_names_filtered)): val = heatmap_data[i, j] cnt = count_data[i, j] if not np.isnan(val): text_color = "white" if val > np.nanpercentile(heatmap_data, 75) else "black" ax.text(j, i, f"{val:.1f}\n(n={cnt})", ha="center", va="center", fontsize=7.5, color=text_color, fontweight="medium") ax.set_xticks(range(len(fg_names_filtered))) ax.set_xticklabels(fg_names_filtered, rotation=55, ha="right", fontsize=9) ax.set_yticks(range(len(oxidants))) ox_labels = ["HO•", OXIDANT_DISPLAY["SO4"], OXIDANT_DISPLAY["CO3"]] ax.set_yticklabels(ox_labels, fontsize=12) cbar = fig.colorbar(im, ax=ax, shrink=0.8, pad=0.02) cbar.set_label("Mean log $k$ (M⁻¹s⁻¹)", fontsize=12) ax.set_title( "Functional Group Reactivity Across Oxidant Systems", fontsize=15, fontweight="semibold", pad=14, ) fig.tight_layout() _save_fig(fig, fig_dir, f"{prefix}_fg_oxidant_heatmap") # Save data result_df = pd.DataFrame(heatmap_data.T, index=fg_names_filtered, columns=oxidants) result_df.index.name = "functional_group" return result_df def plot_functional_group_dual_panel( df: pd.DataFrame, fg_attn_df: pd.DataFrame, fig_dir: Path, prefix: str, ) -> Tuple[pd.DataFrame, pd.DataFrame]: """Main-text Figure 7: single-panel FG-level oxidant attention heatmap.""" setup_plot_style() mol_fg_df = _aggregate_fg_records(fg_attn_df) if mol_fg_df.empty: return pd.DataFrame(), pd.DataFrame() fg_names = _select_display_functional_groups(mol_fg_df, top_n=DISPLAY_TOP_N) if not fg_names: return pd.DataFrame(), pd.DataFrame() oxidants = ["OH", "SO4", "CO3"] oxidant_labels = ["HO•", OXIDANT_DISPLAY["SO4"], OXIDANT_DISPLAY["CO3"]] fg_attention_summary = _build_fg_attention_summary(mol_fg_df) fg_reactivity_summary = _build_fg_reactivity_summary(df) attn_values, attn_counts = _build_heatmap_matrix( fg_attention_summary, fg_names, oxidants, value_col="attn_ox_mean", count_col="n_molecules", min_count=3, ) fig, ax = plt.subplots( 1, 1, figsize=(max(14.8, len(fg_names) * 1.08), 5.8), ) cmap_a = plt.cm.magma.copy() cmap_a.set_bad(color="#f3f0f5") im_a = ax.imshow(attn_values, aspect="auto", cmap=cmap_a, interpolation="nearest") _style_heatmap_axes(ax, fg_names, oxidant_labels) _annotate_heatmap( ax, attn_values, attn_counts, ".3f", big_font=11.2, small_font=8.8, cmap=im_a.cmap, norm=im_a.norm, ) ax.set_title( "AI-Derived Functional-Group Attention by Radical Type", fontsize=17.0, fontweight="semibold", pad=12, ) cbar_a = fig.colorbar(im_a, ax=ax, fraction=0.026, pad=0.018) cbar_a.set_label("Mean attention weight", fontsize=13) fig.subplots_adjust(left=0.06, right=0.94, top=0.90, bottom=0.19) _save_fig(fig, fig_dir, f"{prefix}_fg_oxidant_heatmap") fg_attention_export = fg_attention_summary[fg_attention_summary["functional_group"].isin(fg_names)].copy() fg_reactivity_export = fg_reactivity_summary[fg_reactivity_summary["functional_group"].isin(fg_names)].copy() fg_attention_export["display_label"] = fg_attention_export["functional_group"].map(_short_fg_label) fg_reactivity_export["display_label"] = fg_reactivity_export["functional_group"].map(_short_fg_label) return fg_reactivity_export, fg_attention_export def plot_functional_group_boxplot( df: pd.DataFrame, fig_dir: Path, prefix: str, top_n: int = 12, ) -> None: """Box plots of logk distribution by functional group, split by oxidant.""" setup_plot_style() # Detect functional groups fg_records = [] for _, row in df.iterrows(): smi = row.get("canonical_smiles", row.get("SMILES", "")) fg_counts = _detect_functional_groups(smi) fg_counts["oxidant"] = row["oxidant"] fg_counts["logk"] = row.get("logk_val", row.get("logk", np.nan)) fg_records.append(fg_counts) fg_df = pd.DataFrame(fg_records) # Find most common functional groups (by total hits) fg_names = list(FUNCTIONAL_GROUPS.keys()) fg_total = {fg: int((fg_df[fg] > 0).sum()) for fg in fg_names} top_fgs = sorted(fg_total, key=fg_total.get, reverse=True)[:top_n] fig, axes = plt.subplots(3, 4, figsize=(16, 11)) axes = axes.flatten() ox_colors = {"OH": "#7f8c8d", "SO4": OXIDANT_COLORS["SO4"], "CO3": OXIDANT_COLORS["CO3"]} ox_display = {"OH": "HO•", "SO4": OXIDANT_DISPLAY["SO4"], "CO3": OXIDANT_DISPLAY["CO3"]} for idx, fg in enumerate(top_fgs): ax = axes[idx] box_data = [] box_labels = [] colors = [] for ox in ["OH", "SO4", "CO3"]: ox_mask = (fg_df["oxidant"] == ox) & (fg_df[fg] > 0) if ox_mask.sum() >= 3: box_data.append(fg_df.loc[ox_mask, "logk"].values) box_labels.append(ox_display[ox]) colors.append(ox_colors[ox]) if box_data: bp = ax.boxplot(box_data, labels=box_labels, patch_artist=True, widths=0.6) for patch, color in zip(bp["boxes"], colors): patch.set_facecolor(color) patch.set_alpha(0.6) for element in ["whiskers", "caps", "medians"]: for line in bp[element]: line.set_color("#34495e") line.set_linewidth(1.2) ax.set_title(fg, fontsize=10, fontweight="medium") ax.set_ylabel("log $k$", fontsize=9) ax.tick_params(labelsize=8) # Hide unused axes for idx in range(len(top_fgs), len(axes)): axes[idx].set_visible(False) fig.suptitle( "Reactivity Distribution by Functional Group & Oxidant", fontsize=16, fontweight="semibold", y=1.01, ) fig.tight_layout() _save_fig(fig, fig_dir, f"{prefix}_fg_boxplot") # --------------------------------------------------------------------------- # 2A.2: SHAP Global Analysis (XGBoost) # --------------------------------------------------------------------------- def run_shap_analysis( model_paths: List[Path], X: np.ndarray, feature_names: np.ndarray, ox_ids: np.ndarray, fig_dir: Path, prefix: str, model_type: str = "xgb_desc", ) -> Optional[np.ndarray]: """Compute SHAP values and generate summary/dependence plots.""" setup_plot_style() print(f" Computing SHAP values for {model_type}...") # Average SHAP across folds all_shap_values = [] for mp in model_paths: model = joblib.load(mp) explainer = shap.TreeExplainer(model) sv = explainer.shap_values(X) all_shap_values.append(sv) mean_shap = np.mean(all_shap_values, axis=0) # --- SHAP Summary (Beeswarm) Plot --- fig, ax = plt.subplots(figsize=(10, 8)) shap.summary_plot( mean_shap, X, feature_names=feature_names, max_display=20, show=False, plot_size=None, ) plt.title( f"SHAP Feature Importance — {model_type.upper().replace('_', '-')}", fontsize=15, fontweight="semibold", pad=12, ) plt.tight_layout() fig = plt.gcf() _save_fig(fig, fig_dir, f"{prefix}_shap_summary_{model_type}") # --- SHAP Bar Plot --- fig, ax = plt.subplots(figsize=(10, 7)) shap.summary_plot( mean_shap, X, feature_names=feature_names, plot_type="bar", max_display=20, show=False, plot_size=None, ) plt.title( f"Mean |SHAP| — {model_type.upper().replace('_', '-')}", fontsize=15, fontweight="semibold", pad=12, ) plt.tight_layout() fig = plt.gcf() _save_fig(fig, fig_dir, f"{prefix}_shap_bar_{model_type}") # --- SHAP Dependence Plots for top features --- mean_abs_shap = np.mean(np.abs(mean_shap), axis=0) top_feat_idx = np.argsort(mean_abs_shap)[::-1][:6] fig, axes = plt.subplots(2, 3, figsize=(16, 10)) axes_flat = axes.flatten() ox_color_map = {0: "#7f8c8d", 1: OXIDANT_COLORS["SO4"], 2: OXIDANT_COLORS["CO3"]} for plot_idx, feat_idx in enumerate(top_feat_idx): ax = axes_flat[plot_idx] feat_name = feature_names[feat_idx] if feat_idx < len(feature_names) else f"Feature {feat_idx}" for oid in [0, 1, 2]: mask = ox_ids == oid if mask.sum() == 0: continue label = OXIDANT_LABEL.get(oid, str(oid)) if label == "OH": label_disp = "HO•" else: label_disp = OXIDANT_DISPLAY.get(label, label) color = ox_color_map[oid] ax.scatter( X[mask, feat_idx], mean_shap[mask, feat_idx], c=color, alpha=0.35, s=12, label=label_disp, rasterized=True, ) ax.set_xlabel(feat_name, fontsize=10) ax.set_ylabel("SHAP value", fontsize=10) ax.axhline(0, color="#bdc3c7", linewidth=0.8) ax.legend(fontsize=8, loc="best") ax.set_title(feat_name, fontsize=11, fontweight="medium") fig.suptitle( f"SHAP Dependence Plots — {model_type.upper().replace('_', '-')}", fontsize=15, fontweight="semibold", ) fig.tight_layout(rect=[0, 0, 1, 0.96]) _save_fig(fig, fig_dir, f"{prefix}_shap_dependence_{model_type}") return mean_shap # --------------------------------------------------------------------------- # 2A.3: MACO Attention Statistics by Functional Group # --------------------------------------------------------------------------- def extract_attention_stats( model_paths: List[Path], df: pd.DataFrame, device: torch.device, ) -> pd.DataFrame: """Extract fold-level attention weights aggregated to functional groups.""" from torch_geometric.loader import DataLoader from .data_pipeline import MolDataset from .model import MACO ds = MolDataset(df.reset_index(drop=True)) fg_cache: Dict[str, Dict[str, List[int]]] = {} records = [] for fold_idx, mp in enumerate(model_paths): state = torch.load(mp, map_location=device, weights_only=False) atom_in = state.get("gnn.lin1.weight", next(iter(state.values()))).shape[-1] if "gnn.lin1.weight" in state: atom_in = state["gnn.lin1.weight"].shape[1] hidden = state["gnn.lin1.weight"].shape[0] else: # Handle _orig_mod prefix for k, v in state.items(): if "gnn.lin1.weight" in k: atom_in = v.shape[1] hidden = v.shape[0] break model = MACO( atom_in_channels=atom_in, edge_in_channels=6, hidden_channels=hidden, num_layers=4, num_timesteps=3, dropout=0.0, ).to(device) clean_state = {k.replace("_orig_mod.", ""): v for k, v in state.items()} model.load_state_dict(clean_state, strict=False) model.eval() loader = DataLoader(ds, batch_size=32, shuffle=False) sample_idx = 0 with torch.no_grad(): for batch in loader: batch = batch.to(device) out = model(batch) attn_ox = out["attn_ox"].cpu().numpy() attn_pH = out["attn_pH"].cpu().numpy() batch_vec = batch.batch.cpu().numpy() for graph_idx in range(batch_vec.max() + 1): atom_mask = batch_vec == graph_idx global_idx = sample_idx + graph_idx if global_idx >= len(ds): break row_df = df.iloc[global_idx] ox_name = row_df.get("oxidant") if pd.isna(ox_name) or ox_name is None: ox_id = int(row_df.get("oxidant_id", 0)) ox_name = {0: "OH", 1: "SO4", 2: "CO3"}.get(ox_id, "?") smi = row_df.get("canonical_smiles", row_df.get("SMILES", "")) if smi not in fg_cache: fg_cache[smi] = _detect_functional_group_atoms(smi) fg_atom_map = fg_cache[smi] if not fg_atom_map: continue a_ox = attn_ox[atom_mask] a_pH = attn_pH[atom_mask] for fg_name, atom_indices in fg_atom_map.items(): valid_idx = [idx for idx in atom_indices if idx < len(a_ox)] if not valid_idx: continue records.append({ "fold": fold_idx, "row_id": int(global_idx), "smiles": smi, "oxidant": ox_name, "functional_group": fg_name, "attn_ox": float(np.sum(a_ox[valid_idx])), "attn_pH": float(np.sum(a_pH[valid_idx])), "n_fg_atoms": int(len(valid_idx)), "logk": float(row_df.get("logk", row_df.get("logk_val", np.nan))), }) sample_idx += int(batch_vec.max()) + 1 return pd.DataFrame(records) def plot_attention_by_atom_type( attn_df: pd.DataFrame, fig_dir: Path, prefix: str, cleaned_df: Optional[pd.DataFrame] = None, ) -> pd.DataFrame: """Main-text Figure 8: functional-group-level pH attention analysis.""" setup_plot_style() mol_fg_df = _aggregate_fg_records(attn_df) if mol_fg_df.empty: return pd.DataFrame() fg_names = _select_display_functional_groups(mol_fg_df, top_n=DISPLAY_TOP_N) if not fg_names: return pd.DataFrame() fg_attention_summary = _build_fg_attention_summary(mol_fg_df) ph_oxidants = [ox for ox in ["SO4", "CO3"] if ox in fg_attention_summary["oxidant"].unique()] if not ph_oxidants: return pd.DataFrame() ph_labels = [OXIDANT_DISPLAY[ox] for ox in ph_oxidants] ph_values, ph_counts = _build_heatmap_matrix( fg_attention_summary, fg_names, ph_oxidants, value_col="attn_pH_mean", count_col="n_molecules", min_count=3, ) focus_oxidant = "CO3" if "CO3" in ph_oxidants else ph_oxidants[-1] focus_df = fg_attention_summary[ (fg_attention_summary["oxidant"] == focus_oxidant) & (fg_attention_summary["functional_group"].isin(fg_names)) & (fg_attention_summary["n_molecules"] >= 3) ].copy() focus_df = focus_df.sort_values("attn_pH_mean", ascending=False).head(8) focus_df["attn_pH_se"] = focus_df["attn_pH_sd"].fillna(0.0) / np.sqrt(focus_df["n_molecules"].clip(lower=1)) fig, axes = plt.subplots( 2, 1, figsize=(max(15.0, len(fg_names) * 1.0), 9.6), gridspec_kw={"height_ratios": [1.0, 1.05], "hspace": 0.42}, ) cmap = plt.cm.Blues.copy() cmap.set_bad(color="#f4f6f8") im = axes[0].imshow(ph_values, aspect="auto", cmap=cmap, interpolation="nearest") _style_heatmap_axes(axes[0], fg_names, ph_labels) _annotate_heatmap( axes[0], ph_values, ph_counts, ".3f", big_font=11.0, small_font=8.6, cmap=im.cmap, norm=im.norm, ) axes[0].set_title( "(a) Functional-Group pH Attention Across pH-Variable Datasets", fontsize=16.2, fontweight="semibold", pad=12, ) cbar = fig.colorbar(im, ax=axes[0], fraction=0.022, pad=0.015) cbar.set_label("Mean pH attention weight", fontsize=12.8) bar_colors = plt.cm.Blues(np.linspace(0.42, 0.9, max(len(focus_df), 1)))[::-1] y_pos = np.arange(len(focus_df)) axes[1].barh( y_pos, focus_df["attn_pH_mean"].values, xerr=focus_df["attn_pH_se"].values, color=bar_colors, edgecolor="white", linewidth=0.8, capsize=3, alpha=0.95, ) axes[1].set_yticks(y_pos) axes[1].set_yticklabels([_short_fg_label(fg).replace("\n", " ") for fg in focus_df["functional_group"]], fontsize=12.4) axes[1].invert_yaxis() axes[1].set_xlabel("Mean pH attention weight", fontsize=12.8) axes[1].set_title( f"(b) Highest pH-Sensitive Functional Groups for {OXIDANT_DISPLAY[focus_oxidant]}", fontsize=16.2, fontweight="semibold", pad=12, ) mean_line = float(focus_df["attn_pH_mean"].mean()) if len(focus_df) > 0 else 0.0 axes[1].axvline(mean_line, color="#c0392b", linestyle="--", linewidth=1.2, alpha=0.75) axes[1].text(mean_line, len(focus_df) - 0.3 if len(focus_df) > 0 else 0, " mean", color="#c0392b", fontsize=9, va="bottom", ha="left") axes[1].grid(axis="x", alpha=0.25) x_upper = 0.05 if len(focus_df) > 0: x_upper = float((focus_df["attn_pH_mean"] + focus_df["attn_pH_se"].fillna(0.0)).max() + 0.12) axes[1].set_xlim(0, x_upper) for spine in ["top", "right", "left"]: axes[1].spines[spine].set_visible(False) for idx, row in enumerate(focus_df.itertuples(index=False)): axes[1].text( row.attn_pH_mean + max(row.attn_pH_se, 0.002) + 0.004, idx, f"{row.attn_pH_mean:.3f} (n={int(row.n_molecules)})", va="center", ha="left", fontsize=11.4, fontweight="medium", ) fig.subplots_adjust(left=0.11, right=0.95, top=0.95, bottom=0.11, hspace=0.42) _save_fig(fig, fig_dir, f"{prefix}_attention_by_atom_type") return fg_attention_summary # --------------------------------------------------------------------------- # 2B: Case-level Interpretability # --------------------------------------------------------------------------- def select_representative_molecules( pred_df: pd.DataFrame, knn_dists: Optional[np.ndarray] = None, n_cases: int = 8, ) -> pd.DataFrame: """Select diverse representative molecules from the test set.""" cases = [] for ox_id, ox_name in [(1, "SO4"), (2, "CO3")]: ox_df = pred_df[pred_df["oxidant_id"] == ox_id].copy() if len(ox_df) == 0: continue ox_df = ox_df.copy() ox_df["error"] = ox_df["pred_maco"] - ox_df["logk"] ox_df["abs_error"] = ox_df["error"].abs() # Best prediction (lowest error) best = ox_df.nsmallest(1, "abs_error") cases.append(best) # Worst prediction (highest error) worst = ox_df.nlargest(1, "abs_error") cases.append(worst) # Highest reactivity high_k = ox_df.nlargest(1, "logk") if high_k.index[0] not in [c.index[0] for c in cases]: cases.append(high_k) # Lowest reactivity low_k = ox_df.nsmallest(1, "logk") if low_k.index[0] not in [c.index[0] for c in cases]: cases.append(low_k) result = pd.concat(cases).drop_duplicates(subset=["SMILES", "oxidant_id"]) return result.head(n_cases) def plot_molecule_attention( model_paths: List[Path], case_df: pd.DataFrame, device: torch.device, fig_dir: Path, prefix: str, ) -> None: """Visualize attention weights on molecular structures.""" setup_plot_style() from torch_geometric.loader import DataLoader from .data_pipeline import MolDataset, ATOM_Z_SET from .model import MACO ds = MolDataset(case_df.reset_index(drop=True)) # Collect attention from all folds all_attn_ox = {i: [] for i in range(len(ds))} all_attn_pH = {i: [] for i in range(len(ds))} for mp in model_paths: state = torch.load(mp, map_location=device, weights_only=False) for k, v in state.items(): if "gnn.lin1.weight" in k: atom_in = v.shape[1] hidden = v.shape[0] break model = MACO( atom_in_channels=atom_in, edge_in_channels=6, hidden_channels=hidden, num_layers=4, num_timesteps=3, dropout=0.0, ).to(device) clean_state = {k.replace("_orig_mod.", ""): v for k, v in state.items()} model.load_state_dict(clean_state, strict=False) model.eval() loader = DataLoader(ds, batch_size=len(ds), shuffle=False) with torch.no_grad(): for batch in loader: batch = batch.to(device) out = model(batch) attn_ox = out["attn_ox"].cpu().numpy() attn_pH = out["attn_pH"].cpu().numpy() batch_vec = batch.batch.cpu().numpy() for g_idx in range(batch_vec.max() + 1): atom_mask = batch_vec == g_idx all_attn_ox[g_idx].append(attn_ox[atom_mask]) all_attn_pH[g_idx].append(attn_pH[atom_mask]) # Average over folds n_mols = len(ds) n_cols = min(4, n_mols) n_mol_rows = (n_mols + n_cols - 1) // n_cols n_rows = 2 * n_mol_rows # 2 rows per row of molecules (ox + pH) fig, axes = plt.subplots(n_rows, n_cols, figsize=(n_cols * 4, n_rows * 3.5)) if n_rows == 1: axes = axes.reshape(1, -1) if n_cols == 1: axes = axes.reshape(-1, 1) # Hide all axes first, then show only those with content for ax_row in axes: for ax in ax_row: ax.set_axis_off() cmap_attn = plt.cm.YlOrRd for mol_idx in range(n_mols): row_offset = (mol_idx // n_cols) * 2 col = mol_idx % n_cols # Average attention across folds mean_ox = np.mean(all_attn_ox[mol_idx], axis=0) mean_pH = np.mean(all_attn_pH[mol_idx], axis=0) smi = case_df.iloc[mol_idx].get("SMILES", "") mol = Chem.MolFromSmiles(smi) if mol is None: continue ox_id = int(case_df.iloc[mol_idx].get("oxidant_id", 0)) ox_name = {0: "OH", 1: "SO4", 2: "CO3"}.get(ox_id, "?") logk_true = case_df.iloc[mol_idx].get("logk", np.nan) logk_pred = case_df.iloc[mol_idx].get("pred_maco", np.nan) for attn_idx, (attn_vals, attn_label) in enumerate([(mean_ox, "Oxidant attn"), (mean_pH, "pH attn")]): ax = axes[row_offset + attn_idx, col] if n_cols > 1 else axes[row_offset + attn_idx, 0] # Normalize attention for coloring if attn_vals.max() > attn_vals.min(): norm_attn = (attn_vals - attn_vals.min()) / (attn_vals.max() - attn_vals.min()) else: norm_attn = np.ones_like(attn_vals) * 0.5 # Color atoms atom_colors = {} for a_idx in range(mol.GetNumAtoms()): if a_idx < len(norm_attn): rgba = cmap_attn(norm_attn[a_idx]) atom_colors[a_idx] = rgba # Draw molecule drawer = Draw.MolDraw2DSVG(400, 300) drawer.drawOptions().addAtomIndices = False drawer.drawOptions().padding = 0.1 # Use atom highlighting highlight_atoms = list(range(min(mol.GetNumAtoms(), len(norm_attn)))) highlight_colors = { a_idx: cmap_attn(norm_attn[a_idx])[:3] for a_idx in highlight_atoms } highlight_radii = {a_idx: 0.4 for a_idx in highlight_atoms} drawer.DrawMolecule( mol, highlightAtoms=highlight_atoms, highlightAtomColors=highlight_colors, highlightAtomRadii=highlight_radii, highlightBonds=[], ) drawer.FinishDrawing() svg_text = drawer.GetDrawingText() # Convert SVG to image for matplotlib try: import cairosvg png_data = cairosvg.svg2png(bytestring=svg_text.encode()) img = Image.open(io.BytesIO(png_data)) except ImportError: # Fallback: save SVG and use simple visualization img = Draw.MolToImage(mol, size=(400, 300), highlightAtoms=highlight_atoms, highlightColor=(1.0, 0.6, 0.6)) ax.imshow(img, aspect="equal") ax.set_axis_off() ox_disp = OXIDANT_DISPLAY.get(ox_name, ox_name) if ox_name in OXIDANT_DISPLAY else "HO•" if attn_idx == 0: ax.set_title( f"{ox_disp} | True: {logk_true:.2f} Pred: {logk_pred:.2f}\n{attn_label}", fontsize=9, fontweight="medium", pad=4, ) else: ax.set_title(attn_label, fontsize=9, pad=2) fig.suptitle( "Molecular Attention Visualization — Case Studies", fontsize=16, fontweight="semibold", y=1.01, ) fig.tight_layout() _save_fig(fig, fig_dir, f"{prefix}_case_attention") def plot_shap_waterfall_cases( model_paths: List[Path], case_df: pd.DataFrame, X_cases: np.ndarray, feature_names: np.ndarray, cleaned_df: pd.DataFrame, fig_dir: Path, prefix: str, ) -> None: """SHAP waterfall plots for selected case molecules.""" setup_plot_style() if len(X_cases) == 0: return # Compute SHAP for all folds all_shap = [] for mp in model_paths: model = joblib.load(mp) explainer = shap.TreeExplainer(model) sv = explainer.shap_values(X_cases) all_shap.append(sv) mean_shap = np.mean(all_shap, axis=0) n_cases = min(len(X_cases), 6) fig, axes = plt.subplots(n_cases, 1, figsize=(11, n_cases * 3.5)) if n_cases == 1: axes = [axes] for i in range(n_cases): ax = axes[i] shap_vals = mean_shap[i] top_idx = np.argsort(np.abs(shap_vals))[::-1][:12] vals = shap_vals[top_idx] names = [feature_names[j] if j < len(feature_names) else f"F{j}" for j in top_idx] feat_vals = X_cases[i, top_idx] colors = ["#c0392b" if v > 0 else "#2980b9" for v in vals] y_pos = range(len(vals) - 1, -1, -1) ax.barh(y_pos, vals, color=colors, alpha=0.8, edgecolor="white", height=0.7) ax.set_yticks(list(y_pos)) ax.set_yticklabels([f"{n} = {v:.2f}" for n, v in zip(names, feat_vals)], fontsize=8.5) ax.axvline(0, color="#7f8c8d", linewidth=0.8) smi = case_df.iloc[i].get("SMILES", "") ox_id = int(case_df.iloc[i].get("oxidant_id", 0)) ox_name = {0: "OH", 1: "SO4", 2: "CO3"}.get(ox_id, "?") ox_disp = OXIDANT_DISPLAY.get(ox_name, ox_name) if ox_name in OXIDANT_DISPLAY else "HO•" logk = case_df.iloc[i].get("logk", np.nan) smi_short = smi if len(smi) <= 35 else smi[:32] + "…" ax.set_title(f"{smi_short} | {ox_disp} | log k = {logk:.2f}", fontsize=10, fontweight="medium") ax.set_xlabel("SHAP value", fontsize=9) fig.suptitle( "SHAP Waterfall — Case Studies (XGB-DESC)", fontsize=15, fontweight="semibold", y=1.01, ) fig.tight_layout() _save_fig(fig, fig_dir, f"{prefix}_shap_waterfall_cases") # --------------------------------------------------------------------------- # Main orchestrator # --------------------------------------------------------------------------- def run_interpretability( data_dir: Path, artifacts_dir: Path, split_mode: str, seed: int = 42, device: Optional[torch.device] = None, ) -> Dict: """Run full interpretability analysis for one split mode.""" if device is None: device = torch.device("cuda" if torch.cuda.is_available() else "cpu") print(f"\n{'='*60}") print(f" Interpretability Analysis — {split_mode} split") print(f"{'='*60}") run_root = artifacts_dir / "full" / f"seed_{seed}" / split_mode fig_dir = run_root / "figures" meta_dir = run_root / "metadata" fig_dir.mkdir(parents=True, exist_ok=True) meta_dir.mkdir(parents=True, exist_ok=True) cleaned_df = pd.read_csv(data_dir / "cleaned_group1.csv") trainval_df = pd.read_csv(data_dir / f"{split_mode}_split" / "trainval.csv") test_df = pd.read_csv(data_dir / f"{split_mode}_split" / "test.csv") pred_df = pd.read_csv(run_root / "predictions" / f"{split_mode}_test_predictions.csv") desc_raw = np.load(data_dir / "rdkit_desc_raw.npy") desc_names = np.load(data_dir / "rdkit_desc_names.npy", allow_pickle=True) fp_all = np.load(data_dir / "morgan_fp.npy") import json as _json with open(data_dir / "ph_stats.json") as _f: ph_stats = _json.load(_f) prefix = split_mode maco_paths = sorted(run_root.glob("models/*maco_fold*.pt")) xgb_desc_paths = sorted(run_root.glob("models/*xgb_desc_fold*.joblib")) attn_df = pd.DataFrame() # --- 2A.1: Functional Group Heatmap & Boxplot --- print(" [1/5] Functional-group attention and reactivity...") if maco_paths: attn_df = extract_attention_stats(maco_paths, cleaned_df, device) fg_reactivity_data, fg_attention_data = plot_functional_group_dual_panel(cleaned_df, attn_df, fig_dir, prefix) if not fg_reactivity_data.empty: fg_reactivity_data.to_csv(meta_dir / f"{prefix}_fg_heatmap_data.csv", index=False) if not fg_attention_data.empty: fg_attention_data.to_csv(meta_dir / f"{prefix}_fg_attention_data.csv", index=False) else: fg_data = plot_functional_group_heatmap(cleaned_df, fig_dir, prefix) if not fg_data.empty: fg_data.to_csv(meta_dir / f"{prefix}_fg_heatmap_data.csv") plot_functional_group_boxplot(cleaned_df, fig_dir, prefix) # --- 2A.2: SHAP Global Analysis --- print(" [2/5] SHAP analysis (XGB-DESC)...") # Build features for full dataset (same as tree_models.py) from .tree_models import build_desc_features X_train_desc, _, train_imputer, train_scaler = build_desc_features( trainval_df, desc_raw, ph_stats, fit_scaler=True ) # SHAP on training data (to show global patterns) if xgb_desc_paths: # Get oxidant ids for trainval ox_ids_train = trainval_df["oxidant_id"].values if "oxidant_id" in trainval_df.columns else np.zeros(len(trainval_df)) # Subsample for SHAP efficiency n_shap = min(800, len(X_train_desc)) rng = np.random.RandomState(42) shap_idx = rng.choice(len(X_train_desc), n_shap, replace=False) X_shap = X_train_desc[shap_idx] ox_shap = ox_ids_train[shap_idx] # Feature names for desc model (desc + pH + oxidant dummies) desc_feat_names = list(desc_names) + ["pH_norm", "ox_OH", "ox_SO4", "ox_CO3"] desc_feat_names_arr = np.array(desc_feat_names[:X_shap.shape[1]]) run_shap_analysis(xgb_desc_paths, X_shap, desc_feat_names_arr, ox_shap, fig_dir, prefix, "xgb_desc") else: print(" [WARN] No XGB-DESC models found, skipping SHAP.") # --- 2A.3: Functional-group pH Attention Statistics --- print(" [3/5] Functional-group pH attention...") if maco_paths and not attn_df.empty: attn_agg = plot_attention_by_atom_type(attn_df, fig_dir, prefix, cleaned_df=cleaned_df) if not attn_agg.empty: attn_agg.to_csv(meta_dir / f"{prefix}_attention_stats.csv", index=False) else: print(" [WARN] No MACO models found, skipping attention analysis.") # --- 2B: Case Studies --- print(" [4/5] Selecting representative case molecules...") cases = select_representative_molecules(pred_df, n_cases=8) # Ensure columns required by MolDataset if "is_standard" not in cases.columns: cases["is_standard"] = True print(" [5/5] Case-level visualizations...") if maco_paths and len(cases) > 0: plot_molecule_attention(maco_paths, cases, device, fig_dir, prefix) if xgb_desc_paths and len(cases) > 0: # Build proper features for case molecules using train imputer/scaler X_cases_desc, _, _, _ = build_desc_features( cases, desc_raw, ph_stats, imputer=train_imputer, scaler=train_scaler, fit_scaler=False, ) desc_feat_names_case = list(desc_names) + ["pH_norm", "ox_OH", "ox_SO4", "ox_CO3"] desc_feat_names_arr_case = np.array(desc_feat_names_case[:X_cases_desc.shape[1]]) plot_shap_waterfall_cases( xgb_desc_paths, cases, X_cases_desc, desc_feat_names_arr_case, cleaned_df, fig_dir, prefix, ) cases.to_csv(meta_dir / f"{prefix}_case_molecules.csv", index=False) print(f" [OK] Interpretability analysis complete -- {len(cases)} case molecules analyzed") return {"n_cases": len(cases), "n_functional_groups": len(FUNCTIONAL_GROUPS)}