add knowledge graph visualization section to user guide

ProtHGT_app.py

@@ -22,7 +22,7 @@ import random
 #         with open(".setup_done", "w") as f:
 #             f.write("done")
 
-# # ❌ Remove the info message after initialization is complete
+# # Remove the info message after initialization is complete
 # loading_placeholder.empty()
 
 from run_prothgt_app import *
@@ -70,10 +70,12 @@ with st.expander("🚀 Upcoming Features"):
     
     - **Real-time data retrieval for new proteins**: Currently, ProtHGT can only generate predictions for proteins that already exist in our knowledge graph. We are developing a new feature that will allow users to **predict functions for entirely new proteins starting from their sequences**. This will work by **retrieving relevant relationship data in real time from external source databases** (e.g., UniProt, STRING, and other biological repositories). The system will dynamically construct a knowledge graph for the query protein, incorporating its interactions, domains, pathways, and other biological associations before running function prediction. This approach will enable ProtHGT to analyze newly discovered or less-studied proteins even if they are not pre-annotated in our dataset.  
     - **Expanded embedding options**: Currently, this application represents proteins using **TAPE embeddings**, which serve as the initial numerical representations of protein sequences before being processed in the heterogeneous graph model. We are working on integrating **ProtT5** and **ESM-2** as alternative initial embeddings, allowing users to choose different sequence representations that may enhance performance for specific tasks. A detailed comparison of how these embeddings influence function prediction accuracy will be included in our upcoming publication.
-    - **Knowledge graph visualization for interpretability**: To improve model explainability, we are developing an interactive **knowledge graph visualization** feature. This will allow users to explore the biological relationships that contributed to ProtHGT's predictions for a given protein. Users will be able to inspect **protein interactions, GO annotations, domains, pathways, and other key connections** in a structured graphical format, making it easier to interpret and validate predictions.
 
     Stay tuned for updates and future publications!
     """)
+    st.success("""
+    ✅ **Knowledge graph visualization for interpretability** – Now available! Explore the biological relationships behind ProtHGT's predictions interactively. For each query protein, you can inspect protein interactions, GO annotations, domains, pathways, and other key connections in a structured graphical format. Navigate to the **"View Knowledge Graphs"** tab after generating predictions to try it out.
+    """)
 
 with st.sidebar:
 

pages/About.py

@@ -31,7 +31,7 @@ ProtHGT is a **heterogeneous graph transformer-based model** for automated prote
 
 Using transformer-based message passing, ProtHGT models complex biological relationships by propagating information across proteins and their functional associations in a structured graph. The model represents proteins using initial embeddings from **advanced protein language models (e.g., TAPE, ProtT5)** while integrating contextual information from pathways, domains, and molecular interactions. By employing knowledge **graph attention mechanisms**, ProtHGT learns to prioritize the most biologically relevant connections, improving prediction accuracy and interpretability.
 
-ProtHGT outperforms existing sequence- and graph-based methods, as demonstrated in evaluations on CAFA3 and DeepHGAT datasets. By incorporating a broader biological context through its knowledge graph, **the model improves function prediction across all Gene Ontology (GO) sub-ontologies**. Additionally, its attention-based framework allows researchers to trace predictions back to key contributing relationships in the graph, making it possible to explore new functional links, validate known annotations, and generate testable biological hypotheses.
+ProtHGT outperforms existing sequence- and graph-based methods, as demonstrated in evaluations on DeepHGAT and PROBE datasets. By incorporating a broader biological context through its knowledge graph, **the model improves function prediction across all Gene Ontology (GO) sub-ontologies**. Additionally, its attention-based framework allows researchers to trace predictions back to key contributing relationships in the graph, making it possible to explore new functional links, validate known annotations, and generate testable biological hypotheses.
 
 Overall workflow of ProtHGT is shown below.
 """)

pages/User_Guide.py

@@ -3,14 +3,14 @@ import streamlit as st
 st.sidebar.markdown('''
 # Sections
 - [How to use](#how-to-use)
+- [Knowledge Graph Visualization](#knowledge-graph-visualization)
+- [Running Locally](#running-locally)
 ''', unsafe_allow_html=True)
 
 st.markdown('''
 # ProtHGT User Guide
 ''')
 
-import streamlit as st
-
 st.markdown("""
 ProtHGT is a web-based tool for **automated protein function prediction** using heterogeneous graph transformers and knowledge graphs. Follow the steps below to generate predictions for your proteins.
 """)
@@ -18,6 +18,7 @@ ProtHGT is a web-based tool for **automated protein function prediction** using
 st.subheader("1. Select Proteins")
 st.markdown("""
 In the **sidebar**, choose how to input your proteins:
+- **Use example query**: Loads a random set of 5 proteins from the dataset to quickly explore the tool.
 - **Search Proteins**: Select or search UniProt IDs from the available dataset.
 - **Upload a File**: Upload a text file (.txt) containing UniProt IDs (one per line, max 100).    
 """)
