3D Protein Structure Viewers
Relevant source files
The following files were used as context for generating this wiki page:
- public/js/p3/widget/viewer/ProteinStructure.js
- public/js/p3/widget/proteinStructure/ProteinStructure.js
- public/js/p3/widget/viewer/ProteinStructureList.js
- public/js/p3/widget/proteinStructure/ProteinStructureState.js
- public/js/p3/resources/jsmol/display-types.json
- public/js/p3/widget/AdvancedSearch.js
The 3D Protein Structure Viewers provide an interactive interface for visualizing and analyzing protein structures within the dxkb-web platform. These viewers integrate structural data from multiple sources, including the Protein Data Bank (PDB) and AlphaFold predicted models, allowing researchers to explore molecular configurations, highlighted features, and ligand binding sites.
The system is built on a modular architecture that separates state management, UI widget logic, and the core rendering engine, which primarily utilizes the Mol* (MolStar) library. Users can access these viewers through search results, genome overview pages, or by direct accession IDs.
Sources: public/js/p3/widget/viewer/ProteinStructure.js, public/js/p3/widget/proteinStructure/ProteinStructure.js
System Architecture
The viewing system follows a hierarchical structure where a top-level viewer manages the layout and metadata, while a specialized display widget handles the 3D rendering context.
Component Relationship
The architecture consists of three primary layers:
- Tab/List Viewers: Used for browsing collections of structures.
- ProteinStructureViewer: The main container that handles UI panels, metadata display, and highlighter logic.
- ProteinStructure Display Widget: A wrapper for the Mol* engine that executes the actual 3D rendering.
State Management
The ProteinStructureState object acts as the single source of truth for the viewer's current configuration, including the active accession ID, workspace paths, and active highlighters. Changes to this state trigger reactive updates in the Mol* display widget.
Sources: public/js/p3/widget/proteinStructure/ProteinStructure.js:65-80
Data Loading and Integration
The viewer supports loading structures from external databases and user workspaces. It differentiates between experimentally determined structures and predicted models.
Loading Logic Flow
The loading process determines the source based on the accession metadata or workspace parameters.
Supported Data Sources
| Source | Description | Source Type |
|---|---|---|
| RCSB PDB | Experimental structures identified by PDB IDs. | External API |
| AlphaFold | Predicted structures using UniProtKB accessions. | External API |
| Structure Server | Internal dxkb-web server for custom/predicted files. | Internal URL |
| Workspace | User-uploaded .pdb files stored in the system. | Workspace API |
Sources: public/js/p3/widget/proteinStructure/ProteinStructure.js:140-180
Display and Highlighting Features
The viewer provides advanced highlighting capabilities to map sequence-level information onto the 3D structure.
Highlighting Categories
- Ligands: Automatically detected small molecules or ions within the structure.
- Features: Functional domains or motifs identified in the protein sequence.
- Epitopes: Immunological binding sites fetched from external epitope databases.
Sources: public/js/p3/widget/viewer/ProteinStructure.js:70-120
Visualization Modes
The system supports multiple display types defined in configuration files, allowing users to toggle between different molecular representations.
| Mode | Description | Representation |
|---|---|---|
| Cartoon | Default secondary structure visualization. | Ribbon/Cartoon |
| Ball & Stick | Individual atoms and bonds shown as spheres/cylinders. | Ball & Stick |
| Space | Space-filling model showing van der Waals radii. | Spacefill |
| Stick | Bond-focused view without atom spheres. | Sticks |
| Charge View | Color-coded representation based on residue charge. | Color Map |
Sources: public/js/p3/resources/jsmol/display-types.json
Implementation Details
Core Functions
loadAccession(accessions): Asynchronously fetches and loads one or more protein structures into the Mol* instance.handleHighlight(attr, old, new): Updates the 3D overpaint/coloring based on changes to the highlight state (epitopes, features, ligands).colorToMolStarColor(hexColor): Utility to convert standard hex strings (e.g.,#FF0000) into integer formats required by the Mol* engine.updateAccessionInfo(accessionInfo): Refreshes the metadata side panel with details like organism name, resolution, and PMID.
Sources: public/js/p3/widget/proteinStructure/ProteinStructure.js:100-130, public/js/p3/widget/viewer/ProteinStructure.js:160-175
Search Integration
The AdvancedSearch module enables direct navigation to the viewer via protein_structure data types. Links are generated using the pattern /view/ProteinStructure#accession={PDB_ID}.
Sources: public/js/p3/widget/AdvancedSearch.js:130-140, public/js/p3/widget/AdvancedSearch.js:315-325
Conclusion
The 3D Protein Structure Viewers provide a robust bridge between sequence data and structural biology. By integrating Mol* for rendering and implementing a flexible highlighting system, the dxkb-web platform enables detailed structural analysis of both experimental and predicted protein models. The separation of the rendering engine from the dxkb-web state management allows for reliable updates and extensibility as new structural features or data sources are added.