*! touched NJC 26sep2025

*! version 1.2.1 08oct2025

Title

splitvarlabels -- Split variable labels for multiline graph display

Syntax

splitvarlabels
varlist
[, length(#) break delimiter(string) local(name)]

Main
length(#) target maximum length of each line; default is length(15)

break allow breaking words mid-word if necessary

delimiter(string) split at a specified delimiter character

local(name) store results in specified local macro

Description

splitvarlabels allows you to include variable labels in graphs on multiple lines
produced directly or indirectly by graph bar, graph hbar or graph dot.

It does so by splitting the variable labels into smaller pieces and returning those pieces
in a form appropriate for specification as part of a graph command, typically with the
ascategory option. A multiline format reduces how often variable labels overlap or
are truncated. The variable labels themselves are unchanged.

The variables must be specified in the same order when using splitvarlabels and in any
subsequent graph command. Otherwise, a mislabelling error is likely.

The command displays the split labels as it processes them so you can immediately see
how the labels will appear without waiting to generate a graph.

Options

Main

length(#) specifies the target maximum length for each line of the split label.
The default is 15 characters. By default, the command attempts to keep whole words intact, which may result in lines exceeding this length when necessary to avoid breaking words.

break allows the command to break words mid-word to strictly enforce the length limit.
As noted above, by default, splitvarlabels preserves whole words even if doing so exceeds
the specified length. Use this option when strict length limits are more important than
keeping words intact, such as when working with narrow graph spaces or strict formatting requirements.

delimiter(string) specifies a delimiter at which to split the label. When this option is specified
and the delimiter is found in the label, the label is split just before the delimiter, overriding
the length() setting for that split. This is particularly useful for splitting at natural
breakpoints such as parentheses, colons, or dashes. The delimiter itself remains at the beginning
of the next line. Note that when a delimiter is found, its position becomes the effective length
for all subsequent splits of that particular label. This means that text following the delimiter
will continue to be split at this same length, which may produce unexpected results if the
remaining text is lengthy.

local(name) stores the relabeling specification in the specified local macro, in addition to the standard s(relabel) storage.
This may be useful in programming contexts or when processing multiple variable sets.

Examples

Example 1: Basic usage with long labels

Long variable labels often overlap or get truncated in graphs. splitvarlabels solves this problem by splitting them across multiple lines:

. sysuse uslifeexp.dta, clear

. label var le_wmale "Life expectancy of white males in the United States of America"

. label var le_wfemale "Life expectancy of white females in the United States of America"

. label var le_bmale "Life expectancy of black males in the United States of America"

. label var le_bfemale "Life expectancy of black females in the United States of America"

. local le le_wmale le_wfemale le_bmale le_bfemale

. splitvarlabels `le'

. graph bar `le', ascategory yvar(relabel(`s(relabel)'))

Example 2: Using with graph wrappers like statplot

splitvarlabels works with graph wrapper commands that indirectly use graph bar, graph hbar or graph dot as well.
Here we use it with statplot from SSC:

. ssc install statplot

. splitvarlabels `le', length(20)

. statplot `le', varopts(label(labsize(small)) relabel(`s(relabel)'))

Example 3: Demonstrating the break option

Sometimes you need strict length control, even if it means breaking words. The break option allows this:

. sysuse auto, clear

. label var mpg "Fuel-efficiency-measurement in miles per gallon"

Default behavior keeps "Fuel-efficiency-measurement" intact despite exceeding 10 characters in length:

. splitvarlabels mpg, length(10)

With the break option, the command enforces a strict 10-character limit:

. splitvarlabels mpg, length(10) break

Example 4: Getting meaningful labels

When graphing statistics, Stata's default labels like "mean of collgrad" may not be what the user requires. splitvarlabels provides the actual variable labels:

. sysuse nlsw88, clear

. label var collgrad "Individual graduated from college"

. label var married "Individual is currently married"

. label var c_city "Individual lives in central city"

Without splitvarlabels, you get "mean of collgrad", "mean of married", etc.:

. graph hbar (mean) collgrad married c_city, ascategory title("Select Means")

To manually fix this without splitvarlabels is somewhat tedious:

graph hbar (mean) collgrad married c_city, ascategory yvar(relabel(1 "`:var label collgrad'" 2 "`:var label married'" 3 "`:var label c_city'")) title("Select Means")

Or spelling out the labels manually:

. graph hbar (mean) collgrad married c_city, ascategory yvar(relabel(1 "Individual graduated from college" 2 "Individual is currently married" 3 "Individual lives in central city")) title("Select Means")

With splitvarlabels, it's relatively straightforward:

. splitvarlabels collgrad married c_city

. graph hbar (mean) collgrad married c_city, ascategory yvar(relabel(`s(relabel)')) title("Select Means")

Example 5: Using local() option for multiple graphs

When creating multiple related graphs, the local() option lets you store different label sets without rerunning splitvarlabels immediately before each graph:

. label var union "Individual is member of labor union"

. label var south "Individual resides in southern region"

. label var smsa "Individual lives in standard metropolitan statistical area"

. local demographics collgrad married union

. local geography south c_city smsa

. splitvarlabels `demographics', local(demo_labels)

. splitvarlabels `geography', local(geo_labels)

Now you can create multiple graphs without rerunning splitvarlabels:

. graph hbar (mean) `demographics', ascategory yvar(relabel(`demo_labels')) title("Demographics")

. graph hbar (mean) `geography', ascategory yvar(relabel(`geo_labels')) title("Geography")

Example 6: Using delimiter for metadata on separate lines

The delimiter() option is particularly useful when adding metadata like sample size or units to labels.
It ensures the metadata appears on a separate line by splitting at a natural breakpoint:

. webuse nhanes2, clear

. summarize bmi weight height

. label var bmi "Body Mass Index (kg/m²)"

. label var weight "Body Weight (kg)"

. label var height "Standing Height (cm)"

Split at the opening parenthesis to place units on a separate line:

. splitvarlabels bmi weight height, delimiter("(")

. statplot bmi weight height, over(sex) varopts(relabel(`s(relabel)'))

Saved Results

splitvarlabels saves the following in s():

s(relabel) contains the relabeling specification for use with graph commands.
If the local() option is specified, the same relabeling specification is also stored in the specified local macro.

Authors

Kabira Namit

World Bank

knamit@worldbank.org

Nicholas J. Cox

Durham University

n.j.cox@durham.ac.uk

Acknowledgments

splitvarlabels was directly inspired by and heavily influenced by Nicholas Winter and Ben Jann's splitvallabels (August 2008), available on SSC.