@@ -34,31 +35,221 @@ Select which **Gene Ontology (GO) sub-ontology** to use for function prediction:
 - **All Categories** – Runs predictions for all three categories
 """)
 
-st.subheader("3. Generate Predictions")
+st.subheader("3. Set Generation Threshold (Optional)")
+st.markdown("""
+Use the **Generation threshold** slider to filter predictions at the point of generation. Only predictions with a probability equal to or above the threshold will be included in the output.
+
+Setting a threshold above 0 can significantly **reduce output size** and **speed up the app**, especially when processing many proteins or all GO categories.
+""")
+
+st.subheader("4. Generate Predictions")
 st.markdown("""
 Click **"Generate Predictions"** to start the analysis. The model will process the selected proteins and return predicted functional annotations.
 
-🔄 **Processing time**: A few minutes (depending on input size).
+🔄 **Processing time**: A few minutes (depending on input size). On the **first run of a new session**, the knowledge graph file (~1 GB) will be downloaded automatically — this may take a few additional minutes.
 """)
 
-st.subheader("4. View and Filter Results")
+st.subheader("5. View and Filter Results")
 st.markdown("""
 Once predictions are generated, use the filter options to refine the output:
 - **Filter by Protein** (UniProt ID)
 - **Filter by GO Category**
-- **Set Probability Range** (Adjust prediction confidence thresholds)
+- **Filter by GO Term ID** – Enter a specific GO term (e.g., GO:0003674) to search for it directly
+- **Set Probability Range** – Adjust prediction confidence thresholds
 
-Results are displayed in a sortable table, with **probabilities** indicating prediction confidence.
+Results are displayed in a sortable table, with **probabilities** indicating prediction confidence. UniProt IDs and GO IDs are clickable links that open the corresponding entry in UniProt and QuickGO, respectively.
 """)
 
 st.info("📥 Filtered predictions can be downloaded as a CSV file.")
 
-st.subheader("5. Start a New Query")
+st.subheader("6. Start a New Query")
 st.markdown("""
-After generating predictions, you can start a new query by selecting different options from the sidebar.
+After generating predictions, you can start a new query by selecting different options from the sidebar. Changing the protein selection or GO category will automatically reset the results.
 """)
 
-st.subheader("🚀 Running Locally?")
+st.divider()
+
+st.markdown("""## Knowledge Graph Visualization <span style="background-color: #28a745; color: white; font-size: 14px; font-weight: bold; padding: 3px 10px; border-radius: 12px; vertical-align: middle;">NEW</span>""", unsafe_allow_html=True)
+
 st.markdown("""
-For **larger datasets** or **custom analyses**, you can run ProtHGT locally using our [**GitHub repository**](https://github.com/HUBioDataLab/ProtHGT).
+After generating predictions, switch to the **"View Knowledge Graphs"** tab to explore the biological context behind the model's predictions. This feature is available when **10 or fewer proteins** are selected.
+""")
+
+st.subheader("Generating a Visualization")
+st.markdown("""
+Each query protein gets its own subtab. For each protein:
+
+1. Use the **"Maximum neighbors per edge type (first-degree)"** slider to control how many direct neighbors are shown per relationship type. Higher values show a denser graph.
+2. Use the **"Maximum neighbors per edge type (second-degree)"** slider to control neighbors-of-neighbors when second-degree edges are enabled. This is intentionally kept low (2–10) to avoid cluttered graphs.
+3. Click **"Generate Visualization"** to render the graph.
+""")
+
+st.subheader("What the Graph Shows")
+st.markdown("""
+The visualization renders a **subgraph of the full ProtHGT knowledge graph**, centered on the query protein. Edges and nodes are selected as follows:
+
+- **First-degree edges**: All relationship types that directly connect the query protein to other nodes in the knowledge graph are included (e.g., protein-domain, PPI, GO term annotations). For GO term edges, nodes are ranked by predicted probability and the top-N are shown based on the slider setting.
+- **Second-degree edges**: When enabled via the **"Include second-degree edges"** checkbox, neighbor nodes are also expanded — their own connections (excluding edges back to the query protein) are added to the graph, again limited by the second-degree slider.
 """)
