AlphaFold Database Visualization Skill

An agent skill and computational pipeline for retrieving, analyzing, and visualizing AlphaFold predicted protein structures from the AlphaFold Protein Structure Database (AFDB). Designed for execution in agent environments including Gemini Enterprise App, Antigravity, and other agent harnesses, as well as standalone command-line workflows.

The skill analyzes structural confidence (pLDDT scores), detects intrinsically disordered regions (IDRs), extracts rigid domain boundaries and inter-domain flexibility from Predicted Aligned Error (PAE) matrices, and generates an interactive, standalone HTML/Canvas visual dashboard with embedded 3D molecular graphics (WebGL via 3Dmol.js) and 2D PAE heatmaps.

---

Features

• Structure Retrieval: Automates API queries to the AlphaFold Protein Structure Database, downloading mmCIF structures, PDB files, PAE matrices, and metadata with rate-limit handling and fragment detection.
• pLDDT Confidence Assessment: Classifies residues into AlphaFold confidence tiers (Very High >90, Confident 70-90, Low 50-70, Very Low <50), identifies disordered regions, and assesses overall folding state.
• PAE Domain Segmentation: Evaluates the NxN Predicted Aligned Error matrix using diagonal sliding-window heuristics to locate rigid domain boundaries, calculate intra-domain rigidity, and determine inter-domain mobility.
• Interactive Canvas UI Dashboard: Produces a standalone, single-file HTML interface that renders directly inside iframe-based Canvas environments and web browsers without requiring a local web server or build toolchain.
• Synthetic Test Suite: Includes synthetic, non-PHI test datasets and automated unit and integration tests for offline validation.

---

Non-Technical User Guide: How to Use This Skill in Agent Chat

This skill enables non-technical users, biologists, and researchers to explore 3D protein structures and confidence metrics through conversational chat interfaces without writing code, downloading command-line tools, or configuring bioinformatic software.

What You Need to Get Started

To visualize a protein structure, you need a UniProt Accession ID (a 6-to-10 character alphanumeric code, such as P00520 or P04637).

If you only know the protein name or gene symbol (such as "human p53" or "ABL1"), look up the accession ID at UniProt before asking the agent.

Public Benchmark Proteins to Try

UniProt ID	Protein Name	Gene Symbol	Organism	Structural Architecture	Suggested Test Scenario
P00520	Tyrosine-protein kinase ABL1	ABL1	Homo sapiens	Multi-domain (SH3, SH2, Kinase)	Multi-domain structure with flexible linkers
P04637	Cellular tumor antigen p53	TP53	Homo sapiens	Mixed (Folded core, Disordered N/C termini)	Identifying intrinsically disordered regions
P69905	Hemoglobin subunit alpha	HBA1	Homo sapiens	Single compact globular domain	High-confidence monolithic structure
P12931	Proto-oncogene tyrosine kinase Src	SRC	Homo sapiens	Multi-domain signaling kinase	Evaluating inter-domain flexibility
P37840	Alpha-synuclein	SNCA	Homo sapiens	Intrinsically disordered monomer	Triggering explicit disorder warnings
P01308	Insulin	INS	Homo sapiens	Small disulfide-stabilized peptide	Small peptide model verification

---

Step-by-Step Walkthrough

Step 1: Ask the Agent

Enter a natural-language prompt containing the UniProt ID into the chat interface:

Retrieve the AlphaFold structure for UniProt ID P00520 and visualize the confidence metrics and domain breakdown in Canvas.

Step 2: Automated Background Analysis

When the agent receives your prompt, it automatically:

1. Queries the AlphaFold Protein Structure Database API.
2. Downloads the 3D coordinates (.pdb, .cif), the Predicted Aligned Error (.json), and the metadata.
3. Evaluates per-residue confidence scores (pLDDT) and locates disordered regions.
4. Analyzes the PAE matrix to detect rigid domain blocks and flexible linker hinges.
5. Builds an interactive visual dashboard (dashboard.html).

Step 3: Read the Synthesized Chat Summary

The agent outputs a structured textual overview in the chat stream:

Target:           Tyrosine-protein kinase ABL1 (ABL1)
UniProt ID:       P00520 (Entry: AF-P00520-F1)
Organism:         Homo sapiens
Sequence Length:  1130 residues
Global pLDDT:     72.4 [Mixed Architecture]
Architecture:     Multi-Domain Architecture (3 Domains) with Flexible Inter-Domain Linkers

