import itertools import json import os import tempfile import biotite.structure as bs import gradio as gr import matplotlib.colors as mcolors import matplotlib.patches as mpatches import matplotlib.pyplot as plt import networkx as nx import numpy as np import torch from biotite.database import rcsb from biotite.sequence import io as seqio from biotite.structure import filter_amino_acids, io, spread_residue_wise, to_sequence from gradio_molecule3d import Molecule3D from huggingface_hub import HfApi, snapshot_download from huggingface_hub.utils import GatedRepoError, RepositoryNotFoundError from loguru import logger from matplotlib.cm import ScalarMappable from matplotlib.colors import Normalize from scipy.spatial.distance import cdist from rocketshp import RocketSHP from rocketshp import load_sequence as get_sequence_features from rocketshp import load_structure as get_structure_features from rocketshp.network import ( build_allosteric_network, calculate_centrality, ) os.environ["OMP_NUM_THREADS"] = "4" os.environ["CUDA_VISIBLE_DEVICES"] = "0" def plot_predictions( rmsf: np.ndarray, gcc_lmi: np.ndarray, shp: np.ndarray, title: str = "RocketSHP Predictions", font_scale: float = 1.0, ): with plt.style.context( { "font.size": 12 * font_scale, "legend.fontsize": 12 * font_scale, "axes.labelsize": 12 * font_scale, "axes.titlesize": 12 * font_scale, } ): plot_file = tempfile.NamedTemporaryFile(mode="wb", delete=False, suffix=".png") fig = plt.figure(figsize=(6, 6)) gs = fig.add_gridspec(2, 2) ax1 = fig.add_subplot(gs[0, 0]) ax2 = fig.add_subplot(gs[0, 1]) ax3 = fig.add_subplot(gs[1, :]) fig.suptitle(title) ax1.plot(rmsf, label="RMSF") ax1.set_title("RMSF") ax1.set_xlabel("Residue Index") ax1.set_ylabel("RMSF (Å)") ax1.spines["top"].set_visible(False) ax1.spines["right"].set_visible(False) ax2.imshow(gcc_lmi, cmap="viridis", aspect="equal", vmin=0, vmax=1) ax2.set_title("GCC-LMI") ax2.set_xlabel("Residue Index") ax2.set_ylabel("Residue Index") ax3.imshow(shp.T, cmap="binary", vmin=0, vmax=1, interpolation="none") ax3.set_title("SHP") ax3.set_xlabel("Residue Index") ax3.set_ylabel("Structure Token\nIndex") ax3.set_ylim(21, -1) plt.tight_layout() plt.savefig(plot_file.name) return fig, plot_file.name def download_predictions(job_name, rmsf, gcc_lmi, shp): outfile = tempfile.NamedTemporaryFile(mode="w+", delete=False, suffix=".json") json_content = { "model": job_name, "rmsf": rmsf.tolist(), "gcc_lmi": gcc_lmi.tolist(), "shp": shp.tolist(), } outfile.write(json.dumps(json_content)) return outfile.name def toggle_inputs(model): if "seq" in model or "mini" in model: return ( gr.update(visible=True), # sequence input gr.update(visible=True), # fasta upload gr.update(visible=False), # structure input gr.update(visible=False), # structure upload gr.update(visible=False), # structure output gr.update(visible=False), # chain input ) return ( gr.update(visible=False), # sequence input gr.update(visible=False), # fasta upload gr.update(visible=True), # structure input gr.update(visible=True), # structure upload gr.update(visible=True), # structure output gr.update(visible=True), # chain input ) def predict_rocketshp( model_variant: str, sequence: str | None, sequence_file: str | None, structure_code: str | None, structure_file: str | None, chain_id: str | None, token: gr.OAuthToken | None, ): logger.info(f"sequence text: {sequence}") logger.info(f"sequence file: {sequence_file}") logger.info(f"structure code: {structure_code}") logger.info(f"structure file: {structure_file}") logger.info(f"model variant: {model_variant}") is_authorized, token = check_user_access(token) logger.info(f"User is authorized: {is_authorized}") if not is_authorized: raise gr.Error("Failed to authorize repository access.") # Load the model device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu") model = RocketSHP.load_from_checkpoint(model_variant).to(device) is_sequence_model = "seq" in model_variant or "mini" in model_variant if is_sequence_model: if sequence_file is not None: if sequence != "": gr.Warning("Sequence file provided, ignoring text box.") sequence = str(seqio.load_sequence(sequence_file)) logger.info(sequence) elif sequence == "": raise gr.Error("Sequence input is required for the selected model.") struct_features = None logger.info("Loading sequence features...") seq_features = get_sequence_features(sequence, device=device, HF_TOKEN=token) else: if structure_file is None: if structure_code == "": raise gr.Error("Structure input is required for the selected model.") structure_code = structure_code.strip().upper() structure_tmp_dir = tempfile.TemporaryDirectory() structure_file = rcsb.fetch( structure_code.strip(), "pdb", target_path=structure_tmp_dir.name, ) logger.info(structure_tmp_dir) logger.info(structure_file) elif structure_code != "": gr.Warning(f"PDB file provided, ignoring PDB code {structure_code}.") try: structure = io.load_structure(structure_file) except ValueError: raise gr.Error(f"Invalid PDB Code {structure_code}") if isinstance(structure, bs.AtomArrayStack): gr.Info( f"{len(structure)} models found in structure file, using the first model." ) structure = structure[0] unique_chains = np.unique(structure.chain_id) if len(unique_chains) == 1: old_chain_id = chain_id chain_id = unique_chains[0] if chain_id != old_chain_id: gr.Warning( f"Only one chain ({chain_id}) found in structure, using this chain." ) elif chain_id not in unique_chains: raise gr.Error( f"Chain ID {chain_id} not found in the provided structure. Available chains: {', '.join(unique_chains)}" ) try: structure = structure[structure.chain_id == chain_id] structure = structure[filter_amino_acids(structure)] except Exception as e: raise gr.Error( f"Error processing structure with chain ID {chain_id}: {str(e)}" ) if not len(structure): raise gr.Error( f"No amino acid residues found in chain {chain_id} of the provided structure." ) logger.info(len(structure)) logger.info(structure[:3]) logger.info("Loading structure features...") struct_features = get_structure_features( structure, device=device, HF_TOKEN=token ) sequence = str(to_sequence(structure)[0][0]) seq_features = get_sequence_features(sequence, device=device, HF_TOKEN=token) # Make predictions with torch.no_grad(): logger.info(f"Sequence length: {len(sequence)}") logger.info( f"Structure features shape: {struct_features.shape if struct_features is not None else 'N/A'}" ) logger.info( f"Sequence features shape: {seq_features.shape if seq_features is not None else 'N/A'}" ) try: dynamics_pred = model( { "seq_feats": seq_features, "struct_feats": struct_features, } ) except Exception as e: raise gr.Error(f"Error during model prediction: {str(e)}") # Extract predictions rmsf = dynamics_pred["rmsf"].squeeze().cpu().numpy() gcc_lmi = dynamics_pred["gcc_lmi"].squeeze().cpu().numpy() shp = dynamics_pred["shp"].squeeze().cpu().numpy() if is_sequence_model: ca_dist = dynamics_pred["ca_dist"].squeeze().cpu().numpy() else: ca_struct = structure[bs.filter_amino_acids(structure)] ca_struct = structure[structure.atom_name == "CA"] ca_dist = cdist(ca_struct.coord, ca_struct.coord) ca_dist /= 10.0 # convert to nm fig, plot_file_name = plot_predictions( rmsf, gcc_lmi, shp, title=f"RocketSHP Predictions (model={model_variant})", ) json_file_name = download_predictions(model_variant, rmsf, gcc_lmi, shp) if is_sequence_model: out_structure_file_name = None else: out_structure_file = tempfile.NamedTemporaryFile( mode="w+", delete=False, suffix=".pdb" ) bfactors = spread_residue_wise(structure, rmsf) structure.set_annotation("b_factor", bfactors) io.save_structure(out_structure_file.name, structure) out_structure_file_name = out_structure_file.name seq_display_tuples = [*zip(list(sequence), rmsf)] return ( rmsf, gcc_lmi, shp, ca_dist, sequence, json_file_name, plot_file_name, fig, out_structure_file_name, seq_display_tuples, ) def cluster_network(G: nx.Graph, k: int = 5): """ Cluster the network using Girvan-Newman algorithm. """ logger.info(f"Nodes: {G.number_of_nodes()}") logger.info(f"Edges: {G.number_of_edges()}") logger.info(f"Number of connected components: {nx.number_connected_components(G)}") logger.info(f"Connected: {nx.is_connected(G)}") comp = nx.community.girvan_newman(G) # limited = itertools.takewhile(lambda c: len(c) <= k, comp) # for communities in limited: # clusts = tuple(sorted(c) for c in communities) clusts = next(itertools.islice(comp, k - 1, k)) return clusts def visualize_network( sequence: str, gcc_lmi: np.ndarray, ca_dist: np.ndarray, ca_threshold: float = 12.0, cluster_k: int = 5, progress=gr.Progress(), ): if sequence == "!=" or not len(gcc_lmi): raise gr.Error( "No valid GCC-LMI data available for network visualization, please run RocketSHP first." ) # Build network from GCC-LMI predictions and distance mask progress(0.1, desc="Building allosteric network...") network = build_allosteric_network(gcc_lmi, ca_dist, distance_cutoff=ca_threshold) if not len(network.edges): raise gr.Error( "The resulting allosteric network has no edges. Try increasing the Cα distance cutoff." ) if cluster_k > len(network.nodes): raise gr.Error( f"Number of clusters k={cluster_k} cannot be greater than the number of nodes={len(network.nodes)} in the network." ) if nx.number_connected_components(network) > cluster_k: raise gr.Error( f"Number of connected components in the network ({nx.number_connected_components(network)}) exceeds the number of clusters k={cluster_k}. " "Try increasing the Cα distance cutoff." ) if not nx.is_connected(network): gr.Warning( "Network is not connected. This may result in extra clusters. To connect the network, try increasing the Cα distance cutoff." ) # Apply clustering to identify communities progress(0.2, desc="Clustering network...") communities = cluster_network(network, k=cluster_k - 1) # Calculate betweenness centrality progress(0.8, desc="Calculating centrality...") centralities = calculate_centrality(network) betweenness_centrality = centralities["betweenness"] progress(0.9, desc="Generating plot...") fig, ax = plt.subplots(2, 1, figsize=(10, 8)) pos = nx.spring_layout(network) cmap = plt.cm.tab10 # or whatever colormap you're using cluster_color = [] cluster_label = [] for i, (cluster, color) in enumerate(zip(communities, cmap.colors, strict=False)): hex_color = mcolors.to_hex(color) cluster_color.extend([hex_color] * len(cluster)) cluster_label.extend([i] * len(cluster)) if len(cluster_label) != len(network.nodes): raise gr.Error( "Mismatch between number of nodes and assigned clusters. " "This may be due to the network being disconnected." ) nx.draw( network, pos, with_labels=True, node_color=betweenness_centrality, edge_color="gray", ax=ax[0], cmap="coolwarm", ) nx.draw( network, pos, with_labels=True, node_color=cluster_color, edge_color="gray", ax=ax[1], ) # For ax[0] - Betweenness Centrality ax[0].set_title("Betweenness Centrality") norm = Normalize(vmin=min(betweenness_centrality), vmax=max(betweenness_centrality)) sm = ScalarMappable(cmap="coolwarm", norm=norm) sm.set_array([]) # Required for colorbar plt.colorbar(sm, ax=ax[0]) # For ax[1] - Clusters ax[1].set_title("Network Clusters") unique_clusters = [cmap.colors[i] for i in range(len(communities))] legend_elements = [ mpatches.Patch(facecolor=color, label=f"Cluster {i + 1}") for i, color in enumerate(unique_clusters) ] ax[1].legend(handles=legend_elements) plt.tight_layout() progress(1.0, desc="Done") normalize_centrality = (betweenness_centrality - betweenness_centrality.min()) / ( betweenness_centrality.max() - betweenness_centrality.min() ) comm_highlight = [ (aa, f"Cluster {i + 1}") for aa, i in zip(list(sequence), cluster_label) ] bc_highlight = [*zip(list(sequence), normalize_centrality)] out_cluster_file = tempfile.NamedTemporaryFile( mode="w+", delete=False, suffix=".csv" ) out_cluster_file.write("Residue_Index,Amino_Acid,Cluster,Betweenness Centrality\n") for i, (aa, cluster_id, bet) in enumerate( zip(list(sequence), cluster_label, betweenness_centrality) ): out_cluster_file.write(f"{i + 1},{aa},Cluster_{cluster_id + 1},{bet}\n") out_cluster_file_name = out_cluster_file.name return fig, bc_highlight, comm_highlight, out_cluster_file_name def check_user_access(oauth_token: gr.OAuthToken | None): """Check if user is logged in and has access to private repo""" if oauth_token is None: raise gr.Error("Please log in to use this Space") token = oauth_token.token try: # Try to access a file from your private repo api = HfApi(token=token) # Test access by trying to get repo info _ = api.repo_info( repo_id="EvolutionaryScale/esm3-sm-open-v1", repo_type="model", # or "dataset" or "space" token=token, ) gr.Info("Successfully authenticated, downloading ESM3 weights...") snapshot_download(repo_id="EvolutionaryScale/esm3-sm-open-v1", token=token) return ( True, token, ) except GatedRepoError: raise gr.Error( "You need to request access to the private repository at https://huggingface.co/username/private-repo-name", ) except RepositoryNotFoundError: raise gr.Error("You don't have access to the required repository") except Exception as e: raise gr.Error(f"Error checking access: {str(e)}") reps = [ { "model": 0, "chain": "", "resname": "", "style": "cartoon", "color": """ function(atom) { var b = atom.b || 0; // Map B-factor to color (adjust min/max as needed) var min_b = 0; var max_b = 100; var normalized = (b - min_b) / (max_b - min_b); // Blue (low) to Red (high) var r = Math.floor(normalized * 255); var b_color = Math.floor((1 - normalized) * 255); return 'rgb(' + r + ', 0, ' + b_color + ')'; } """, # "residue_range": "", "around": 0, "byres": False, # "visible": False, "opacity": 1, } ] rocketshp_gradio = gr.Blocks(title="RocketSHP") # , theme=gr.themes.Monochrome()) with rocketshp_gradio: gr.Markdown(""" # RocketSHP 🚀 RocketSHP enables ultra-fast prediction of protein dynamics and flexibility from amino acid sequences and/or protein structures. Trained on thousands of molecular dynamics trajectories, it predicts multiple dynamics-related features simultaneously: - Root-Mean-Square Fluctuations (RMSF) - Generalized Correlation Coefficients with Linear Mutual Information (GCC-LMI) - Structural Heterogeneity Profiles (SHP) This approach bridges the gap between static structural biology and dynamic functional understanding, providing a computational tool that complements experimental approaches at unprecedented speed and scale. - 📄: [Paper](https://www.biorxiv.org/content/10.1101/2025.06.12.659353v1) - 💻: [GitHub](https://github.com/flatironinstitute/RocketSHP/tree/main) To run RocketSHP, your HuggingFace account should have access to [ESM3-open](https://huggingface.co/EvolutionaryScale/esm3-sm-open-v1) weights. If you don't have access, please go through the gating process on HuggingFace to gain access to the model weights. """) rmsf = gr.State([]) gcc = gr.State([]) shp = gr.State([]) ca_dist = gr.State([]) sequence = gr.State([]) gr.LoginButton() model_variant = gr.Dropdown( label="Select RocketSHP Model", choices=["latest", "v1_seq", "v1_mini"], value="latest", ) structure_input = gr.Textbox(label="Enter PDB ID") chain_input = gr.Textbox(label="Chain", value="A", max_length=1) structure_upload = gr.File( label="Upload Structure File (PDB or MMCIF)", file_types=[".pdb", ".cif"], ) sequence_input = gr.Textbox(label="Paste FASTA Sequence", visible=False) sequence_upload = gr.File( label="Upload FASTA File", file_types=[".fasta", ".fa"], visible=False, ) predict_button = gr.Button("Run RocketSHP") with gr.Tabs(): with gr.Tab("View Results"): seq_display = gr.HighlightedText(label="RMSF per Residue") mol_display = Molecule3D( confidenceLabel="RMSF", label="Structure", reps=reps, show_label=True, ) fig_display = gr.Plot(label="Prediction Plots") with gr.Tab("Allosteric Network"): ca_threshold = gr.Slider( label="Cα Distance Cutoff (Å)", minimum=4.0, maximum=12.0, step=0.1, value=8.0, ) cluster_k = gr.Slider( label="Number of Clusters (k)", minimum=2, maximum=10, step=1, value=5, ) network_button = gr.Button("Visualize Network") net_fig = gr.Plot(label="Allosteric Network") htext_cmap = { f"Cluster {i + 1}": mcolors.to_hex(color) for i, color in enumerate(plt.cm.tab10.colors) } seq_betweenness = gr.HighlightedText(label="Betweenness Centrality") seq_clusters = gr.HighlightedText( label="Network Clusters", combine_adjacent=True, color_map=htext_cmap ) with gr.Tab("Downloads"): download_file = gr.File(label="Download Results") fig_file = gr.File(label="Download Plot") clusters_file = gr.File(label="Download Network Clusters") model_variant.change( toggle_inputs, inputs=model_variant, outputs=[ sequence_input, sequence_upload, structure_input, structure_upload, chain_input, mol_display, ], ) predict_button.click( predict_rocketshp, inputs=[ model_variant, sequence_input, sequence_upload, structure_input, structure_upload, chain_input, ], outputs=[ rmsf, gcc, shp, ca_dist, sequence, download_file, fig_file, fig_display, mol_display, seq_display, ], ) network_button.click( visualize_network, inputs=[sequence, gcc, ca_dist, ca_threshold, cluster_k], outputs=[net_fig, seq_betweenness, seq_clusters, clusters_file], ) if __name__ == "__main__": rocketshp_gradio.launch(share=True)