11 KiB
Temporal & Scenario Analysis - Quick Reference Card
At a Glance
What is this? A tool for temporal evolution analysis and scenario exploration of constellation graphs.
What it's NOT: Version control (Git), undo/redo, or collaborative editing.
Key Idea: Capture snapshots of your graph at different times or scenarios, then compare and analyze them.
Core Concepts (5-Second Summary)
| Concept | What It Is | Example |
|---|---|---|
| State | Snapshot of graph at specific moment | "Q1 2023", "Session 5", "Strategy A" |
| Timeline | Ordered sequence of states | Jan → Feb → Mar → Apr |
| Scenario | Alternative branch from a point | Current → Strategy A vs Strategy B |
| Comparison | Visual diff between two states | What changed from Q1 to Q4? |
| Journey | Track one actor across states | How did Alice's role evolve? |
Common Use Cases
1. Historical Tracking
Track how your network changed over time
- Example: Company org chart 2020-2024
- Action: Capture state at each quarter/year
2. Therapeutic Progress
Show relationship evolution across sessions
- Example: Family therapy sessions 1-10
- Action: Capture state after each session
3. Strategic Planning
Explore different future scenarios
- Example: 3 different growth strategies
- Action: Branch scenarios from current state
4. Project Evolution
Show stakeholder changes through project phases
- Example: Kickoff → Planning → Execution → Closure
- Action: Capture state at each phase
Quick Actions
Capture a State
- Work on your graph
- Click "Capture State" button (toolbar)
- Label it (e.g., "Q1 2023")
- Add notes (optional)
- Done!
Load a State
- Click state selector dropdown (toolbar)
- Choose state from list
- Graph updates to that state
Compare Two States
- Select state A
- Click "Compare" button
- Select state B
- View differences (side-by-side or overlay)
Create Timeline
- Capture several states
- Open timeline panel (bottom)
- States auto-appear in order
- Use scrubber to navigate
Create Scenario Branch
- Load the branching point state
- Menu → States → Create Scenario Branch
- Name it and add description
- Modify graph for this scenario
- Capture states along the scenario
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
Ctrl+Shift+S |
Capture current state |
Ctrl+Shift+T |
Toggle timeline panel |
Ctrl+Shift+C |
Open comparison view |
← / → |
Navigate timeline (when focused) |
Space |
Play/pause animation (when focused) |
Ctrl+J |
View actor journeys |
Ctrl+Shift+P |
Presentation mode |
Esc |
Exit modal/presentation |
UI Components
Toolbar (Top)
Current State: Q3 2023 ▼ [📸 Capture] [🔍 Compare]
- State Selector: Dropdown to switch states
- Capture Button: Create new state
- Compare Button: Compare two states
Timeline Panel (Bottom)
●═══●═══●═══●═══●
Q1 Q2 Q3 Q4 Now
- Markers: Click to load state
- Scrubber: Drag to animate through timeline
- Controls: Navigate, play, compare
Right Panel
When state is selected, shows:
- State metadata (date, label, notes)
- Quick stats (actors, relations)
- Navigation (previous/next)
- Actions (edit, compare, delete)
Comparison Modes
Side-by-Side
Two graphs shown next to each other
- Best for: Overall comparison
- Pros: Clear separation
- Cons: Takes more screen space
Overlay
Changes highlighted on single graph
- Best for: Detailed change analysis
- Pros: Shows changes in context
- Cons: Can be cluttered with many changes
Diff List
Text list of all changes
- Best for: Systematic review
- Pros: Comprehensive, exportable
- Cons: Less visual
Change Indicators
Visual Coding
- 🟢 Green: Added (new actors/relations)
- 🔴 Red: Removed (deleted actors/relations)
- 🟡 Yellow: Modified (changed properties)
- ⚪ Gray: Unchanged
Change Types
- Actor Added: New person/entity joined
- Actor Removed: Person/entity left
- Actor Modified: Role, name, or properties changed
- Relation Added: New connection formed
- Relation Removed: Connection broken
- Relation Modified: Relationship type or strength changed
Best Practices
Naming States
✅ Good: "Q3 2023: Post-Merger Integration" ❌ Bad: "State 3"
✅ Good: "Session 5: Breakthrough Session" ❌ Bad: "May 15"
✅ Good: "Strategy A: Aggressive Growth (Optimistic)" ❌ Bad: "Option 1"
When to Capture States
✅ Capture at significant milestones ✅ Capture at regular intervals (quarterly, sessions) ✅ Capture before major changes
❌ Don't capture for every tiny edit ❌ Don't create states "just in case" ❌ Don't capture without context/labels
Organizing States
✅ Use timelines for temporal sequences ✅ Use scenarios for alternatives ✅ Add descriptions explaining what changed ✅ Tag states for easy finding
❌ Don't mix temporal and scenario in same timeline ❌ Don't create orphaned states without context ❌ Don't forget to clean up old/unused states
Common Workflows
Workflow: Temporal Analysis
1. Start with current graph
2. Capture state: "Jan 2024"
3. Make changes to graph
4. Capture state: "Feb 2024"
5. Repeat monthly
6. View timeline
7. Compare Jan vs Dec
8. Animate evolution
Workflow: Scenario Exploration
1. Create current state: "Current Reality"
2. Branch scenario: "Strategy A"
3. Modify graph for Strategy A
4. Capture: "Strategy A - Year 1"
5. Return to "Current Reality"
6. Branch scenario: "Strategy B"
7. Develop Strategy B
8. Compare Strategy A vs B
Workflow: Actor Journey
1. Ensure multiple states captured
2. Select actor on graph
3. Click "View Journey" (right panel)
4. See actor's timeline
5. Review changes over time
6. Export journey report
Data Model Summary
State
{
stateId: "unique-id",
stateType: "temporal" | "scenario",
snapshot: { nodes, edges },
temporal: { label, timestamp },
// OR
scenario: { label, description, assumptions },
notes: "What changed and why"
}
Timeline
{
timelineId: "unique-id",
label: "Project Evolution",
states: ["state1", "state2", "state3"]
}
Scenario Branch
{
branchId: "unique-id",
label: "Strategy A",
states: ["stateA1", "stateA2"],
color: "#3b82f6"
}
Comparison Output
Summary Statistics
- Total actors: Before → After (Δ)
- Total relations: Before → After (Δ)
- Network density change
- Centrality changes
Detailed Changes
- Actors added: [list]
- Actors removed: [list]
- Actors modified: [list with changes]
- Relations added: [list]
- Relations removed: [list]
- Relations modified: [list with changes]
Export Formats
- PDF report with graphs
- JSON data for analysis
- CSV for spreadsheet
- HTML interactive report
Performance Tips
For Large Graphs (100+ actors)
- Capture states selectively
- Use state pagination
- Enable caching
- Reduce animation quality if needed
For Many States (50+ states)
- Organize into multiple timelines
- Use semantic search (ChromaDB)
- Archive old states
- Export/backup regularly
For Smooth Animation
- Limit number of frames
- Use simplified rendering
- Adjust animation speed
- Close other applications
Troubleshooting
Problem: State won't load
Solution: Check if state data is corrupted, try restarting app
Problem: Comparison is slow
Solution: Large graph - reduce comparison mode quality or use diff list
Problem: Animation is choppy
Solution: Reduce animation speed or quality setting
Problem: Can't find a state
Solution: Use search function or check timeline filters
Problem: Timeline is cluttered
Solution: Create multiple timelines, archive old states
Implementation Status
| Phase | Feature | Status | Priority |
|---|---|---|---|
| 1 | Core State Management | 🔲 Not Started | HIGH |
| 2 | Temporal Analysis | 🔲 Not Started | HIGH |
| 3 | Comparison & Diff | 🔲 Not Started | HIGH |
| 4 | Scenario Branching | 🔲 Not Started | MEDIUM |
| 5 | Actor Journeys | 🔲 Not Started | MEDIUM |
| 6 | Animation & Presentation | 🔲 Not Started | MEDIUM |
| 7 | ChromaDB Integration | 🔲 Not Started | MEDIUM |
| 8 | Advanced Features | 🔲 Not Started | LOW |
Resources
Documentation
- Summary:
TEMPORAL_ANALYSIS_SUMMARY.md - Full Plan:
TEMPORAL_SCENARIO_IMPLEMENTATION_PLAN.md - User Guide:
TEMPORAL_QUICK_START.md - Examples:
VISUAL_EXAMPLES.md - Checklist:
IMPLEMENTATION_CHECKLIST.md - This Card:
QUICK_REFERENCE.md
Key Files (To Be Created)
- Types:
/src/types/temporal.ts - Store:
/src/stores/stateStore.ts - Components:
/src/components/TemporalAnalysis/
FAQs
Q: Will this replace normal editing? A: No, it's optional. You can ignore states and use app normally.
Q: Can I undo after capturing a state? A: Yes, undo/redo is separate. States don't affect edit history.
Q: How many states can I create? A: No hard limit, but recommend <100 per document for performance.
Q: Can I delete a state? A: Yes, but be careful - this can't be undone.
Q: Can I rename states? A: Yes, edit state metadata anytime.
Q: Can states be shared? A: Yes, they're included in document export/import.
Q: What's the difference between temporal and scenario? A: Temporal = time progression. Scenario = alternative branches.
Q: Can I merge scenarios? A: No, scenarios are independent explorations for comparison.
Quick Tips
💡 Tip 1: Label states descriptively - your future self will thank you
💡 Tip 2: Use comparison view liberally - it's the most powerful feature
💡 Tip 3: Animate timelines for presentations - it's impressive!
💡 Tip 4: Track key actors across states to tell their story
💡 Tip 5: Capture states BEFORE making major changes (safety net)
💡 Tip 6: Use scenarios to explore "what if" without commitment
💡 Tip 7: Export comparison reports for documentation
💡 Tip 8: Clean up old/unused states periodically
Remember
This is about storytelling and analysis, not version control!
Think: "How did this network evolve?" not "What edits did I make?"
Use states to:
- ✅ Show temporal evolution
- ✅ Explore scenarios
- ✅ Compare alternatives
- ✅ Track actor journeys
- ✅ Present findings
Not to:
- ❌ Undo/redo edits
- ❌ Track every change
- ❌ Collaborate on editing
- ❌ Version control your work
Happy analyzing! 🎉