Controls and Settings

Controls and Settings

SPARQLWorks™ provides extensive customization options through its controls panel. This document explains all available settings and how to use them effectively.

🎛️ Accessing Controls

Controls Panel

1. Open Panel: Click the gear icon (⚙️) in the top-right corner
2. Panel Features:
   • Floating design with backdrop blur
   • Sticky header for easy access
   • Scrollable content area
   • Draggable positioning

Panel Controls

• Toggle Visibility: Click gear icon to show/hide
• Drag to Move: Grab header to reposition panel
• Auto-positioning: Panel stays within viewport bounds

⚡ Physics Controls

Charge Strength

Range: -1000 to 0 (default: -600) Purpose: Controls node repulsion force

• Higher values (less negative): Nodes cluster closer together
• Lower values (more negative): Nodes spread further apart
• Effect: Influences overall graph layout compactness

Link Distance

Range: 10 to 300 pixels (default: 180) Purpose: Controls spacing between connected nodes

• Smaller values: Tighter, more compact relationships
• Larger values: Spread out, easier to read individual connections
• Effect: Affects graph readability and density

Usage Guidelines

• Large graphs: Increase charge strength (less negative) for better clustering
• Dense relationships: Increase link distance for clarity
• Performance: Extreme values may impact rendering performance

🎨 Display Options

Hover Focus

Default: Enabled with 0.5s delay Purpose: Highlights connected nodes when hovering

• Enabled: Mouse hover emphasizes related nodes and edges
• Disabled: No hover effects, all elements remain visible
• Delay: Prevents accidental triggering during navigation

Friendly Labels

Default: Enabled Purpose: Shows human-readable labels instead of URIs

• Enabled: Displays rdfs:label, schema:name, etc.
• Disabled: Shows compact CURIEs (e.g., dbr:Apple_Inc.)
• Configuration: Click gear icon next to toggle for priority settings

IRI Labels

Default: Enabled Purpose: Shows compact IRI representations

• Enabled: Displays CURIEs like dbr:Apple_Inc.
• Disabled: Shows full URIs
• Compact Form: Reduces visual clutter in large graphs

Preferred Language

Input: Language code (default: 'en') Purpose: Prioritizes labels in specific language

• Examples: 'en', 'fr', 'de', 'es', 'zh'
• Fallback: Uses any available label if preferred language missing
• Multi-language: Supports datasets with multiple language labels

🔗 URL Format Settings

Default Mode

Behavior: Opens IRIs directly in browser

• Simple linking: Direct navigation to IRI targets
• No transformation: URLs used as-is
• Universal compatibility: Works with any IRI

Virtuoso Mode

Behavior: Opens entity description pages

• Entity descriptions: Uses /describe/?uri= pattern
• Endpoint-specific: Constructs URLs relative to SPARQL endpoint
• Rich information: Shows detailed entity information

Describe Base Configuration

Input: Custom describe base URL Purpose: Defines entity description service URL

• Auto-detection: Derived from SPARQL endpoint by default
• Custom URLs: Override for specific services
• Format: https://example.com/describe/?uri=
• Encoding: IRIs automatically URL-encoded

🔍 Filtering Controls

RDF Type Filtering

Mode: Select-to-include (accordion) Purpose: Shows only nodes with selected types

• Empty selection: Shows all rdf:type values
• Type selection: Displays only matching entities
• Dynamic updates: Graph refreshes immediately
• Select all: Bulk selection/deselection

Property Filtering

Mode: Select-to-include (accordion) Purpose: Shows only relationships using selected predicates

• Empty selection: Shows all properties
• Predicate selection: Filters by full IRI
• Relationship focus: Highlights specific connection types
• Select all: Bulk selection/deselection

Node Group Filtering

Type: Checkboxes for each category Categories:

• IRI: External entities and resources
• Literal: String, number, date values
• Class: RDF type definitions
• Category: Classification terms
• Role: Functional roles
• Scheme: Organization schemes
• External: Linked external resources

Hide rdf:type Relationships

Default: Disabled Purpose: Removes type classification edges

• Enabled: Hides rdf:type arrows for cleaner graphs
• Disabled: Shows all type relationships
• Visualization: Focuses on domain relationships

🏷️ Label Priority Settings

Label Predicate Priority

Default Order:

