Hierarchical quantitative breakdowns
Compare quantities across nested categories.
Plotly · Class
go.Treemap
go.Treemap is a Plotly trace for representing hierarchical data with nested rectangles. Its sectors are defined by labels or IDs, parent relationships, and optionally numeric values.
How it works
Instantiate go.Treemap with hierarchical labels and parent references; optional values determine sector sizes and can be aggregated according to branchvalues. Add the trace to a Figure to render the interactive rectangles.
Syntax
plotly.graph_objects.Treemap(arg=None, alignmentgroup=None, ... , values=None, visible=None, **kwargs)Parameters
| Name | Type | Description |
|---|---|---|
arg | dict or plotly.graph_objects.Treemap | Dictionary of properties compatible with this constructor, or an existing Treemap object. |
branchvalues | str | Controls how values are summed for branch nodes. |
labels | list | Labels displayed for sectors. |
parents | list | Parent reference for each sector. |
values | list | Numeric values used to size sectors. |
visible | bool or str | Whether to display the trace. |
Returns
A plotly.graph_objects.Treemap trace object.
Key points
- Use the class to display hierarchical data as rectangles, progressing from leaf or outer-branch entries toward a root.
- Define sectors with
labelsorids, and connect them into the hierarchy throughparents. - The
branchvaluesproperty controls the aggregation rule for numeric values across branches. - The
countproperty supplies the default value behavior when novaluesarray is given.
Common mistakes
- Every sector needs a coherent hierarchy: use
labelsor uniqueidstogether with matchingparentsentries. - Choose
branchvaluesdeliberately because it changes how parent totals relate to descendant values. - If
valuesis omitted, Plotly infers defaults rather than treating every sector as having an explicitly supplied measurement.
Example: Basic hierarchical treemap
import plotly.graph_objects as go
fig = go.Figure(go.Treemap(
labels=["Company", "Engineering", "Sales", "Backend", "Frontend"],
parents=["", "Company", "Company", "Engineering", "Engineering"],
values=[100, 60, 40, 35, 25],
))
fig.show()Creates a hierarchical treemap whose rectangles are defined by labels, parent relationships, and numeric values.
When to use it
Part-to-whole exploration
Show how leaf items roll up into branches and a root.
Interactive hierarchy navigation
Build interactive drillable category views in a Plotly figure.
Interview questions
QWhat does go.Treemap represent, and how is its hierarchy specified?
go.Treemap visualizes hierarchical data with nested rectangles. The hierarchy comes from labels or ids plus parents, while values controls the quantitative size of sectors.
Follow-up: How are parent values interpreted? branchvalues determines how values are summed across branches, so it should match whether parent values include descendants.
QWhat are the main constructor inputs?
The constructor accepts a dictionary of compatible properties or another Treemap instance through arg, followed by trace properties such as labels, parents, values, and branchvalues. This lets callers configure the trace directly or from property mappings.
Follow-up: Why might ids be preferable to labels? IDs provide stable sector identity when displayed labels are duplicated or change.
QWhat happens if values is omitted?
When values is not supplied, the class infers a default of 1 for leaves and/or branches and otherwise 0. Explicit values are preferable when rectangle areas must represent measured quantities.
Follow-up: What should be checked when inferred values look unexpected? Inspect whether nodes are leaves or branches and provide an explicit values array when needed.
Related
plotly.graph_objects.Figureplotly.graph_objects.Sunburstplotly.graph_objects.Icicleplotly.graph_objects.layout.template.data.Treemap