Hierarchical Charts

Visualize nested data and tree structures.

All hierarchical charts require engine: d3.

---

Treemap

Show nested proportions as rectangles.

```dg
type: treemap
engine: d3
data:
  source: |
    [
      {"name": "root", "parent": null, "value": 0},
      {"name": "Engineering", "parent": "root", "value": 0},
      {"name": "Design", "parent": "root", "value": 0},
      {"name": "Frontend", "parent": "Engineering", "value": 4500},
      {"name": "Backend", "parent": "Engineering", "value": 3800},
      {"name": "DevOps", "parent": "Engineering", "value": 2100},
      {"name": "UX", "parent": "Design", "value": 2400},
      {"name": "Visual", "parent": "Design", "value": 1800}
    ]
hierarchy:
  id: name
  parent: parent
  value: value
width: 700
height: 500
title: "Team Budget Allocation"
```

When to use: Showing proportions within a hierarchy (budgets, file sizes, org structure).

---

Sunburst

Radial hierarchy visualization.

```dg
type: sunburst
engine: d3
data:
  source: |
    [
      {"name": "root", "parent": null, "value": 0},
      {"name": "Documents", "parent": "root", "value": 0},
      {"name": "Projects", "parent": "root", "value": 0},
      {"name": "Work", "parent": "Documents", "value": 2500},
      {"name": "Personal", "parent": "Documents", "value": 1800},
      {"name": "WebApp", "parent": "Projects", "value": 4500},
      {"name": "MobileApp", "parent": "Projects", "value": 3800}
    ]
hierarchy:
  id: name
  parent: parent
  value: value
width: 550
height: 550
title: "Disk Space Usage (MB)"
```

When to use: Interactive drill-down into hierarchies, showing depth and proportion.

---

Circle Packing

Nested circles for hierarchical data.

```dg
type: circle-packing
engine: d3
data:
  source: |
    [
      {"name": "Science", "parent": null, "value": 0},
      {"name": "Physics", "parent": "Science", "value": 0},
      {"name": "Biology", "parent": "Science", "value": 0},
      {"name": "Quantum", "parent": "Physics", "value": 4500},
      {"name": "Relativity", "parent": "Physics", "value": 3200},
      {"name": "Genetics", "parent": "Biology", "value": 5100},
      {"name": "Ecology", "parent": "Biology", "value": 2900}
    ]
hierarchy:
  id: name
  parent: parent
  value: value
width: 600
height: 600
title: "Research Citations by Field"
```

When to use: Aesthetic hierarchical visualization where depth matters more than precise comparison.

---

Dendrogram

Tree diagram showing relationships.

```dg
type: dendrogram
engine: d3
data:
  source: |
    [
      {"name": "CEO", "parent": null},
      {"name": "CTO", "parent": "CEO"},
      {"name": "CFO", "parent": "CEO"},
      {"name": "VP Engineering", "parent": "CTO"},
      {"name": "VP Product", "parent": "CTO"},
      {"name": "Controller", "parent": "CFO"},
      {"name": "Frontend", "parent": "VP Engineering"},
      {"name": "Backend", "parent": "VP Engineering"}
    ]
hierarchy:
  id: name
  parent: parent
orientation: horizontal
width: 800
height: 500
title: "Organization Chart"
```

When to use: Org charts, taxonomies, decision trees.

---

Tidy Tree

Cleaner tree layout with better spacing.

```dg
type: tidy-tree
engine: d3
data:
  source: |
    [
      {"name": "Animalia", "parent": null},
      {"name": "Chordata", "parent": "Animalia"},
      {"name": "Arthropoda", "parent": "Animalia"},
      {"name": "Mammalia", "parent": "Chordata"},
      {"name": "Aves", "parent": "Chordata"},
      {"name": "Insecta", "parent": "Arthropoda"},
      {"name": "Primates", "parent": "Mammalia"},
      {"name": "Carnivora", "parent": "Mammalia"}
    ]
hierarchy:
  id: name
  parent: parent
orientation: horizontal
width: 750
height: 500
title: "Animal Taxonomy"
```

When to use: When node labels are important and space between nodes matters.

---

Icicle (Partition)

Rectangular partition layout.

```dg
type: icicle
engine: d3
data:
  source: |
    [
      {"name": "/", "parent": null, "value": 0},
      {"name": "usr", "parent": "/", "value": 0},
      {"name": "var", "parent": "/", "value": 0},
      {"name": "bin", "parent": "usr", "value": 2400},
      {"name": "lib", "parent": "usr", "value": 8500},
      {"name": "log", "parent": "var", "value": 5600},
      {"name": "cache", "parent": "var", "value": 3800}
    ]
hierarchy:
  id: name
  parent: parent
  value: value
width: 700
height: 450
title: "File System Usage (MB)"
```

When to use: File system views, flame graphs, sequential hierarchy.

---

Data Format

All hierarchical charts use the same data format:

hierarchy:
  id: name       # Unique identifier field
  parent: parent # Parent reference field
  value: value   # Size/weight (optional for tree charts)

Required fields:

• id - Unique name for each node
• parent - Reference to parent node (null for root)
• value - Numeric size (required for treemap, sunburst, icicle, circle-packing)

---

Configuration Options

Option	Type	Default	Description
orientation	string	horizontal	horizontal or vertical (dendrogram, tidy-tree)
hierarchy.id	string	-	Field for node identifier
hierarchy.parent	string	-	Field for parent reference
hierarchy.value	string	-	Field for node size

---

Tips

Tip: The root node should have parent: null and typically value: 0.

Common Mistake: Forgetting to include intermediate nodes. Every parent value must exist as an id.

Tip: For large hierarchies, consider using external JSON files:

data:
  file: data/org-chart.json

---

See Also

• Network Charts - For non-hierarchical relationships
• Pie Charts - For flat proportions