# Graph Visualization

SPARQLWorks™ transforms SPARQL query results into interactive, dynamic graphs using advanced D3.js visualization techniques. This document explains how to interpret and interact with the graph visualizations.

## 🎨 Graph Structure

### Node Types

#### IRI Nodes (Blue Circles)
- **Entities**: Persons, places, organizations, concepts
- **Classes**: RDF type definitions
- **External Resources**: Linked data entities
- **Size**: Medium (14px radius)

#### Literal Nodes (Gray Circles)
- **String Values**: Text content
- **Numbers**: Integer/float values
- **Dates**: Temporal values
- **Booleans**: True/false values
- **Size**: Small (10px radius)

#### Class Nodes (Green Circles)
- **RDF Types**: Category definitions
- **Ontology Classes**: Schema definitions
- **Size**: Large (18px radius)

#### Role Nodes (Purple Circles)
- **Functional Roles**: Specific functions or positions
- **Size**: Medium-large (16px radius)

### Edge Types

#### Directional Relationships
- **Solid arrows**: Subject → Predicate → Object
- **Arrowheads**: Indicate relationship direction
- **Colors**: Match source node colors

#### Symmetric Relationships
- **Double arrows**: Bidirectional relationships
- **Special predicates**: `owl:sameAs`, `owl:equivalentClass`
- **Visual feedback**: Both ends show arrowheads

## 🎯 Graph Layout

### Force-Directed Algorithm
SPARQLWorks uses D3.js force simulation for natural graph layouts:

- **Charge Force**: Node repulsion (negative = stronger repulsion)
- **Link Force**: Edge length constraints
- **Center Force**: Graph centering
- **Collision Detection**: Prevents node overlap

### Physics Controls

#### Charge Strength (-1000 to 0)
```javascript
// Lower values = stronger repulsion
simulation.force("charge").strength(-600); // Default
simulation.force("charge").strength(-1000); // Strong repulsion
simulation.force("charge").strength(0); // No repulsion
```

#### Link Distance (10-300 pixels)
```javascript
// Controls spacing between connected nodes
simulation.force("link").distance(180); // Default
simulation.force("link").distance(50); // Tight clusters
simulation.force("link").distance(300); // Spread out
```

## 🖱️ Interaction Methods

### Navigation

#### Zoom Controls
- **Mouse Wheel**: Zoom in/out centered on cursor
- **Zoom Range**: 0.1x to 8x magnification
- **Smooth Animation**: Gradual zoom transitions

#### Pan Controls
- **Click + Drag**: Move graph view
- **Momentum**: Physics-based movement continuation
- **Boundaries**: Automatic centering constraints

#### Fit to Viewport
- **"Fit" Button**: Auto-adjust zoom to show all nodes
- **Padding**: 8-pixel margin around graph bounds
- **Animation**: Smooth transition to fitted view

### Node Interactions

#### Hover Effects
- **Node Highlight**: Target node grows (1.5x radius)
- **Connected Highlight**: Related nodes and edges emphasized
- **Tooltip Display**: Show node information
- **Delay**: 0.5 second activation delay

#### Click Actions
- **IRI Nodes**: Open entity URL in new tab
- **URL Construction**: Uses configured entity description service
- **Default**: Direct IRI opening
- **Virtuoso Mode**: Entity description pages

#### Drag Behavior
- **Manual Positioning**: Override physics layout
- **Pin Nodes**: Fix position with `fx`, `fy` properties
- **Double-click**: Release pinned positions

### Edge Interactions

#### Hover Information
- **Predicate Display**: Show full IRI or compact form
- **Relationship Context**: Subject → Object relationship
- **Tooltip**: Detailed edge information

#### Click Navigation
- **Predicate Links**: Open predicate IRI in new tab
- **Documentation**: Access property definitions
- **External Resources**: Ontology documentation

## 🎨 Visual Customization