1. skos:prefLabel
2. rdfs:label
3. schema:name
4. schema:title
5. foaf:name

Customizing Priority

1. Click gear icon next to "Use IRI Labels"
2. Modal opens showing current priority and usage counts
3. Drag to reorder predicates by importance
4. Save changes to apply new priority
5. Reset to restore defaults

Priority Logic

• First match wins: Uses first available label in priority order
• Language preference: Within each predicate, prefers selected language
• Fallback chain: Continues through priority list
• Final fallback: IRI fragment if no labels found

⚙️ Advanced Settings

Edge Annotations

Options: Icons or Names Purpose: Controls how relationships are displayed

• Icons: Visual predicate representations
• Names: Full predicate terms with backgrounds
• Performance: Icons render faster than text labels

Label Priority Modal

Access: Gear icon in main controls or query panel Features:

• Usage statistics: Shows label counts per predicate
• Sample labels: Examples from current data
• Drag reordering: Intuitive priority adjustment
• Live preview: Immediate effect on current graph

💾 Persistence

Local Storage

All settings automatically saved:

• Physics parameters: Charge strength, link distance
• Display preferences: Labels, language, IRI format
• Filter selections: Types, properties, groups
• Authentication: OAuth settings, tokens
• Label priority: Custom ordering

URL Encoding

Settings encoded in shareable URLs:

• Complete state: All active settings and filters
• Bookmarkable: Save and restore exact configurations
• Shareable: Send specific views to colleagues

Session Management

• Per-browser: Settings isolated by browser instance
• Cross-tab: Changes sync across open tabs
• Privacy: No data transmitted to external servers

🎯 Usage Scenarios

Large Graph Optimization

Charge Strength: -800 (more spread out)
Link Distance: 250 (extra spacing)
Hover Focus: Enabled (navigation aid)
Friendly Labels: Enabled (readability)

Dense Relationship Focus

Charge Strength: -400 (clustered)
Link Distance: 120 (compact)
Hide rdf:type: Enabled (reduce clutter)
Property Filter: Selected predicates only

Exploration Mode

Hover Focus: Enabled
Friendly Labels: Enabled
Preferred Language: User's language
Type Filter: Empty (show all)
Group Filters: All enabled

Presentation Mode

Physics: Balanced settings
Labels: Friendly with priority
Filters: Focused on key relationships
URL Format: Entity descriptions
Edge Annotations: Names (clearer for audience)

🔧 Troubleshooting

Controls Not Responding

• Panel hidden: Click gear icon to show controls
• Page reload: Refresh page to reset stuck controls
• Browser cache: Clear cache if settings don't persist

Graph Not Updating

• Apply filters: Click outside controls to apply changes
• Re-run query: Some settings require fresh query execution
• Check conflicts: Conflicting filter combinations may hide all data

Performance Issues

• Reduce nodes: Use LIMIT in queries
• Simplify filters: Fewer active filters improve performance
• Adjust physics: Less extreme values improve rendering speed

Settings Not Saving

• Local storage: Ensure browser allows local storage
• Incognito mode: Private browsing may not persist settings
• Browser restrictions: Check for storage blocking extensions

📊 Performance Tuning

Optimal Settings by Graph Size

Small Graphs (< 50 nodes)

Charge Strength: -500
Link Distance: 150
Hover Focus: Optional
Filters: Minimal

Medium Graphs (50-200 nodes)

Charge Strength: -650
Link Distance: 180
Hover Focus: Enabled
Filters: Moderate

Large Graphs (200+ nodes)

Charge Strength: -800
Link Distance: 220
Hover Focus: Enabled
Filters: Focused
Edge Annotations: Icons (faster)

Memory Considerations

• Large graphs: May impact browser memory
• Many filters: Complex filtering increases processing
• Label resolution: Extensive label lookup for large datasets
• Animation: Smooth transitions consume resources

🔄 Resetting Settings

Individual Resets

• Label priority: Use "Reset" button in priority modal
• Filters: Uncheck all selections
• Physics: Double-click sliders to reset to defaults

Complete Reset

// In browser console
localStorage.clear();
location.reload();

Selective Reset

// Clear specific settings
localStorage.removeItem('labelPriority');
localStorage.removeItem('chargeStrength');
// etc.

---

← Authentication | Next: URL Parameters →