+
+st.subheader("Reading the Graph")
+
+st.components.v1.html("""
+<style>
+    .kg-legend {
+        margin-top: 10px;
+        margin-bottom: 10px;
+        padding: 20px;
+        border: 1px solid #ddd;
+        border-radius: 5px;
+        font-family: Arial, sans-serif;
+        display: flex;
+        gap: 20px;
+    }
+    .legend-section-nodes {
+        flex: 2;
+    }
+    .legend-section-edges {
+        flex: 1;
+    }
+    .legend-title {
+        margin-bottom: 15px;
+        color: #333;
+        font-size: 16px;
+        font-weight: bold;
+    }
+    .nodes-grid {
+        display: grid;
+        grid-template-columns: repeat(2, 1fr);
+        gap: 12px;
+    }
+    .edges-grid {
+        display: grid;
+        grid-template-columns: 1fr;
+        gap: 12px;
+    }
+    .legend-item {
+        display: flex;
+        align-items: center;
+        padding: 4px;
+    }
+    .node-indicator {
+        width: 15px;
+        height: 15px;
+        border-radius: 50%;
+        margin-right: 10px;
+        flex-shrink: 0;
+    }
+    .edge-indicator {
+        width: 40px;
+        height: 3px;
+        margin-right: 10px;
+        flex-shrink: 0;
+    }
+    .legend-label {
+        font-size: 14px;
+    }
+</style>
+<div class="kg-legend">
+    <div class="legend-section-nodes">
+        <div class="legend-title">Node Types</div>
+        <div class="nodes-grid">
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #079dbb;"></div>
+                <span class="legend-label">Disease</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #58d0e8;"></div>
+                <span class="legend-label">Phenotype</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #815ac0;"></div>
+                <span class="legend-label">Drug</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #d2b7e5;"></div>
+                <span class="legend-label">Compound</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #6bbf59;"></div>
+                <span class="legend-label">Domain</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #ff8800;"></div>
+                <span class="legend-label">Biological Process</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #ffaa00;"></div>
+                <span class="legend-label">Molecular Function</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #ffc300;"></div>
+                <span class="legend-label">Cellular Component</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #720026;"></div>
+                <span class="legend-label">Pathway</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #ce4257;"></div>
+                <span class="legend-label">EC Number</span>
+            </div>
+            <div class="legend-item">
+                <div class="node-indicator" style="background-color: #3aa6a4;"></div>
+                <span class="legend-label">Protein</span>
+            </div>
+        </div>
+    </div>
+    <div class="legend-section-edges">
+        <div class="legend-title">Edge Colors</div>
+        <div class="edges-grid">
+            <div class="legend-item">
+                <div class="edge-indicator" style="background-color: #8338ec;"></div>
+                <span class="legend-label">Confirmed Prediction (Found in Ground Truth)</span>
+            </div>
+            <div class="legend-item">
+                <div class="edge-indicator" style="background-color: #c1121f;"></div>
+                <span class="legend-label">Novel Prediction (Not in Ground Truth)</span>
+            </div>
+            <div class="legend-item">
+                <div class="edge-indicator" style="background-color: #219ebc;"></div>
+                <span class="legend-label">Existing GO Term Annotation</span>
+            </div>
+            <div class="legend-item">
+                <div class="edge-indicator" style="background-color: #666666;"></div>
+                <span class="legend-label">Other Relationships</span>
+            </div>
+        </div>
+    </div>
+</div>
+""", height=320)
+
+st.markdown("""
+**Node colors** indicate the biological entity type of each node in the graph. The **query protein** is always shown as a larger node with a white background and red border, making it easy to identify at a glance.
+
+**Edge colors** indicate the nature of each connection:
+- **Purple** – The predicted GO term was also found in the ground truth annotations, confirming the model's prediction.
+- **Red** – The predicted GO term was not in the ground truth — this is a novel prediction made by the model.
+- **Blue** – An existing GO term annotation already present in the knowledge graph, included for context but not generated as a new prediction.
+- **Gray** – Other biological relationships such as protein-protein interactions, protein-domain associations, drug-target links, and pathway memberships.
+
+Hovering over any node or edge reveals a **tooltip** with the entity name, type, and prediction probability where applicable. Nodes and GO IDs are clickable links to their respective database entries (UniProt, QuickGO, InterPro, etc.).
+""")
+
+st.subheader("Controls and Downloads")
+st.markdown("""
+- **Include second-degree edges** checkbox – Toggles between first-degree-only and expanded graph views.
+- **Regenerate Visualization** – Re-renders the graph with updated slider settings. Use this after changing the neighbor limits.
+- **Download Visualized Edges** – Downloads a JSON file containing all edges shown in the current visualization, including source/target node IDs and prediction probabilities.
+""")
+
+st.warning("If you change the slider settings after generating a visualization, a warning will appear. Click **'Regenerate Visualization'** to apply the new settings.")
+
+st.info("For deeper exploration beyond second-degree connections, the complete knowledge graph can be downloaded from the link provided in the visualization tab.")
+
+st.divider()
+
+st.markdown("## Running Locally")
+st.markdown("""
+For **larger datasets** or **custom analyses**, you can run ProtHGT locally using our [**GitHub repository**](https://github.com/HUBioDataLab/ProtHGT).
+""")