help labrepel v1.0graphfunctions (GitHub)

(back to help graphfunctions)

labrepel

: is a Stata program for automatically repositioning point labels using a force-directed algorithm.

The command takes a y-x coordinate pair and a label variable, then creates adjusted coordinates in _xcoord and _ycoord.
It is designed for crowded scatter plots where labels overlap and manual adjustment is not practical.

This program is currently in beta. It is inspired by R ggrepel function, and uses a force-directed layout algorithm for label placement.

Syntax

labrepel yvar xvar [if] [in], label(varname)
[ boxpadding(num) push(num) pull(num) damping(num) cooling(num) maxiter(int) maxtime(num) maxoverlaps(int)
maxdisplacement(num) nudgex(num) nudgey(num) direction(str) seed(int) jitter(num) xlimit(min max) ylimit(min max)
xsize(num) ysize(num) mlabsize(num) hjust(num) vjust(num) center nodetail ]

Options

Required

labrepel yvar xvar The command requires two numeric variables in y-x order for label anchor positions.

label(varname) String variable containing label text. Empty labels are ignored.

Force parameters

boxpadding(num) Padding around label bounding boxes. Higher values add more spacing. Default is boxpadding(0.05).

push(num) Repulsion strength for overlapping labels. Higher values push labels apart more strongly. Default is push(3).

pull(num) Attraction strength pulling labels toward original positions (or away from center with center). Default is pull(1.5).

damping(num) Movement damping factor. Lower values move labels more slowly and smoothly. Default is damping(0.3).

cooling(num) Minimum cooling factor as iterations progress. Default is cooling(0.2).

Algorithm control

maxiter(int) Maximum number of iterations. The algorithm may converge earlier. Default is maxiter(50).

maxtime(num) Maximum runtime in seconds. Default is maxtime(10).

maxoverlaps(int) Threshold used in overlap warnings in detailed output. Default is maxoverlaps(10).

maxdisplacement(num) Maximum displacement as a fraction of data range. Default maxdisplacement(0) applies an internal 10% range cap.

jitter(num) Random perturbation for breaking symmetric force cancellation in dense clusters. Default is jitter(0).

seed(int) Random seed used with jitter() for reproducible placement.

Position control

nudgex(num), nudgey(num) Initial global x and y offsets applied before optimization. Defaults are nudgex(0) and nudgey(0).

direction(str) Restrict movement to both (default), x, or y.

center Push labels away from plot center rather than pulling them toward original anchor points.

Plot dimensions

xlimit(min max), ylimit(min max) Explicit coordinate limits. If omitted, limits are computed from the estimation sample.

xsize(num), ysize(num) Declared graph dimensions in inches for converting label sizes to data units. Defaults are xsize(5) and ysize(3).

Label size and alignment

mlabsize(num) Label size multiplier used for bounding-box calculations. Default is mlabsize(2.5).

hjust(num), vjust(num) Horizontal and vertical label justification in [0,1]. Default is hjust(0.5) and vjust(0.5).

Display

nodetail Suppress detailed diagnostics. By default, detailed output is shown.

Stored results

labrepel stores the following in r():

Local macros

r(n_labels) number of non-empty labels processed

r(iterations) number of iterations completed

r(direction) movement direction used (both, x, or y)

Variables created

_xcoord adjusted x coordinates for label positions

_ycoord adjusted y coordinates for label positions

Examples

See GitHub for more examples.

Feedback

Please submit bugs, errors, feature requests on GitHub by opening a new issue.

Package details

Version : labrepel v1.0 in graphfunctions
This release : 08 Mar 2026
First release: 08 Mar 2026
Repository : GitHub
Keywords : Stata, graph, labels, repulsion, force-directed layout
License : MIT

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

Citation guidelines

Visit https://ideas.repec.org/c/boc/bocode/s459379.html for the official SSC citation.
Please note that the GitHub version might be newer than the SSC version.

Other visualization packages

arcplot, alluvial, bimap, bumparea, bumpline, circlebar, circlepack, clipgeo, delaunay, graphfunctions,
geoboundary, geoflow, joyplot, marimekko, polarspike, sankey, schemepack, spider, splinefit, streamplot,
sunburst, ternary, tidytuesday, treecluster, treemap, trimap, waffle, vcontrol

Visit GitHub for further details.