help circlepackcirclepack v1.2 (GitHub)

circlepack

: A Stata package for hierarchical circle packing.

This program implements the A1.0 algorithm (Huang et. al. 2006) based on D3's packEnclose and Python's circlify routines.

Syntax

circlepack numvar [if] [in], by(variables (min=1, max=3))
[ pad(num) points(num) angle(num) circle0 circle0c(str) format(str) palette(string) share
labprop titleprop labscale(num) threshold(num) fi(list) addtitles novalues nolabels labsize(num)
title(str) subtitle(str) note(str) scheme(str) name(str) ]

The options are described as follows:

circlepack numvar The command requires a numeric variable that contains the values.

by(group vars) At least one by() string variable needs to be specified, and a maximum of three string variables are allowed. These also are used as labels.
The order is parent layer first followed by child layer or more aggregated layers should be specified first.

pad(num) Add padding to the circles. Default value is 0.1. A value of 0 implies no padding.

points(num) Number of points to define the circles. Default value is 60. A value of 3 = triangles, 6 = hexagons, 8 = octagons, etc.
If you are exporting a very large impact, value > 60 is recommended for smoother circles.

angle(num) Angle of the points. Default value is 0. Any value specified here will rotate the points on the circle.
For example, if you draw hexagons, you can rotate the shapes using this option.

threshold(num) The value below which categories are combined in a "Rest of ..." category. Default is thresh(0).

labcond(value) The minimum value for showing the value labels. For example, labcond(20) will only plot values greater than 20.

format(fmt) Format the values of the labels. The default option is format(%12.0fc) for values and format(%5.2f) for the percent option.

share Show percentage shares of the total instead of the actual values for all the layers.

circle0 Drawing the bounding circle.

circle0c(str) Define the bounding circle color.

palette(str) Color name is any named scheme defined in the colorpalette package. Default is tableau.

fi(numlist max=3) The fill intensity of the layers in the other they are specified. The default values are fi(50 75 100).

addtitles Add titles to upper layers. This adds the name and value in the top left corner of the boxes.

titleprop Make the size of the box titles proportional to the area.

labprop Make the size of the labels proportional to the area.

labscale(num) This option changes how the labels are scaled. This is an advanced option and should be used cautiously. Default value is labscale(0.5).
The scaling is sensitive to change in this value so modify in small increments.

novalues Do not add the values in the inner-most boxes. If the graph is too crowded, this option might help.

nolabels Do not add anylabels. This gives just boxes without any numbers.

labsize(string max=3) The size of the labels. The default values are labs(2 2 2). If only one value is specified, it will passed on to all the layers.

title, subtitle, note These are standard twoway graph options.

scheme(str) Load the custom scheme. Above options can be used to fine tune individual elements.

Dependencies

The palette package (Jann 2018, 2022) is required for circlepack:

ssc install palettes, replace
ssc install colrspace, replace

Even if you have these installed, it is highly recommended to check for updates: ado update, update

Examples

Set up the data

use "https://github.com/asjadnaqvi/stata-circlepack/blob/main/data/demo_r_pjangrp3_clean.dta?raw=true", clear

drop year
keep NUTS_ID y_TOT

drop if y_TOT==0

keep if length(NUTS_ID)==5

gen NUTS2 = substr(NUTS_ID, 1, 4)
gen NUTS1 = substr(NUTS_ID, 1, 3)
gen NUTS0 = substr(NUTS_ID, 1, 2)

ren NUTS_ID NUTS3

- circlepack y_TOT, by(NUTS0)

- circlepack y_TOT, by(NUTS0) addtitles labsize(2) format(%15.0fc)

- circlepack y_TOT if NUTS0=="AT", by(NUTS3 NUTS2) addtitles noval labsize(1.6) format(%15.0fc)

Acknowledgements

Fayssal Ayad found errors with duplicate and zero values that was causing the layers to be drawn improperly (v1.01).

Package details

Version : circlepack v1.2
This release : 15 Jan 2023
First release: 08 Sep 2022
Repository : GitHub
Keywords : Stata, graph, circle packing, circlepack, A1.0
License : MIT

Author : Asjad Naqvi
E-mail : asjadnaqvi@gmail.com
Twitter : @AsjadNaqvi

References

Huang, W., Li, Y., Li, C.M., Xu, R.C. (2006). New heuristics for packing unequal circles into a circular container. Computers & Operations Research 33(8).

Bostock, M. D3 packEnclose. Observable HQ.

Jann, B. (2018). Color palettes for Stata graphics. The Stata Journal 18(4): 765-785.

Jann, B. (2022). Color palettes for Stata graphics: an update. University of Bern Social Sciences Working Papers No. 43.

Lecomte, J. Python circlify.

Other visualization packages

arcplot, alluvial, bimap, bumparea, bumpline, circlebar, circlepack, clipgeo, delaunay, joyplot,
marimekko, sankey, schemepack, spider, streamplot, sunburst, treecluster, treemap