pages/User_Guide.py

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
''')

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.
""")

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).    
""")
st.warning("⚠️ Currently, our system can only generate predictions for proteins that are already included in our knowledge graph. Real-time retrieval of relationship data from external source databases is not yet supported. We are actively working on integrating this capability in future updates. Stay tuned!")
st.info("📥 Selected proteins can be downloaded as a txt file.")


st.subheader("2. Choose Gene Ontology (GO) Category")
st.markdown("""
Select which **Gene Ontology (GO) sub-ontology** to use for function prediction:
- **Molecular Function (MF)** – Biochemical activity of the protein
- **Biological Process (BP)** – Biological roles and pathways
- **Cellular Component (CC)** – Location within the cell
- **All Categories** – Runs predictions for all three categories
""")

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). 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("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**
- **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. 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("6. Start a New Query")
st.markdown("""
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.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("""
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.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).
""")

st.markdown("""

""")