### Node Coloring
D3.js category10 color scheme:
- **Scheme**: Blue (#1f77b4)
- **Class**: Orange (#ff7f0e)
- **Category**: Green (#2ca02c)
- **Role**: Red (#d62728)
- **External**: Purple (#9467bd)
- **Literal**: Brown (#8c564b)

### Edge Styling
- **Width**: 2.5px solid lines
- **Opacity**: 60% base transparency
- **Arrowheads**: Custom SVG markers
- **Colors**: Match source node colors

### Label Display

#### IRI Labels
- **Compact Form**: CURIEs (e.g., `dbr:Apple_Inc.`)
- **Full URIs**: Complete IRIs when needed
- **Language Support**: Multi-language label preferences

#### Friendly Labels
- **Human Readable**: Use `rdfs:label`, `schema:name`, etc.
- **Priority Order**: Configurable predicate preference
- **Fallback**: IRI fragments when no labels available

### Edge Annotations

#### Icon Mode
- **Predicate Icons**: Visual representations
  - `rdf:type`: Tag icon
  - `owl:sameAs`: Link icon
  - `skos:broader`: Down arrow
  - Generic: URI chain icon

#### Name Mode
- **Full Names**: Complete predicate terms
- **Background**: Semi-transparent rectangles
- **Rotation**: Align with edge direction
- **Size**: Auto-fit to text content

## 🔍 Filtering & Focus

### Hover Focus Feature
- **Activation**: Hover over nodes/edges for 0.5s
- **Highlight**: Connected components emphasized
- **Fade**: Unrelated elements dimmed (15% opacity)
- **Reset**: Mouse leave clears focus

### Type-Based Filtering
- **Include Mode**: Show only selected `rdf:type` values
- **Empty Selection**: Show all types
- **Dynamic Updates**: Graph refreshes on filter changes

### Property Filtering
- **Predicate Selection**: Show only chosen properties
- **IRI Matching**: Full IRI comparison
- **Empty Selection**: Show all properties

### Group Filtering
- **Node Categories**: IRI, Literal, Class, etc.
- **Checkbox Controls**: Enable/disable categories
- **Legend Integration**: Visual category indicators

## 📊 Performance Optimization

### Large Graph Handling
- **Progressive Rendering**: Incremental node/edge addition
- **Force Simulation**: Efficient physics calculations
- **Memory Management**: Automatic cleanup of unused elements

### Rendering Limits
- **Node Capacity**: Thousands of nodes supported
- **Edge Capacity**: Complex relationship networks
- **Viewport Culling**: Only visible elements rendered

### Animation Performance
- **Smooth Transitions**: CSS transitions for UI changes
- **Debounced Updates**: Prevent excessive re-renders
- **Efficient Updates**: D3.js enter/update/exit pattern

## 🎛️ Advanced Controls

### Graph Manipulation
- **Clear Graph**: Remove all nodes and edges
- **Reset View**: Return to default zoom/pan
- **Manual Layout**: Drag nodes to preferred positions

### Export & Sharing
- **URL Encoding**: Complete graph state in URLs
- **Position Persistence**: Node positions saved
- **Configuration Sharing**: Filters and settings included

### Accessibility
- **Keyboard Navigation**: Full keyboard support
- **Screen Reader**: ARIA labels and descriptions
- **High Contrast**: Clear visual distinctions
- **Touch Support**: Mobile-friendly interactions

## 🔧 Technical Implementation

### D3.js Integration
```javascript
const simulation = d3.forceSimulation()
    .force("link", d3.forceLink().id(d => d.id))
    .force("charge", d3.forceManyBody())
    .force("collision", d3.forceCollide().radius(d => getNodeRadius(d) + 12))
    .force("center", d3.forceCenter(width / 2, height / 2))
    .alphaDecay(0.02)
    .velocityDecay(0.3);
```

### Data Processing
- **JSON-LD Parsing**: Native Linked Data format support
- **Node Classification**: Automatic type detection
- **Relationship Extraction**: Triple to graph conversion
- **Label Resolution**: Multi-predicate label prioritization

### Layout Algorithm
- **Initialization**: Random node positioning
- **Iteration**: Physics-based position updates
- **Stabilization**: Alpha decay for convergence
- **Interaction**: Real-time position adjustments

---

[← Query Modes](Query-Modes.md) | [Next: Examples →](Examples.md)