Confidence Breakdown:
- Very High (>90)    : 342 residues (30.3%)
- Confident (70-90)  : 418 residues (37.0%)
- Low (50-70)        : 120 residues (10.6%)
- Very Low (<50/IDR) : 250 residues (22.1%)

Rigid Domain Breakdown:
- [D1] Residues  65 - 120 ( 56 aa) | SH3 Domain
- [D2] Residues 125 - 220 ( 96 aa) | SH2 Domain
- [D3] Residues 240 - 500 (261 aa) | Catalytic Kinase Domain

Downstream Guidance:
Multi-domain structure with flexible linkers. Perform Foldseek searches and binding site docking on individual domains independently, as their relative global orientation is dynamic.

Step 4: Explore the Interactive Canvas Dashboard

The agent displays the generated interactive dashboard in the Canvas pane. Non-technical users can interact with four integrated panels:

1. 3D Molecular Viewer (Top Left):

   • Rotate: Click and drag with the mouse.
   • Zoom: Use the mouse scroll wheel.
   • Color Modes: Switch between pLDDT confidence coloring (dark blue = very high, light blue = confident, yellow = low, orange = disordered), domain colors, secondary structure, or rainbow gradient.
   • Styles: Choose cartoon ribbon, semi-transparent surface, sticks, or spheres.
   • Auto-Spin: Click the Auto-Spin button for continuous rotation.

2. 2D PAE Heatmap (Top Right):

   • Move the mouse across the matrix to inspect alignment error between any two residues in Angstroms.
   • Toggle the "Show Domain Boxes" checkbox to display color-coded bounding boxes around detected rigid domains.

3. Per-Residue pLDDT Plot (Bottom Left):

   • Hover over sequence positions to identify structured beta-sheets/alpha-helices versus flexible disordered loops.

4. Domain Boundaries and Downstream Recommendations Table (Bottom Right):

   • Review exact residue start and end positions, average domain pLDDT, and actionable advice for docking or homology search workflows.

---

Example Prompts for Common Use Cases

Scenario A: Investigating a Multi-Domain Kinase

Retrieve the AlphaFold model for UniProt accession P00520. Show me the domain boundaries, check if the domains are rigidly connected, and open the interactive dashboard.

Scenario B: Assessing Intrinsic Disorder in a Protein

Can you analyze the AlphaFold prediction for UniProt ID P04637? I want to know which parts of the protein are well-folded and which regions are disordered.

Scenario C: Checking Feasibility for Molecular Docking

I want to perform ligand docking on protein P12931. Please retrieve its AlphaFold structure and tell me if there are flexible loops or disordered regions I should avoid in my binding grid.

Scenario D: Verifying a Single Globular Domain

Analyze the structural confidence for UniProt ID P69905 and generate a 3D visualization.

---

Technical CLI Usage (For Developers and Bioinformaticians)

Technical users can execute the Python scripts directly from the terminal or integrate them into automated bioinformatic workflows.

1. Unified End-to-End Pipeline

The primary CLI entry point is scripts/run_pipeline.py. It executes retrieval, statistical calculations, domain heuristics, and dashboard generation in a single command:

python3 scripts/run_pipeline.py P00520 -o ./output/P00520

CLI Arguments:

• uniprot_id: UniProt Accession ID (e.g., P00520, P04637, or synthetic SYNTH01).
• -o, --output-dir: Output directory path for all generated files and dashboard.
• --format: File formats to download (cif, pdb, or both; default: both).
• --mock: Runs against local synthetic test fixtures in sample_data/ without network calls.
• --timeout: Download timeout in seconds (default: 30).
• --json-out: Optional file path to export the complete analysis report in JSON format.

2. Running Individual Modular Scripts

A. Fetch Structure Files and Metadata

Downloads the mmCIF structure, PDB file, PAE JSON matrix, and metadata JSON:

python3 scripts/fetch_structure.py P00520 -o ./output/P00520 --format both

B. Analyze pLDDT Confidence and Disorder

Calculates confidence distributions and detects contiguous intrinsically disordered regions:

python3 scripts/analyze_plddt.py ./output/P00520/AF-P00520-F1-metadata.json --json-out ./output/P00520/plddt_summary.json

C. Analyze PAE Matrix and Domain Boundaries

