Knowledge Graph Visualization¶

Discover hidden connections in your timeline with network graph visualization.

Overview¶

The Knowledge Graph feature transforms your linear timeline into a network visualization that reveals relationships between events, people, places, and categories. See your life story as an interconnected web of experiences.

What is a Knowledge Graph?¶

A knowledge graph is a network of connected entities that shows:

• Nodes - Events, people, locations, and categories
• Edges - Relationships between nodes (temporal, spatial, categorical)
• Attributes - Metadata like dates, confidence scores, and priorities

Why use graphs?

• 📊 Pattern Recognition - Spot clusters and trends invisible in linear timelines
• 🔗 Relationship Discovery - See how events connect through shared people/places
• 🎯 Importance Analysis - Identify central events with many connections
• 🕸️ Network Effects - Understand how experiences influence each other

Two Modes: JSON-Based vs Neo4j-Enhanced¶

ChronoScope offers two modes for graph visualization, with graceful degradation:

Mode 1: JSON-Based (Always Available) ⭐¶

No database required - works out of the box!

What you get: - ✅ Interactive network visualization with NetworkX + Plotly - ✅ Temporal relationships (event sequences) - ✅ People connections (shared people between events) - ✅ Location connections (events at same place) - ✅ Category clustering (events with same tags) - ✅ Confidence filtering - ✅ Fully offline/private

How it works:

ChronoScope builds graphs directly from your JSON timeline data using NetworkX (a Python graph library) and visualizes with Plotly.

Perfect for: - Quick exploration without setup - Privacy-critical scenarios (local only) - Small to medium timelines (< 500 events) - Immediate visualization needs

Mode 2: Neo4j-Enhanced (Optional)¶

Advanced features with graph database

Additional capabilities: - 🏢 Organization extraction - Auto-detect companies/schools - 🔍 Advanced queries - Cypher query language - 📈 Scalability - Handle 1000s of events efficiently - 🔄 Relationship inference - Discover implicit connections - 💾 Persistent storage - Queryable graph database

When to use: - Large timelines (500+ events) - Advanced analysis needs - Multi-user scenarios - Long-term data exploration

Setup required: - Docker + Neo4j installation - Database credentials configuration - See Neo4j Setup Guide below

Using the Knowledge Graph (JSON Mode)¶

Step 1: Access Graph Tab¶

1. Navigate to 🔗 Knowledge Graph tab
2. ChronoScope automatically builds graph from your events

Step 2: View Network Visualization¶

The graph displays:

Node Types: - 🔵 Events - Your timeline events (sized by priority) - 👤 People - Individuals mentioned in events - 📍 Places - Locations from events - 🏷️ Categories - Event tags/categories

Edge Types: - ➡️ PRECEDES - Temporal sequence (Event A → Event B) - 👥 INVOLVES - Person appeared in event - 📌 LOCATED_AT - Event occurred at location - 🏷️ TAGGED_AS - Event has category/tag

Visual Encoding: - Node Size - Importance (number of connections) - Node Color - Type (event vs person vs place vs category) - Edge Color - Relationship type - Layout - Spring algorithm (closely related nodes cluster together)

Step 3: Interact with the Graph¶

Actions:

• Hover - See node details (event title, date, confidence)
• Zoom - Mouse wheel or pinch gesture
• Pan - Click and drag background
• Select - Click node to highlight connections
• Filter - Use sidebar to hide low-confidence events

Step 4: Analyze Patterns¶

What to look for:

1. Hubs - Large nodes with many connections (pivotal events/people)
2. Clusters - Grouped nodes (related periods or themes)
3. Bridges - Nodes connecting different clusters (transitional events)
4. Isolates - Disconnected nodes (unique experiences)

Graph Interpretation Guide¶

Node Centrality¶

High-centrality nodes (many connections):

• Important people appearing across multiple events
• Recurring locations (workplaces, schools)
• Central life events (graduation, job changes)
• Key categories spanning years

Example:

Node: "Stanford University" (Location)
Connections: 15 events
Interpretation: Major life hub - education, research, networking

Temporal Paths¶

PRECEDES edges show event sequences:

Event A → Event B → Event C

Insights: - Career progression (job A → job B → job C) - Skill development sequences - Life phase transitions

Community Detection¶

Clusters reveal thematic groups:

• Career cluster - Work events grouped together
• Education cluster - Academic events
• Personal cluster - Life milestones
• Location cluster - Events at same place

Visual cue: Nodes physically close in the graph

Relationship Triangles¶

Three connected nodes:

Event A ← Person → Event B
    ↓                ↓
    └── Same Location ──┘

Interpretation: Person appeared at same location in multiple events (e.g., colleague at multiple jobs)

Configuration Options¶

Temporal Relationships¶

Toggle: Include PRECEDES edges

• ✅ On - Show event sequences (default)
• ❌ Off - Focus only on shared people/places

When to disable: - Timeline is very long (reduces clutter) - Only interested in thematic connections

Confidence Filtering¶

Slider: Minimum confidence threshold (0.0 - 1.0)

• 0.0 - Include all events (even uncertain)
• 0.5 - Moderate confidence (recommended)
• 0.8 - High confidence only

Effect: Low-confidence events excluded from graph

Use case: Clean up graph by removing uncertain data

Graph Statistics¶

ChronoScope displays graph metrics:

Example interpretation:

Nodes: 150
Edges: 300
Density: 0.027
Avg Degree: 4.0
Components: 1

Analysis:
- Moderately sized graph
- Each event averages 4 connections
- Low density (sparse graph - focused connections)
- Single component (all events connected)

Neo4j Setup (Optional Enhancement)¶

Prerequisites¶

1. Docker installed (Get Docker)
2. ChronoScope running locally

Installation Steps¶

