help treemapv

Title

treemapv -- Voronoi treemap visualization (under development)

Requires Stata 17 or later (uses frames for data handling)

Syntax

treemapv numvar [if] [in] [weight], by(varlist) [options]

Required
by(varlist) One to three variables defining the hierarchy (max 3 levels).

Canvas
xsize(num) Width of the plot in inches. Default is 5.

ysize(num) Height of the plot in inches. Default is 3.

Algorithm
convergence(num) Target convergence ratio for Voronoi iteration. Default is 0.01 (1%).

maxiter(int) Maximum iterations for weighted Voronoi computation. Default is 50.

minweight(num) Minimum weight as ratio of maximum. Default is 0.01 (1%).

seed(int) Random seed for initial site positions. Default is 12345.

Data
threshold(num) Collapse categories smaller than threshold into "Rest of..." Default is 0.

stat(str) Statistic to compute: sum (default) or mean.

share Display shares/percentages instead of values.

colorby(var) Variable to determine color grouping.

Styling
palette(str) Color palette. See colorpalette.

pad(numlist) Padding between boxes (up to 3 values for each level).

linewidth(str) Width of boundary lines.

linecolor(str) Color of boundary lines.

fade(num) Color intensity. Default is 10.

Labels
nolabels Suppress all labels.

novalues Suppress values, show only category names.

addtitles Add variable names as titles.

labsize(str) Size of labels.

labgap(str) Gap between labels.

labscale(num) Label scaling factor. Default is 0.3333.

labcond(num) Conditional display of labels based on area.

labprop Scale labels proportional to box area.

wrap(numlist) Character limits for label wrapping.

aweights, fweights, pweights, and iweights are allowed.

Description

treemapv creates Voronoi treemap visualizations, which display hierarchical data using
weighted Voronoi tessellations instead of rectangles. This creates organic-looking boundaries
that can be more aesthetically pleasing than traditional rectangular treemaps.

The algorithm is based on d3-voronoi-treemap by Philippe Rivière, which uses iterative
weighted Voronoi diagrams to create hierarchical visualizations where each cell's area
is proportional to its value.

CURRENT STATUS (v0.2): The command integrates with delaunay.ado and voronoi.ado
to compute basic Voronoi tessellations. The Lloyd's relaxation framework is implemented but
weighted iteration (area matching) is not yet complete. Currently falls back to rectangular
treemap layout.

Working components:

- Basic Voronoi diagram computation via delaunay package

- Iteration framework for weighted adjustment

- Polygon area and centroid calculations (Mata functions)

- Initial site positioning

Not yet implemented:

- Weighted iteration (adjusting sites to match target areas)

- Convergence checking (requires area calculation integration)

- Hierarchical recursion (nested Voronoi cells)

For production use of true Voronoi treemaps, consider:

- D3.js with d3-voronoi-treemap

- Python with voronoi-treemap package

- R with treemap package (Voronoi option)

Algorithm Overview

The Voronoi treemap algorithm works recursively:

1. Start with a clipping polygon (typically rectangular canvas)

2. Place random initial "sites" for each data point

3. Compute weighted Voronoi diagram (Lloyd's relaxation):

a. Generate Voronoi tessellation from sites

b. Compute centroid of each Voronoi cell

c. Weight centroids by target weights (proportional to values)

d. Move sites toward weighted centroids

e. Repeat until convergence or max iterations

4. Recursively apply to children using their Voronoi cells as clipping regions

Examples

Single level hierarchy

. sysuse auto, clear

. treemapv price, by(rep78)

Two level hierarchy

. treemapv price, by(foreign rep78) palette(CET C6)

Three level hierarchy with options

. treemapv price, by(foreign rep78 make) threshold(1000) novalues

Custom convergence settings

. treemapv price, by(rep78) convergence(0.005) maxiter(100)

Technical Notes

The Voronoi diagram computation requires:

- Delaunay triangulation

- Voronoi edge computation from Delaunay dual graph

- Polygon clipping operations (Sutherland-Hodgman algorithm)

- Iterative weighted centroidal Voronoi tessellations (WCVT)

- Recursive polygon subdivision

These operations are not available in native Stata and would require either:

1. Mata implementation of computational geometry algorithms

2. Integration with external libraries (C, Python, etc.)

3. Pre-computation in another language and import to Stata

Dependencies

The command requires the following packages:

ssc install carryforward - Data manipulation

ssc install graphfunctions - Label utilities

ssc install palettes - Color palettes

ssc install colrspace - Color space conversions

For Voronoi computation (should be in ./voronoi/ folder):

delaunay.ado - Delaunay triangulation and Voronoi tessellation

voronoi.ado - Voronoi diagram utilities

Available at: https://github.com/asjadnaqvi/stata-delaunay

References

Voronoi treemaps are described in:

Balzer, M. and Deussen, O. (2005). "Voronoi Treemaps".
IEEE Symposium on Information Visualization (InfoVis 2005).

Nocaj, A. and Brandes, U. (2012). "Computing Voronoi Treemaps: Faster, Simpler, and Resolution-independent".
Computer Graphics Forum, 31(3): 855-864.

Author

Asjad Naqvi (asjadnaqvi@gmail.com)

If you find this useful, please cite:

Naqvi, A. (2026). "Stata package for treemap visualizations".
GitHub repository: https://github.com/asjadnaqvi/stata-treemap

Also see

treemap (standard rectangular treemap)