Add API documentation, help tooltips, zoom controls, and professional text

- Add API Documentation tab with Python client and cURL examples
- Add help tooltips to Stride and Threshold sliders explaining their function
- Add zoom controls (500bp, 1kb, 5kb, Full) using Plotly rangeselector
- Add minimap navigator using Plotly rangeslider for sequence overview
- Remove emojis throughout UI for professional appearance
- Update main description with technical/scientific language
- Update Embeddings tab with detailed mode descriptions
- Update About tab with architecture table, training details, parameter reference

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

app.py

@@ -98,18 +98,20 @@ def create_prediction_plot(positions, probabilities, threshold=0.3, regions=None
 
 
 def create_interactive_prediction_plot(positions, probabilities, threshold=0.3, regions=None):
-    """Create an interactive Plotly figure showing the prediction curve."""
+    """Create an interactive Plotly figure showing the prediction curve with minimap."""
     fig = go.Figure()
 
+    max_pos = max(positions) if positions else 1000
+
     # Main probability curve with fill
     fig.add_trace(go.Scatter(
         x=positions,
         y=probabilities,
         mode='lines',
-        name='CRISPR Score',
-        line=dict(color='royalblue', width=1),
+        name='Prediction Score',
+        line=dict(color='#2563eb', width=1.5),
         fill='tozeroy',
-        fillcolor='rgba(65, 105, 225, 0.2)',
+        fillcolor='rgba(37, 99, 235, 0.15)',
         hovertemplate='Position: %{x:,} bp<br>Score: %{y:.3f}<extra></extra>'
     ))
 
@@ -117,9 +119,10 @@ def create_interactive_prediction_plot(positions, probabilities, threshold=0.3,
     fig.add_hline(
         y=threshold,
         line_dash="dash",
-        line_color="red",
+        line_color="#dc2626",
         annotation_text=f"Threshold ({threshold})",
-        annotation_position="top right"
+        annotation_position="top right",
+        annotation_font_size=11
     )
 
     # Highlight detected CRISPR regions
@@ -127,25 +130,73 @@ def create_interactive_prediction_plot(positions, probabilities, threshold=0.3,
         for r in regions:
             fig.add_vrect(
                 x0=r['start'], x1=r['end'],
-                fillcolor="rgba(255, 0, 0, 0.15)",
+                fillcolor="rgba(220, 38, 38, 0.12)",
                 layer="below",
-                line_width=0,
-                annotation_text=f"Region {r['region_id']}",
+                line_width=1,
+                line_color="rgba(220, 38, 38, 0.3)",
+                annotation_text=f"CRISPR {r['region_id']}",
                 annotation_position="top left",
-                annotation_font_size=10
+                annotation_font_size=10,
+                annotation_font_color="#dc2626"
             )
 
     fig.update_layout(
-        title=dict(text='CRISPR Array Detection Score', font=dict(size=16)),
-        xaxis_title='Position (bp)',
-        yaxis_title='CRISPR Probability',
-        yaxis=dict(range=[0, 1], gridcolor='lightgray'),
-        xaxis=dict(range=[0, max(positions) if positions else 1000], gridcolor='lightgray'),
+        title=dict(
+            text='CRISPR Array Detection',
+            font=dict(size=14, color='#1f2937'),
+            x=0.5,
+            xanchor='center'
+        ),
+        xaxis=dict(
+            title='Position (bp)',
+            range=[0, max_pos],
+            gridcolor='#e5e7eb',
+            showgrid=True,
+            zeroline=False,
+            # Rangeslider for minimap navigation
+            rangeslider=dict(
+                visible=True,
+                thickness=0.08,
+                bgcolor='#f3f4f6',
+                bordercolor='#d1d5db',
+                borderwidth=1
+            ),
+            # Range selector buttons for quick zoom
+            rangeselector=dict(
+                buttons=list([
+                    dict(count=500, label="500bp", step="all", stepmode="backward"),
+                    dict(count=1000, label="1kb", step="all", stepmode="backward"),
+                    dict(count=5000, label="5kb", step="all", stepmode="backward"),
+                    dict(step="all", label="Full")
+                ]),
+                bgcolor='#f9fafb',
+                bordercolor='#d1d5db',
+                font=dict(size=10),
+                x=0,
+                y=1.15
+            )
+        ),
+        yaxis=dict(
+            title='CRISPR Probability',
+            range=[0, 1.05],
+            gridcolor='#e5e7eb',
+            showgrid=True,
+            zeroline=False,
+            tickformat='.1f'
+        ),
         hovermode='x unified',
         showlegend=True,
-        legend=dict(yanchor="top", y=0.99, xanchor="right", x=0.99),
-        height=400,
-        plot_bgcolor='white'
+        legend=dict(
+            yanchor="top", y=0.99,
+            xanchor="right", x=0.99,
+            bgcolor='rgba(255,255,255,0.8)',
+            bordercolor='#e5e7eb',
+            borderwidth=1
+        ),
+        height=480,
+        plot_bgcolor='white',
+        paper_bgcolor='white',
+        margin=dict(t=80, b=60)
     )
 
     return fig
@@ -908,67 +959,72 @@ with gr.Blocks(title="CRISPR Array Detection") as demo:
     gr.Markdown("""
 # CRISPR Array Detection
 
-Detect CRISPR arrays in DNA sequences using a BERT-based deep learning model (430M parameters), fine-tuned from a BERT model pre-trained on metagenomic and genomic microbial sequences.
+A deep learning approach for identifying CRISPR arrays in prokaryotic genome sequences. This tool employs a 24-layer BERT transformer architecture (~430M parameters) that was pre-trained on metagenomic contigs and complete microbial genomes, then fine-tuned on annotated CRISPR array sequences.
+
+**Method**: Input sequences are processed using a sliding window approach (1000 bp window, configurable stride). For each window, the model outputs a probability score ∈ [0,1] indicating the likelihood that the central region contains part of a CRISPR array. Overlapping predictions are aggregated to produce per-position scores across the full sequence length.
 
-**How it works**: The model scans your sequence with a sliding window and outputs a probability score (0-1) for each position indicating likelihood of being part of a CRISPR array.
+**Output**: Detected CRISPR regions are reported with genomic coordinates, mean prediction scores, and can be exported in standard formats (GFF3, CSV) for downstream analysis.
     """)
 
-    with gr.Tab("Predict & Visualize"):
-        gr.Markdown("Paste a DNA sequence or upload a FASTA file to get per-position CRISPR probability scores with interactive visualization.")
+    with gr.Tab("Prediction"):
         with gr.Row():
             with gr.Column(scale=1):
                 seq_input = gr.Textbox(
-                    label="DNA Sequence (min 1000 bp)",
-                    placeholder="Paste DNA sequence or FASTA...",
+                    label="Input Sequence",
+                    placeholder="Paste DNA sequence (FASTA format accepted)...",
                     lines=6,
-                    value=FLANKED_CRISPR_EXAMPLE
+                    value=FLANKED_CRISPR_EXAMPLE,
+                    info="Minimum length: 1000 bp. Accepts raw sequence or FASTA format."
                 )
                 file_upload = gr.File(
-                    label="Or upload FASTA file",
+                    label="Upload FASTA File",
                     file_types=[".fasta", ".fa", ".fna", ".txt"],
                     type="filepath"
                 )
                 with gr.Row():
                     stride_input = gr.Slider(
                         minimum=50, maximum=500, value=100, step=50,
-                        label="Stride"
+                        label="Stride (bp)",
+                        info="Step size between consecutive windows. Lower values increase resolution but require more computation."
                     )
                     threshold_input = gr.Slider(
                         minimum=0.1, maximum=0.9, value=0.3, step=0.05,
-                        label="Threshold"
+                        label="Detection Threshold",
+                        info="Minimum score to classify a region as CRISPR. Lower = more sensitive, higher = more specific."
                     )
                 with gr.Row():
-                    predict_btn = gr.Button("🔬 Analyze Sequence", variant="primary", size="lg")
-                gr.Markdown("**Load example:**")
+                    predict_btn = gr.Button("Run Analysis", variant="primary", size="lg")
+                gr.Markdown("**Example sequences:**")
                 with gr.Row():
                     gr.Button("Flanked CRISPR").click(
                         lambda: FLANKED_CRISPR_EXAMPLE, outputs=seq_input
                     )
-                    gr.Button("E. coli K-12").click(
+                    gr.Button("E. coli K-12 CRISPR I-E").click(
                         lambda: ECOLI_CRISPR_EXAMPLE, outputs=seq_input
                     )
                 with gr.Row():
-                    gr.Button("CRISPR Only").click(
+                    gr.Button("CRISPR Array").click(
                         lambda: CRISPR_EXAMPLE, outputs=seq_input
                     )
-                    gr.Button("Non-CRISPR").click(
+                    gr.Button("Negative Control").click(
                         lambda: NON_CRISPR_EXAMPLE, outputs=seq_input
                     )
                 result_summary = gr.Markdown()
-                with gr.Accordion("📥 Downloads", open=False, visible=False) as download_accordion:
-                    gr.Markdown("**Plot exports:**")
+                with gr.Accordion("Export Results", open=False, visible=False) as download_accordion:
+                    gr.Markdown("**Figures:**")
                     with gr.Row():
                         pred_download_png = gr.File(label="PNG", interactive=False)
                         pred_download_pdf = gr.File(label="PDF", interactive=False)
-                    gr.Markdown("**Data exports:**")
+                    gr.Markdown("**Data:**")
                     with gr.Row():
                         pred_download_csv = gr.File(label="CSV", interactive=False)
                         pred_download_gff = gr.File(label="GFF3", interactive=False)
                     with gr.Row():
                         pred_download_summary = gr.File(label="Summary", interactive=False)
             with gr.Column(scale=2):
-                plot_output = gr.Plot(label="CRISPR Score Profile (Interactive)")
-                with gr.Accordion("🧬 Sequence Viewer", open=False, visible=False) as seq_viewer_accordion:
+                plot_output = gr.Plot(label="Prediction Score Profile")
+                with gr.Accordion("Sequence Viewer", open=False, visible=False) as seq_viewer_accordion:
+                    gr.Markdown("*Color scale: blue (low score) → yellow (medium) → red (high score). Hover over nucleotides for exact values.*")
                     seq_viewer_html = gr.HTML(label="Color-coded sequence")
                 regions_output = gr.JSON(label="Detected Regions", visible=False)
 
@@ -999,54 +1055,53 @@ Detect CRISPR arrays in DNA sequences using a BERT-based deep learning model (43
         )
 
     with gr.Tab("Embeddings"):
-        gr.Markdown("""## State-Dynamic Plots
+        gr.Markdown("""
+### Hidden State Analysis
 
-Visualize how the model's internal representation changes across the sequence. The **State-Dynamics** mode projects embeddings to 2D/3D using UMAP and clusters similar regions together.
+Extract and visualize the model's internal representations (embeddings) from the transformer layers. The **State-Dynamics** mode applies UMAP dimensionality reduction to project the 768-dimensional embeddings into 2D/3D space, then performs agglomerative clustering to identify regions with similar activation patterns.
 
-**For CRISPR arrays**: Expect to see alternating colors in the bottom bar where repeats and spacers alternate. Repeats should cluster together (conserved pattern), while spacers cluster separately.
+**Biological interpretation**: In CRISPR arrays, repeat sequences share conserved motifs and should cluster together, while unique spacer sequences form distinct clusters. This creates a characteristic alternating pattern in the sequence map visualization.
 """)
         with gr.Row():
             with gr.Column(scale=1):
                 embed_seq = gr.Textbox(
-                    label="DNA Sequence (longer sequences work better)",
+                    label="Input Sequence",
                     placeholder="Paste DNA sequence...",
                     lines=6,
-                    value=EMBEDDING_CRISPR_EXAMPLE
+                    value=EMBEDDING_CRISPR_EXAMPLE,
+                    info="Longer sequences (>2000 bp) provide better clustering resolution."
                 )
                 embed_mode = gr.Radio(
                     choices=["state-dynamics", "mean", "max", "trajectory"],
                     value="state-dynamics",
                     label="Visualization Mode",
-                    info="state-dynamics: Interactive UMAP | mean/max: pooled heatmap | trajectory: per-window heatmap"
+                    info="state-dynamics: UMAP clustering | mean/max: pooled embedding | trajectory: per-window heatmap"
                 )
                 use_3d = gr.Checkbox(
-                    label="3D Visualization",
+                    label="3D UMAP Projection",
                     value=False,
-                    info="Enable 3D UMAP projection (drag to rotate)",
+                    info="Project embeddings to 3D space (interactive rotation)",
                     visible=True
                 )
                 with gr.Row():
-                    embed_btn = gr.Button("Analyze Embeddings", variant="primary")
+                    embed_btn = gr.Button("Extract Embeddings", variant="primary")
                 with gr.Row():
-                    gr.Button("Load CRISPR Example (3kb)").click(
+                    gr.Button("CRISPR Example (3kb)").click(
                         lambda: EMBEDDING_CRISPR_EXAMPLE, outputs=embed_seq
                     )
-                    gr.Button("Load Random Example (3kb)").click(
+                    gr.Button("Control Sequence (3kb)").click(
                         lambda: EMBEDDING_RANDOM_EXAMPLE, outputs=embed_seq
                     )
                 gr.Markdown("""
-**CRISPR Example Structure:**
-- Upstream: 0-600 bp (random)
-- Array: 600-2364 bp (25 repeats + 24 spacers)
-- Downstream: 2364-2964 bp (random)
+**Example structure:** 600 bp upstream | CRISPR array (25 repeats + 24 spacers) | 600 bp downstream
 """)
                 embed_summary = gr.Markdown()
-                with gr.Accordion("Downloads", open=False, visible=False) as embed_download_accordion:
+                with gr.Accordion("Export Results", open=False, visible=False) as embed_download_accordion:
                     with gr.Row():
                         download_png = gr.File(label="PNG", interactive=False)
                         download_pdf = gr.File(label="PDF", interactive=False)
             with gr.Column(scale=2):
-                embed_plot = gr.Plot(label="Embedding Visualization (Interactive)")
+                embed_plot = gr.Plot(label="Embedding Visualization")
 
         # Show/hide 3D checkbox based on mode
         embed_mode.change(
@@ -1065,40 +1120,121 @@ Visualize how the model's internal representation changes across the sequence. T
             outputs=[embed_plot, embed_summary, download_png, download_pdf, embed_download_accordion]
         )
 
+    with gr.Tab("API"):
+        gr.Markdown("""
+### Programmatic Access
+
+This tool can be accessed programmatically using the Gradio Python client or via HTTP requests.
+
+#### Python Client
+
+```python
+from gradio_client import Client
+
+# Connect to the API
+client = Client("genomenet/crispr-array-detection")
+
+# Run prediction
+result = client.predict(
+    sequence="ATGC...",      # DNA sequence (min 1000 bp)
+    stride=100,              # Window stride in bp
+    threshold=0.3,           # Detection threshold
+    api_name="/predict"
+)
+
+# result contains: (plot, summary, regions, png_path, pdf_path, csv_path, summary_path, gff_path, seq_viewer_html)
+```
+
+#### Extract Embeddings
+
+```python
+result = client.predict(
+    sequence="ATGC...",
+    mode="state-dynamics",   # or "mean", "max", "trajectory"
+    use_3d=False,
+    api_name="/get_embedding"
+)
+```
+
+#### cURL Example
+
+```bash
+curl -X POST "https://genomenet-crispr-array-detection.hf.space/api/predict" \\
+  -H "Content-Type: application/json" \\
+  -d '{"data": ["ATGCATGC...", 100, 0.3]}'
+```
+
+#### Output Formats
+
+| Format | Description |
+|--------|-------------|
+| CSV | Per-position scores: `position, probability, above_threshold` |
+| GFF3 | Standard genome annotation format for detected regions |
+| TXT | Human-readable summary with statistics |
+| PNG/PDF | Publication-ready figures |
+
+#### Rate Limits
+
+- Free tier: Standard HuggingFace rate limits apply
+- For high-throughput analysis, consider running the model locally
+
+#### Local Installation
+
+```bash
+git clone https://huggingface.co/spaces/genomenet/crispr-array-detection
+cd crispr-array-detection
+pip install -r requirements.txt
+python app.py
+```
+        """)
+
     with gr.Tab("About"):
         gr.Markdown("""
-## Model Details
+### Model Architecture
+
+| Component | Specification |
+|-----------|--------------|
+| Base model | BERT (Bidirectional Encoder Representations from Transformers) |
+| Layers | 24 transformer blocks |
+| Hidden size | 768 dimensions |
+| Attention heads | 12 |
+| Parameters | ~430 million |
+| Classification head | Bottleneck architecture |
+
+### Training
+
+**Pre-training corpus**: Metagenomic contigs and complete microbial genomes from public databases.
+
+**Fine-tuning data**: Annotated CRISPR arrays from bacterial and archaeal genomes, including positive examples from CRISPRCasdb and negative examples from non-CRISPR genomic regions.
+
+**Embedding extraction**: Hidden states are extracted from transformer layer 21 (768 dimensions per position).
 
-- **Architecture**: 24-layer BERT transformer with bottleneck classification head
-- **Parameters**: ~430 million
-- **Pre-training**: BERT model trained on metagenomic and genomic microbial sequences
-- **Fine-tuning**: Trained on annotated CRISPR arrays from bacterial genomes
-- **Input**: DNA sequence (1000 bp windows)
-- **Output**: Per-position probability (0 = non-CRISPR, 1 = CRISPR)
+### Parameters
 
-## How to Use
+| Parameter | Range | Default | Description |
+|-----------|-------|---------|-------------|
+| Stride | 50-500 bp | 100 bp | Step size between windows. Lower = higher resolution, more computation |
+| Threshold | 0.1-0.9 | 0.3 | Detection cutoff. Lower = more sensitive, higher = more specific |
+| Window size | Fixed | 1000 bp | Input window for the transformer model |
 
-1. **Paste your sequence** in the text box (minimum 1000 bp)
-2. **Click "Analyze Sequence"** to run the model
-3. **View the plot** showing CRISPR probability along the sequence
-4. Regions above the threshold (red) are predicted CRISPR arrays
+### Performance Considerations
 
-## Tips
+- **GPU recommended**: T4 or better for interactive use
+- **CPU inference**: Functional but slower (~10-30s per analysis)
+- **Memory**: ~2GB GPU memory required
 
-- Use **lower stride** (50) for finer resolution, higher stride (200-500) for faster analysis
-- Adjust **threshold** based on your needs: lower = more sensitive, higher = more specific
-- The model works best on bacterial/archaeal genomic sequences
+### Citation
 
-## Citation
+If you use this tool in your research, please cite:
 
-Based on [CRISPRArrayDetection](https://github.com/Ziyu-Mu/CRISPRArrayDetection) by Ziyu Mu
+> Mu, Z. (2024). Deep Learning-Based CRISPR Array Detection. Master's Thesis, Helmholtz Centre for Infection Research.
 
-## Acknowledgements
+### Acknowledgements
 
-- Ziyu Mu, Master's Thesis, HZI BIFO
-- DFG SPP 2141 (Geschäftszeichen MC 172)
-- BMBF GenomeNet
-- Helmholtz Centre for Infection Research
+- Ziyu Mu - Model development (Master's Thesis, HZI BIFO)
+- DFG SPP 2141 "Much more than Defence" (Project MC 172)
+- BMBF de.NBI / GenomeNet
+- Helmholtz Centre for Infection Research (HZI)
         """)