Step 1: Start Neo4j Container¶

docker run \
    --name chronoscope-neo4j \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/chronoscope123 \
    -v $PWD/neo4j-data:/data \
    neo4j:latest

Explanation: - 7474 - Web interface port - 7687 - Database connection port - NEO4J_AUTH - Username/password (change in production!) - -v - Persist data across restarts

Step 2: Configure ChronoScope¶

Add to .streamlit/secrets.toml:

[neo4j]
uri = "bolt://localhost:7687"
username = "neo4j"
password = "chronoscope123"

Step 3: Test Connection¶

1. Open ChronoScope
2. Go to 🔗 Knowledge Graph tab
3. Scroll to "Advanced: Enhance with Neo4j"
4. Click "Test Connection"
5. Should see: ✅ Connected to Neo4j!

Step 4: Sync Data¶

1. Click "🔄 Sync to Neo4j"
2. Wait for sync to complete
3. View database stats

Success indicators: - Node count matches event count - Edge count shows relationships - No error messages

Neo4j-Enhanced Features¶

Organization Extraction¶

Automatic entity recognition:

ChronoScope identifies organizations from event descriptions:

• Companies (Google, Microsoft, etc.)
• Universities (Stanford, MIT, etc.)
• Nonprofits, institutions, agencies

New relationships:

Event → AFFILIATED_WITH → Organization
Person → WORKS_FOR → Organization
Organization → LOCATED_IN → Place

Advanced Queries¶

Use Neo4j Browser (localhost:7474) for custom queries:

Find all events with a specific person:¶

MATCH (e:Event)-[:INVOLVES]->(p:Person {name: "John Doe"})
RETURN e.title, e.start_date
ORDER BY e.start_date

Find career progression:¶

MATCH path = (e1:Event)-[:PRECEDES*]->(e2:Event)
WHERE e1.category = 'work' AND e2.category = 'work'
RETURN path
ORDER BY length(path) DESC
LIMIT 5

Find most connected people:¶

MATCH (p:Person)-[:INVOLVES]-(e:Event)
RETURN p.name, count(e) as event_count
ORDER BY event_count DESC
LIMIT 10

Relationship Inference¶

Neo4j can infer implicit connections:

Example:

Event A → INVOLVES → Person X → WORKS_FOR → Company Y
Event B → INVOLVES → Person X → WORKS_FOR → Company Y

Inference: Event A and Event B related through Company Y

Use Cases¶

Career Network Analysis¶

Goal: Understand professional trajectory

Approach: 1. Filter to work-related events 2. Highlight people nodes (connections) 3. Identify hubs (key mentors/colleagues) 4. Trace PRECEDES paths (career progression)

Insights: - Who influenced career most? - Which roles were pivotal? - How did network grow over time?

Location-Based Storytelling¶

Goal: Visualize geographic journey

Approach: 1. Focus on location nodes 2. See events clustered by place 3. Identify location transitions

Insights: - Where did most significant events occur? - How did location changes impact career? - Which places had most connections?

Skill Development Tracking¶

Goal: Trace how skills evolved

Approach: 1. Tag events with skills (Python, Leadership, etc.) 2. Visualize skill categories as nodes 3. Follow temporal paths through skills

Insights: - When did you acquire each skill? - Which skills led to which opportunities? - How did skillset diversify over time?

Collaborative Timeline¶

Goal: Shared experiences with others

Approach: 1. Focus on person nodes 2. Find triangles (events with same people) 3. Identify key collaborators

Insights: - Who appeared most in your timeline? - Which events involved which people? - How did relationships evolve?

Best Practices¶

Graph Design¶

✅ DO:

• Keep timelines focused (< 500 events for JSON mode)
• Use consistent category names
• Add people names to event descriptions
• Include locations for geographic context
• Set appropriate confidence scores

❌ DON'T:

• Create overly dense graphs (hard to interpret)
• Use inconsistent naming (splits nodes)
• Skip metadata (reduces connections)
• Filter too aggressively (loses context)

Visual Clarity¶

For complex graphs:

• Increase minimum confidence (filter noise)
• Disable temporal edges temporarily
• Focus on one node type at a time
• Export static image for sharing

For simple graphs:

• Include all relationships
• Show all node types
• Use lower confidence threshold

Troubleshooting¶

Graph is Too Cluttered¶

No Connections Showing¶

Neo4j Connection Failed¶

Sync Takes Too Long¶

Performance Tips¶

JSON Mode Optimization¶

For timelines > 200 events:

• Filter by date range first
• Disable temporal edges (reduces edge count)
• Increase confidence threshold
• Use category filtering

Neo4j Mode Optimization¶

For timelines > 500 events:

• Create database indexes:

  CREATE INDEX ON :Event(start_date)
  CREATE INDEX ON :Person(name)
  CREATE INDEX ON :Place(location)
  

• Use pagination in queries

• Limit result sets (LIMIT 100)
• Monitor database memory usage

Export Options¶

Static Image Export¶

Save graph as PNG:

1. Hover over graph visualization
2. Click camera icon (Plotly toolbar)
3. Choose "Download plot as png"
4. Save to desired location

Use for: - Presentations - Reports - Documentation - Sharing (non-interactive)

Data Export¶

Export graph structure:

• JSON mode: Already in timeline_events.json
• Neo4j mode: Use Neo4j export tools

Export queries:

// Export all nodes and edges as CSV
CALL apoc.export.csv.all("graph_export.csv", {})

Comparison: Timeline vs Knowledge Graph¶

Recommendation: Use both views for complete understanding!

Next Steps¶

After exploring the knowledge graph:

• 📊 Return to Timeline View
• 📤 Export to TimelineJS
• 📝 Add More Events
• ✅ Validate Data Quality

Quick Reference¶

Back to Documentation Home