# Dagre Ranker Visual Comparison Guide **Purpose**: Explain why "Hierarchical (Topโ†’Bottom)" and "Adaptive (Tight Tree)" layouts look similar --- ## ๐Ÿ” The Core Difference **Both layouts use**: - โœ… Same direction: Topโ†’Bottom (TB) - โœ… Same layout engine: Dagre - โœ… Same spacing rules: nodesep, ranksep **Only difference**: - โŒ Ranking algorithm: `network-simplex` vs `tight-tree` --- ## ๐Ÿ“Š Visual Comparison: Simple vs Complex Diagrams ### Simple Tree Structure (Like NetworkOrganisation) ``` Root / \ Child1 Child2 | | Leaf1 Leaf2 ``` #### With network-simplex (Hierarchical): ``` Root (Rank 0) / \ Child1 Child2 (Rank 1) | | Leaf1 Leaf2 (Rank 2) ``` #### With tight-tree (Adaptive): ``` Root (Rank 0) / \ Child1 Child2 (Rank 1) | | Leaf1 Leaf2 (Rank 2) ``` **Result**: IDENTICAL (both assign same ranks to nodes) --- ### Complex Graph with Multiple Paths ``` Root / \ A B |\ /| | \ / | C \/ D /\ E F ``` #### With network-simplex (Hierarchical): ``` Root (Rank 0) / \ A B (Rank 1) | | C D (Rank 2) โ† Balanced ranks | | E F (Rank 3) ``` #### With tight-tree (Adaptive): ``` Root (Rank 0) / \ A B (Rank 1) / \ / \ C E D F (Rank 2) โ† Compressed into fewer ranks! ``` **Result**: DIFFERENT (tight-tree compresses height) --- ## ๐Ÿงฎ Algorithm Behavior ### network-simplex (Hierarchical) **Goal**: Minimize total edge length **Method**: Linear programming solver **Behavior**: - Distributes nodes evenly across ranks - Balances vertical and horizontal space - Prioritizes aesthetic appeal - May create more ranks (taller graphs) **Best for**: - General-purpose diagrams - Balanced visual appearance - Mixed relationship types - Standard UML class diagrams ### tight-tree (Adaptive) **Goal**: Minimize graph height **Method**: Spanning tree algorithm **Behavior**: - Compresses nodes into fewer ranks - Minimizes vertical space - Accepts more horizontal spreading - Fewer ranks (shorter graphs) **Best for**: - Deep hierarchies (many levels) - Space-constrained displays - Emphasizing breadth over depth - Dense interconnected graphs ### longest-path (Adaptive) **Goal**: Emphasize dependency chains **Method**: Longest path from roots **Behavior**: - Maximizes graph height - Shows clear dependency levels - Creates more ranks - Emphasizes sequential relationships **Best for**: - Workflow diagrams - Build dependency graphs - Process flows - Showing critical paths --- ## ๐Ÿ“ Spacing Calculations From UMLVisualization.tsx (Lines 286-298): ```typescript const isVertical = dagreDirection === 'TB' || dagreDirection === 'BT'; const nodesep = isVertical ? 80 : 100; // Horizontal spacing const ranksep = isVertical ? 120 : 150; // Vertical spacing between ranks g.setGraph({ rankdir: dagreDirection, // TB, BT, LR, RL nodesep: nodesep, // Space between nodes on same rank ranksep: ranksep, // Space between ranks ranker: dagreRanker, // โ† ONLY DIFFERENCE! marginx: 50, marginy: 50 }); ``` **Same spacing for all rankers!** **Difference**: How many ranks are created (height) --- ## ๐ŸŽจ When You'll See Differences ### Diagram Complexity Threshold | Diagram Size | Nodes | Links | Ranker Differences? | |--------------|-------|-------|---------------------| | **Tiny** | <10 | <15 | โŒ No (identical) | | **Small** | 10-20 | 15-30 | โš ๏ธ Subtle | | **Medium** | 20-50 | 30-80 | โœ… Noticeable | | **Large** | 50-100 | 80-150 | โœ… Significant | | **Huge** | 100+ | 150+ | โœ… Very different | ### Graph Structure Matters **Simple Trees** (No differences): - Single root - No cross-hierarchy edges - Clear parent-child relationships - Example: Simple class inheritance **Complex Graphs** (Clear differences): - Multiple roots - Cross-hierarchy relationships - Dense interconnections - Cycles (if present) - Example: Full ontology schema --- ## ๐Ÿงช Test Cases to See Differences ### Test 1: Simple Tree (NO difference expected) **File**: `NetworkOrganisation_20251123_225712.mmd` **Structure**: Linear hierarchy ``` UmbrellaOrganisation | NetworkOrganisation | Consortium ``` **Result**: All rankers produce identical layout ### Test 2: Complex Schema (DIFFERENCES expected) **File**: `full_schema_20251123_174151.mmd` (264 lines) **Structure**: Multiple inheritance, cross-references ``` Multiple root classes Complex relationships Many-to-many connections Deep hierarchies ``` **Result**: - `network-simplex`: Balanced, medium height - `tight-tree`: Compressed, shorter height - `longest-path`: Stretched, taller height ### Test 3: Multi-Aspect Model (SUBTLE differences) **File**: `custodian_multi_aspect_20251122_155319.mmd` **Structure**: Hub-and-spoke with cross-links ``` Central hub (CustodianObservation) Multiple aspects radiating out Cross-aspect relationships ``` **Result**: - `network-simplex`: Centered hub, even spacing - `tight-tree`: Compressed vertical spacing - `longest-path`: Emphasized main paths --- ## ๐Ÿ“Š Performance Comparison | Ranker | Time Complexity | Space | Best Use | |--------|----------------|-------|----------| | **network-simplex** | O(nยฒ) | Balanced | General | | **tight-tree** | O(n log n) | Compact | Space-constrained | | **longest-path** | O(n) | Spread | Workflows | **For small diagrams (<50 nodes)**: Performance difference negligible --- ## ๐Ÿ’ก Why The Confusion? ### User Expectation "Adaptive (Tight Tree)" sounds like a completely different layout style โ†’ Users expect visually distinct appearance ### Technical Reality It's the same layout engine with different ranking algorithm โ†’ Produces similar results for simple graphs ### Solution Options **Option 1**: Update UI descriptions ```typescript // Current "Compact arrangement, minimal whitespace" // Better "Minimizes height (visible in complex diagrams)" ``` **Option 2**: Add complexity indicator ```typescript if (diagram.nodes.length < 20) { showMessage("Tip: Try a complex diagram to see ranker differences"); } ``` **Option 3**: Side-by-side comparison mode - Render with all 3 rankers - Show actual differences - Educational value --- ## ๐ŸŽ“ Key Takeaways 1. **Rankers are optimization algorithms, not layout styles** - They decide which nodes go on which rank (horizontal level) - Same spacing rules apply to all rankers - Visual differences depend on graph complexity 2. **Simple trees โ†’ identical layouts** - All rankers agree on optimal ranking - No alternative solutions exist - This is EXPECTED behavior 3. **Complex graphs โ†’ visible differences** - Multiple valid rankings exist - Each ranker optimizes for different goals - Load `full_schema_20251123_174151.mmd` to see 4. **Not a bug, it's algorithm convergence** - Mathematically correct behavior - UI clarity could be improved - User education helps set expectations --- ## ๐Ÿ” How To Verify This ### Step 1: Load Simple Diagram 1. Open `http://localhost:5173/uml-viewer` 2. Load `NetworkOrganisation_20251123_225712.mmd` 3. Switch between: - Hierarchical (Topโ†’Bottom) [network-simplex] - Adaptive (Tight Tree) [tight-tree] 4. **Observe**: Layouts look identical โœ“ ### Step 2: Load Complex Diagram 1. Load `full_schema_20251123_174151.mmd` 2. Switch between same layouts 3. **Observe**: Layouts now differ! โœ“ - Hierarchical: Balanced spacing - Tight Tree: Compressed height - Longest Path: Emphasized depth ### Step 3: Compare Metrics - Count vertical ranks in each layout - Measure total graph height - Note node clustering differences --- ## ๐Ÿ“š Further Reading **Dagre Documentation**: - Ranker algorithms: https://github.com/dagrejs/dagre/wiki#configuring-the-layout - Layout options: https://github.com/dagrejs/dagre/wiki/Configuring-the-Layout **Graph Theory**: - Sugiyama framework (hierarchical layout) - Network simplex algorithm - Longest path in DAGs **UML Best Practices**: - When to use different layouts - Choosing ranker for diagram type - Performance optimization tips --- **Created**: November 24, 2025 **Purpose**: Explain dagre ranker behavior **Conclusion**: Layout similarity is expected for simple diagrams **Recommendation**: Test with complex diagrams to see differences **Next**: Load `full_schema_20251123_174151.mmd` and compare all 5 layouts!