Skip to content

CLAUDE.md

Latest commit

 

History

History
113 lines (91 loc) · 5.24 KB

CLAUDE.md

File metadata and controls

113 lines (91 loc) · 5.24 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a modular bioinformatics visualization tool that displays genetic variants on a 3D protein structure of HNF1B (PDB ID: 2H8R). The application uses the NGL.js library to render 3D molecular visualizations in the browser and is organized into separate HTML, CSS, and JavaScript files for improved maintainability.

Architecture

Modular Structure: The application is organized into separate HTML, CSS, and JavaScript files for maintainability.

File Structure:

├── index.html              # Main HTML entry point
├── CLAUDE.md              # Project documentation for Claude
├── README.md              # Project README
├── css/                   # Stylesheets
│   ├── main.css           # Global styles and layout
│   ├── viewer.css         # 3D viewer container styles
│   ├── variants.css       # Variant list and UI styles
│   ├── distances.css      # Distance visualization styles
│   └── representations.css # Protein representation styles
├── js/                    # JavaScript modules
│   ├── variants.js         # Variant data configuration
│   ├── protein-viewer.js   # NGL viewer management class
│   ├── variant-manager.js  # Variant UI logic class
│   ├── distance-calculator.js # Distance calculation logic
│   ├── representation-manager.js # Representation control
│   ├── ngl-config.js      # NGL.js configuration
│   └── main.js            # Application initialization
├── scripts/               # Python analysis scripts
│   ├── extract-snv-variants.py    # Extract variants from CSV
│   └── analyze-variant-distances.py # Statistical analysis
├── data/                  # Input data files
│   ├── HNF1B_DataCuration - Individuals.csv
│   └── variant-distances.json
└── output/                # Generated analysis outputs
    ├── variant-distance-analysis.png
    └── variant-distance-processed.csv

Core Components:

  • protein-viewer.js: ES6 class managing NGL.js Stage, protein loading, highlighting, and state management. Handles PDB loading from RCSB servers, residue existence checking, and 3D representation control.
  • variant-manager.js: ES6 class handling variant list UI, sorting by pathogenicity, and DOM event management. Manages variant-to-viewer communication and dynamic list population.
  • distance-calculator.js: Calculates distances between protein residues and DNA helix.
  • representation-manager.js: Manages different protein display representations.
  • Data Layer: Variant objects exported from variants.js module with standardized schema (name, residue, type, color)
  • Application Coordinator: main.js orchestrates initialization sequence: viewer setup → protein loading → residue validation → UI population → event binding

Key Technical Patterns:

  • ES6 modules with import/export syntax for clean dependency management
  • Class-based architecture with clear separation of concerns
  • Uses NGL.js Stage and Component objects for 3D rendering with stateful highlight management
  • Implements residue existence checking to handle incomplete PDB structures (2H8R fragment contains residues 170-280)
  • Dynamic DOM manipulation with automatic pathogenicity-based sorting
  • Event-driven interaction model with delegation for scalable variant list handling
  • Async/await pattern for protein loading with proper error handling

Development Commands

Local Development:

# Serve the HTML file locally for testing
python3 -m http.server 8000
# Then navigate to http://localhost:8000/index.html

No Build Process: This is a static HTML file with no compilation or build steps required.

Python Scripts:

# Extract variants from CSV and update js/variants.js
cd scripts
python extract-snv-variants.py

# Run statistical analysis on variant distances
python analyze-variant-distances.py
# Outputs: ../output/variant-distance-analysis.png and variant-distance-processed.csv

Data Management

Adding Variants: Modify the variants array in js/variants.js:

export const variants = [
    { name: 'p.VariantName', residue: 123, type: 'Pathogenic', color: 'red' }
    // Add new entries here
];

Pathogenicity Classifications: Use standard clinical significance terms:

  • 'Pathogenic' (red)
  • 'Likely Pathogenic' (orange)
  • 'Likely Benign' (#f5d547)
  • 'Uncertain Significance' (grey)

Naming Conventions

File Naming: All files use kebab-case (lowercase with hyphens) for consistency:

  • JavaScript files: protein-viewer.js, variant-manager.js
  • CSS files: main.css, viewer.css, variants.css
  • HTML files: index.html

Technical Considerations

PDB Structure Limitations: The 2H8R structure is a fragment (residues 170-280). The application automatically disables variants outside this range and provides user feedback via tooltips.

External Dependencies:

  • NGL.js v2.0.0-dev.34 loaded from unpkg CDN
  • PDB files fetched directly from RCSB servers

Browser Compatibility: Modern browsers required for ES6+ features and WebGL support for 3D rendering.