Evaluates rigid domain boundaries and inter-domain flexibility from the PAE matrix:

python3 scripts/analyze_pae.py ./output/P00520/AF-P00520-F1-predicted_aligned_error.json --json-out ./output/P00520/pae_summary.json

D. Generate Standalone HTML / Canvas Dashboard

Assembles all processed data into the self-contained HTML dashboard:

python3 scripts/generate_dashboard.py   -m ./output/P00520/AF-P00520-F1-metadata.json   -p ./output/P00520/AF-P00520-F1-predicted_aligned_error.json   --pdb ./output/P00520/AF-P00520-F1-model.pdb   -o ./output/P00520/dashboard.html

---

Project Structure and File Tree

alphafold-database-visualize-skill/
├── SKILL.md                                  # Skill specification and agent execution rules
├── README.md                                 # Project documentation and non-technical user guide
├── LICENSE                                   # Apache License, Version 2.0
├── requirements.txt                          # Optional performance dependencies (numpy, requests)
├── assets/
│   └── alphafold_skill_overview.jpg          # Workflow diagram and dashboard interface visual
├── scripts/
│   ├── fetch_structure.py                   # AFDB REST API client and download utility
│   ├── analyze_plddt.py                     # Per-residue pLDDT confidence and IDR analyzer
│   ├── analyze_pae.py                       # PAE matrix parser and rigid domain segmenter
│   ├── generate_dashboard.py                # Standalone HTML/Canvas dashboard generator
│   └── run_pipeline.py                      # Unified pipeline orchestrator
├── sample_data/                              # Synthetic test fixtures (no PHI)
│   ├── AF-SYNTH01-F1-metadata.json          # Multi-domain synthetic protein metadata
│   ├── AF-SYNTH01-F1-model_v4.pdb           # Multi-domain synthetic PDB coordinates
│   ├── AF-SYNTH01-F1-model_v4.cif           # Multi-domain synthetic mmCIF coordinates
│   ├── AF-SYNTH01-F1-predicted_aligned_error_v4.json # Synthetic 2D PAE matrix (180x180)
│   ├── AF-SYNTH02-F1-metadata.json          # Disordered synthetic protein metadata
│   ├── AF-SYNTH02-F1-model_v4.pdb           # Disordered synthetic PDB coordinates
│   ├── AF-SYNTH02-F1-model_v4.cif           # Disordered synthetic mmCIF coordinates
│   └── AF-SYNTH02-F1-predicted_aligned_error_v4.json # Disordered synthetic PAE matrix (120x120)
├── tests/
│   ├── __init__.py                          # Test package initializer
│   ├── test_fetch.py                        # Unit tests for structure retrieval and mock loader
│   ├── test_plddt.py                        # Unit tests for pLDDT statistics and IDR detection
│   ├── test_pae.py                          # Unit tests for PAE domain segmentation heuristics
│   ├── test_dashboard.py                    # Unit tests for HTML dashboard generation
│   └── test_pipeline.py                     # End-to-end integration tests on synthetic data
└── references/
    ├── citation.bib                         # Literature citations (AlphaFold, AFDB, 3Dmol.js)
    └── canvas_integration.md                # Technical guide on Canvas iframe architecture

---

Installation and Requirements

The core scripts require only Python 3.8+ and standard library modules (urllib.request, json, math, argparse, dataclasses, pathlib, unittest). No compilation steps, Node.js dependencies, or uv package managers are required.

To install optional packages for faster matrix computations and HTTP sessions:

pip install -r requirements.txt

---

Testing

Run the automated test suite to verify retrieval logic, statistical calculations, domain heuristics, and dashboard generation:

python3 -m unittest discover -s tests -p "test_*.py" -v

All test cases execute against synthetic, non-PHI datasets located in sample_data/ and do not require external network connectivity.

---

References

• Jumper, J., Evans, R., Pritzel, A., et al. Highly accurate protein structure prediction with AlphaFold. Nature 596, 583-589 (2021).
• Varadi, M., Anyango, S., Deshpande, M., et al. AlphaFold Protein Structure Database: massively expanding the structural coverage of protein-sequence space with high-accuracy models. Nucleic Acids Research 50, D439-D444 (2022).
• Rego, N. & Koes, D. 3Dmol.js: molecular visualization with WebGL. Bioinformatics 31, 1322-1324 (2015).

---

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.