Speaking Stata: Automating axis labels: Nice numbers and transformed scales

Abstract

Two common problems with graph axis labels are to decide in advance on some “nice” numbers to use on one or both axes and to show particular labels on some transformed scale. In this column, I discuss the nicelabels and mylabels commands, which address these problems. The first command is new to Stata, and the second is a revision of a previously published command. I also survey the myticks command for tick placement. In all commands, the main output is a local macro in the calling program’s space, in the interest of promoting automation in do-files and programs.

1 Introduction

Consider a routine Stata graph, such as figure 1 obtained with Stata’s auto data. If you wish, you can read in the dataset yourself and follow the thread actively by typing in commands.

Figure 1.

A common or garden scatterplot showing how graph twoway chooses “nice” axis labels automatically

Users of Stata’s graphics commands quickly learn that there is an automatic choice of axis labels for such graphs. In auto.dta, mpg varies from 12 to 41 (miles per gallon), and weight varies from 1760 to 4840 (pounds). With scatter and many other commands, you get “nice” axis labels by default. For this graph, the y-axis labels are 10(10)40 for mpg, and the x-axis labels are 2000(1000)5000 for weight. The notation start(step)stop implies numeric values running from start to stop in increments of step.

Here “nice” is a term of art as well as a simple English word. Part of the business of this column is to give some discussion of what it means for axis labels. As in the rest of life, niceness can be easy to recognize but harder to define precisely or universally.

Users also should quickly learn that you can reach in and override the default label choices if you prefer something else. For example, you might want axis labeling to start at 0, include more labels, or differ in some other way from the default. If so, spell out, say, ylabel(0(10)40) or ylabel(0(5)40). Such flexibility is helpful and indeed essential for statistical and related purposes. Examples could be multiplied, but let’s just also mention showing critical levels (say, legal or clinical or physical thresholds) or summary values (say, mean or median) as particular axis labels. From this point of view, 32 ^◦ F as the freezing point on the Fahrenheit scale could be a helpful label if that temperature fell into the range of some data.

Sections 2 and 3 of this column focus on needs where neither the default nor the flexibility of specifying different choices on the fly is quite the answer. A problem often raised by users is wanting a series of graphs to follow the same label choices—because left to follow its own rules, graph might show different labels for different subsets of the data. But if we know the limits of a variable in principle, or we can work them out in practice for the entire dataset, then we should be able to identify some standardized choices. A new command, nicelabels, uses simple algorithms to suggest automatically “nice” labels, given some information. The possibilities allowed by nicelabels do not reach as far as more subtle (and inevitably more complicated) algorithms. Hence, the area remains wide open for further work.

Users frequently want to show values on transformed scales. By far the most common example is that one or even both axes use logarithmic scales. graph provides specific support for such scales, using the yscale(log) and xscale(log) options. That said, the accompanying choice of labels is often awkward. The niceloglabels command (Cox 2018, 2020a) was published in an earlier column as an alternative. Its users do need to specify a style, as label styles such as 1, 2, 5, 10 or 1, 3, 10 or powers of 2 may each be appropriate or appeal otherwise. niceloglabels offers a choice between those and yet other styles.

Although less common than logarithmic scales, various other nonlinear scales are possible in statistical applications. Square root, cube root, reciprocal, and logit scales are some leading examples. In principle, you just need to calculate what you want to show before the graph is drawn. The more challenging task is to show text labels on the original scales, just as with yscale(log) or xscale(log), values like 1, 10, or 100 would often be shown as axis labels, not the corresponding logarithms.

Sections 4 and 5 here discuss a generic solution for labels on transformed scales, which is to loop over the text to be shown as axis labels and to work out where to put it in each case (Cox 2008b, 2012). To this end, the community-contributed command mylabels has been under development since 2003. Early mentions include Cox (2004, 2005a). A revised version is now published formally in this issue. The idea of transformation implemented is quite wide and includes scope to add text as a prefix or suffix to axis labels.

Any readers new to Stata or more familiar with other software might like a confirmation that Stata’s axis labels are not text titles for an axis but any text shown at axis ticks. Other terms that can be found include tick mark label (Cleveland 1985, 23; 1994, 24; Robbins 2013, 156) and tick label (Koponen and Hildén 2019, 206).

2 nicelabels in practice

2.1 nicelabels fed minimum and maximum

nicelabels supports two main syntaxes, one in which a variable is named and one in which two numbers are specified, typically some minimum and maximum. The second syntax seems likely to be less often used, but it is a good place to start the story.

nicelabels suggests, by default, what Heckbert (1990) called “loose” labels, which often go beyond the minimum and maximum suggested. Conversely, the tight option is not so generous. The choice between them can be regarded as partly technical detail and partly a matter of taste. Using the tight option promotes full use of the plot region, typically reducing the amount of space surrounding data elements on a graph.

As the examples show, nicelabels suggests power-of-10 multiples of 1, 2, and 5 and suggests “about 5” labels by default, here 6 and 4, respectively, for the loose and tight options. If you are interested in the algorithm, take a look at Heckbert (1990) or the code revealed after installation by

• . viewsource nicelabels.ado

Stata programmers will appreciate the close correspondence between Heckbert’s original pseudocode and C code and the Mata code used inside nicelabels.

The default of “about 5” labels echoes widespread statistical practice, exemplified in the suggestion by Cleveland (1985, 39; 1994, 39) of 3 to 10 labels on any axis.

Naturally, you may ask for more labels. You should guess that, rather than use a step of 20, the code might suggest a step of 10 if you ask for moderately more labels. Here adding the option nvals(10) leads to suggestions of 11 and 9 labels for the 2 basic choices. Although those results should seem plausible as being “about 10”, the number of values is a suggestion, not an instruction, so far as the code is concerned.

nicelabels insists on a local() option, naming a local macro to hold the results. If the idea of a local macro is new to you, consider it as a bag or box within your program space that contains text (which, as indicated, could be numeric characters and spaces). Among various lengthier introductions to local macros is a recent Speaking Stata column (Cox 2020b, 2021a).

This insistence on a local macro is intended to be in your own best interests, encouraging the use of that local macro within a later command, either interactively or in a do-file or program. Because nicelabels displays the labels suggested, you could also copy and paste them within Stata or even type them out again, but neither is recommended as ideal practice. The goal of self-documenting, reproducible code leads to emphasis on commands that run directly from a script. In this case, we have no data in sight, and a facetious macro name foo does no harm. As in the rest of Stata, an existing local macro will readily be overwritten. We kept using the same macro name, and there was no complaint from Stata. Overwriting local macros is usually a feature but may lead to a tiny loss of results if you are a little careless.

2.2 nicelabels fed a numeric variable name

Let’s now switch to the major syntax of nicelabels, based on asking the command to look at a numeric variable. Like auto.dta, census.dta, now used as a sandbox, is bundled with Stata, so you can follow along by typing the same commands.

For 50 states of the United States in 1980, let’s imagine working with median ages. The point is not that graph will not do a good job by itself but just to show how to work with nicelabels, given a variable of interest. As you might guess, nicelabels fires up summarize to find the range of a variable from minimum to maximum, but it does not show the results, so we will do that here. We see that the range is maximum − minimum = 34.7 − 24.2 = 10.5.

You feed the variable name to nicelabels, and here it makes various suggestions, depending on choice of the default or of options that you specify.

With its default, nicelabels is clearly struggling to find many nice numbers in the variable range. My inclinations for this variable run to a step of 2, not 5. You can check for yourself by plotting medage against any other variable that, left to itself, graph twoway agrees with that step.

Let’s use nicelabels to make our own version of a quantile plot, using a rank from 1 for the state with the youngest median age to 50 for the state with the oldest. We will run with age labels 24(2)36:

Figure 2 shows the result.

Figure 2.

Quantile plot for median ages of 50 U.S. states in 1980. nicelabels was used to obtain labels for median age.

A small lesson here is that the output of nicelabels and the display format of medage, or any other numeric variable, are quite separate matters. For some reason, medage has been assigned a display format of %9.2f, specifying display of values to two decimal places, which is one more than the resolution of the data themselves. Thus, we may want to spell out display of integers (zero decimal places). At the same time, the distribution deserves a little annotation. To my eye, states with ranks 1, 2, and 50 stand out from other states.

Figure 3 shows the result. Utah, Alaska, and Florida are unsurprising identifications.

Figure 3.

Quantile plot for median ages of 50 U.S. states in 1980. For this version, we specified a display format for the median age labels, and added some annotation.

2.3 Further twists

Let’s think how to tackle some further twists that may arise. For the sake of variety, examples are taken once more from auto.dta.

An axis should start at zero: Suppose you have a variable that is always positive, but you want an axis, and so axis labeling, to start at zero. Whether axes should start at zero is sometimes a vexed question in statistical graphics, but for now we will just run with that choice as a decision made. One way to do that is to feed nicelabels with 0 as one argument and the empirical maximum from summarize as another argument.

Note that using the maximum from the summarize command with options such as ylabel(0(10)`max’) or ylabel(0(20)`max’) or ysc(0 `max’) yla(#6) may be as or more effective, particularly if you have a clear idea in advance of a good step size. In either case, local max = r(max) should be assigned just after summarize.

Axis labels should include empirical minimum and maximum: A possibility shown by Tufte (2001, 149) is that the lowest and highest labels are the empirical minimum and maximum; the others are all “nice”. The trick here resembles that in the previous example—to get extremes from summarize but to let nicelabels, tight do the rest of the work.

Figure 4 shows the result. The example is candid in showing a limitation of the idea: it can seem a little awkward at best if a minimum or maximum label is very close to a nice label.

Figure 4.

A scatterplot with nice labels together with empirical minimum and maximum on each axis

Here we are exploiting how easy it is to redefine a local macro. nicelabels defines a local macro. As mentioned, you can think of such a macro as being like a bag that you may define and redefine as you please, here just by adding other values to the bag. Note that it is crucial to specify the local macro persona of a saved result, for example, `r(min)’ rather than r(min). Otherwise, you just add the result name r(min), not its current value, to the macro.

Controlling the number of labels: Redefining a macro is also crucial to the next twist here. In a do-file or program, we might want to insist on at least a certain number of axis labels. One idea is simple: Try out the nicelabels default and count how many labels are suggested; if that is not enough, fire up nicelabels again with the nvals() option. This idea could be coupled with trying both default and tight options or just one of the two choices.

As previously, but now finding that three labels are too few:

wordcount() does what it says—counts words. In Stata, words are separated by white space, so every label is counted as a separate word.

Once again: If you are working interactively, you could see for yourself that only three labels are suggested the first time around and move immediately to asking for more. The point about using wordcount() with a local macro result is allowing such choice to be automated.

2.4 Further remarks

The aim of nicelabels is not to repeat, still less to replace, what is already easy in Stata, or to satisfy all needs. Thus, if quantiles are being shown, it may be that labels 0.5, 0.25, 0.75, 0.125, 0.375, 0.625, 0.875, etc., appeal for a probability scale as corresponding to median, quartiles, octiles, and so forth. These labels are easily produced either by spelling them out or by using step sizes such as 0.25 or 0.125. Those labels are not nice in Heckbert’s sense, but they do have some statistical appeal. The same issue arises with a percent scale from 0 to 100 whenever labels like 25, 50, and 75 seem desirable. Even more generally, if you know a good step size, it will often be easiest to specify it directly.

Consider, for example, a graph with two years’ worth of monthly data and a monthly date on the X axis. nicelabels has no special understanding of time variables and will just suggest steps of 5 or 10 months. In contrast, you will find that official commands like line, tsline, and xtline will suggest tailored steps of six months, given only minimal hints through formatting the date variable with a monthly date display format (and declaring it as time variable to tsset or xtset). If you need to write code to standardize date label choices, it can help to remember that the first half-year, quarter, or month in a year yields 0 on being fed to mod(date, 2), mod(date, 4), or mod(date, 12), respectively. For more on mod(), see Cox (2007a).

Less common—but important to their users—are variables on a circular scale such as compass bearings (in degrees from North, on a scale between 0 and 360 ^◦ ) or times of day (in hours up to 24). Here useful steps are likely to be 90 or 45 ^◦ or 6 or 3 hours, not (for example) 100 or 50 ^◦ or 5 or 10 hours.

This implementation of nicelabels focuses on the ideas covered by Heckbert (1990). There is a wider literature both before and after that date. Wilkinson (2005, 95–97) and Talbot, Lin, and Hanrahan (2010) have spelled out how fully automated choice entails a delicate tradeoff between several desiderata, chiefly simplicity, coverage, granularity, and legibility. Talbot, Lin, and Hanrahan (2010) give a full survey of the problem.

3 nicelabels in principle

3.1 Syntax

• nicelabels varname] [if] [in] , local(macname) [tight nvals(#)]

• nicelabels #1 #2, local(macname) [tight nvals(#) ]

3.2 Description

nicelabels suggests axis labels that would look nice on a graph using a general scale. It can help when, for example, you want to choose the same labels for a series of graphs. Results are put in a local macro for later use.

“Nice” is a little hard to define but easier to recognize. This command follows common practice in general, and Heckbert (1990) in particular, in selecting power-of-10 multiples of 1, 2, or 5 that are equally spaced.

See Hardin (1995) for an earlier implementation in Stata of such ideas. Hardin (1995) implemented what Heckbert calls a “loose” definition of labels, while this command allows also a “tight” definition.

There are two syntaxes. In the first, the name of a numeric variable must be given. In the second, two numeric values are given, which will be interpreted as indicating minimum and maximum of an axis range. Those two values can be given in any order.

3.3 Options

local(macname) inserts the specification of labels in local macro macname within the calling program’s space. Hence, that macro will be accessible after nicelabels has finished. This is helpful for later use with graph twoway or other graphics commands. local() is required.

tight tends to pull in as compared with the default and so not suggest labels beyond the minimum or maximum. This option may often be combined with the nvals() option (see below).

nvals(#) suggests the number of values to be labeled. The default is nvals(5). Most commonly, you may wish to suggest more values, say, nvals(10). As said, this is a suggestion, not an instruction.

4 mylabels in practice

As explained in the introduction, graph offers special support for logarithmic scales. That leaves the question of how to support any other nonlinear scales wide open. For example, I make occasional use of square root, cube root, reciprocal, logit, folded root, neglog, and asinh scales, to mention only seven transformations, as well as various quantile (inverse cumulative distribution) scales. Even as a personal list, that is not complete, and others could add yet other scales. The prospect of a separate command or function for each possibility, or even the most common or important according to someone’s judgment, is daunting to users and programmers alike.

A better idea, explicit in Royston (1996) in a Stata context, is to expect users to calculate what numbers they want to show and to focus on the question of what axis labels should be shown whenever such numbers are graphed. This is what mylabels offers. A defense of the command name is that a bland name mentioning labels might be hard to find in a search.

For a first example, we use auto.dta again. As commonly remarked, miles per gallon, although a conventional measurement of car performance in the United States, Britain, and some other countries, is mechanically the wrong way round for relating to weight. The reciprocal, gallons per mile, is worth examining. As a matter of convenience, we multiply by 1,000. The calculation is easy, but the harder bit is labeling axes in terms of the original measurements. (Other way round, if gallons per 1,000 miles appeals as a natural scale, then labeling will not be an issue.)

Figure 5 is the result.

Figure 5.

Gallons per 1,000 miles versus weight, but labeled in terms of miles per gallon using mylabels

For mylabels, there are three essentials.

The labels you want to see: Often, but not necessarily, such labels are specified as numlists. We have already seen examples of the step notation, used just now for 15(5)40. More information on allowed notation is given at help numlist.

The scale you are working on: Here the @ character is a placeholder for the variable in question. You do not need to have a particular variable in mind, or you could be working out good labels that should be useful with several similar variables. Here you are saying that you want 15 20 25 30 35 40 as labels, but in each case the value being plotted is 1,000 divided by each of those.

A place to put the specification: As with nicelabels, mylabels does display the syntax for your desired labels (as text) and where graph should put them, but the command insists on a local macro name to encourage good coding practices.

Although it is not so often wanted, mylabels has a sister command, myticks, to place ticks on an axis. Axis ticks can help in conveying a sense of how far an original scale is being stretched or squeezed when transformed, given that values are shown in the same space.

Transformations do not have to be nonlinear to be useful. A large group of linear transformations concerns mappings between different units of measurement, including simple scalings such as between proportions from 0 and 1 and percents from 0 to 100. The next example takes data for U.S. cities on average temperatures in Fahrenheit but shows labels on a Celsius scale. Recall that Fahrenheit temperatures F and Celsius temperatures C are related by F = 32 + (9/5)C. After a quick look at summarize results and some rough calculations, I decided on the labels I wanted to see. The result of the last graph is shown in figure 6.

Figure 6.

July and January temperatures for various U.S. cities. The original data were on Fahrenheit scale, but mylabels is used to show selected labels in Celsius.

Fortuitously, but fortunately, the aspect ratio is about right, namely, that these cities vary much more in January temperature than in July temperature. The ratio of ranges is matched roughly by the aspect ratio of the graph.

Naturally, you could just calculate new variables holding Celsius values. The point is that you do not have to do that. For example, you might have many variables on the Fahrenheit scale, and holding two versions of each variable might seem a little cluttered in that case.

For our next example, let’s look at the ln_wage variable in nlswork.dta. As its name implies, this is already on a natural logarithm scale. A spikeplot can be interesting as a way of checking on the fine structure of a distribution, but in turn it can benefit from a root scale for frequencies to pull in long spikes and pull out short spikes. See Cox (2012, 2021b) and references given therein if you want more discussion of root scales. Wilke (2019) is unusual among graphics books in giving root scales any particular attention.

So we want to use mylabels in two ways—to show the raw scale for a variable already logged and to show the original scale for a variable we are going to show as square roots.

The result is shown in figure 7.

Figure 7.

Spikeplot of wage on logarithmic scale with frequencies on a root scale. See text for how mylabels was used to get the axis labels.

mylabels can be used to add text systematically to axis labels, whether as a prefix or a suffix. Common applications include percent signs, currency symbols, and units of measurement. Let’s look at percent of older people (meaning aged 65 or older) in the U.S. census data for 1980.

Suppose first you want to show “%” explicitly by each label. Precedents include Robbins (2013, 188, 250, 278, 318), Knaflic (2015, 1, 48f, 51, 59, 81f, 156, 209f, 228ff, 238f), Koponen and Hildén (2019, 22, 64, 77, 84, 94, 101, 107, 185, 190, 193ff, 206, 209, 214ff), Wilke (2019, 29, 34, 69, 101f, 104, 107, 139ff, 179, 184f, 234ff, 258f, 261), Tufte (2020, 107), and Gelman, Hill, and Vehtari (2021, 4, 29f, 94, 96, 114, 126f, 166, 292, 467f). The excess of zeal in citation will be explained shortly.

mylabels will let you do this. Here, as an easy twist, we first use nicelabels to get the labels and then mylabels to add a “%” suffix.

Note the way the local macro is just passed from command to command, being modified or just used according to need.

Figure 8 is the result.

Figure 8.

Percent 65 and older and median age for 50 U.S. states in 1980. mylabels was used to add the percent sign to each y-axis label.

There is a question of taste here. Simply, if you think that adding a percent sign to every label is repetitive clutter, then do not do that. The point of multiplying citations just now was to underline that some excellent authors often do this. Do make your own choice. You might prefer to explain measurement units in an axis title or text caption, if they need explanation at all.

There is a compromise, amply exemplified by Wong (2010, 24f, 50f, 58ff, 64f, 69, 100, 102, 107, 111, 115, 117, 119, 126, 128ff, 141) and Koponen and Hildén (2019, 98f, 181f), which is to add a prefix or a suffix to one label only, say, the first or last on an axis. mylabels has options firstonly and lastonly, added in this 2022 version of the command.

5 mylabels in principle

5.1 Syntax

mylabels lbllist, local(macname) [myscale(transformation_syntax) format(format) clean prefix(text) suffix(text) firstonly lastonly ]

myticks ticklist , local( macname ) [myscale( transformation_syntax ) ]

5.2 Description

mylabels and myticks generate axis labels and ticks on specified scales. Their uses are best explained by examples, as below. Note that the label list, lbllist, and tick list, ticklist, will be expanded if presented as legal numlists and left as specified otherwise.

5.3 Remarks

You draw a graph, and one axis is on a transformed square-root scale. You wish the axis labels to show untransformed values. For some values, this is easy; for example, ylabel(0 1 2 "4" 3 "9" 4 "16" 5 "25") says to use "4" as a label for 2, and so forth. For other values or other transformations, the conversion may be more difficult to do in your head, so a dedicated utility is helpful.

The idea behind mylabels is that you feed it the labels (usually, but not necessarily, numeric labels) that you want shown and the transformation being used. It will then place the appropriate specification in a local macro that you name. You may then use that local macro as part of a later graph command.

Suppose you want labels 0 1 4 9 16 25 36 49, and your data are square roots of these. Your call is mylabels 0 1 4 9 16 25 36 49, myscale(sqrt(@)) local(labels). Or suppose you want percents shown, and your data are proportions 0–1. Your call is mylabels 0(25)100, myscale(@/100) local(labels). Think of this as follows: My graph labels that I want are 0(25)100, but my data scale is that of the labels divided by 100.

A similar idea may be used for axis ticks.

Further examples are given in the help file.

5.4 Options

local(macname) inserts the option specification in local macro macname within the calling program’s space. Hence, that macro will be accessible after mylabels or myticks has finished. This is helpful for later use with graph or other graphics commands. local() is required.

myscale(transformation_syntax) specifies the transformation used to produce the data you have. Stata syntax should be used with @ as a placeholder for the original value. To show proportions as percents, specify myscale(@/100). If no transformation is being used, you may specify myscale(@), but that is also the default.

format(format) specifies a format controlling the labels. This is an occasionally specified option. Its main use is to enforce the presentation of leading zeros.

clean specifies a minimal format eliding trailing zeros and decimal points (whether periods [stops] or commas). This option is most often used together with format(). Thus, by itself format(%03.2f) would render 0(0.25)1 as 0.00 0.25 0.50 0.75 1.00, but clean reduces it to 0 0.25 0.5 0.75 1. Do not use this option with integer labels such as 10(10)40.

prefix(text) specifies text to be prepended to all axis labels. Specify any blank spaces within " ".

suffix(text) specifies text to be appended to all axis labels. Specify any blank spaces within " ".

firstonly and lastonly specify that any prefix or suffix should be attached to the first or last label only.

6 Conclusion

In graphics, like much else, the devil can lie in the details. Many graphs are for one purpose and can be optimized on the fly to match your personal taste or some compelling prescription. Other graphs may need to follow some overarching choices, worked out systematically. nicelabels, mylabels, and myticks can help either way, but particularly if you are writing scripts to automate graph choices across a range of broadly similar graphs. These commands depend on the convenience of local macros to hold the information produced.

Some other tips and tricks in similar territory can be found in Cox (2005b, 2007b, 2008a) and Cox and Wiggins (2019).

8 Programs and supplemental materials

Supplemental Material, sj-zip-1-stj-10.1177_1536867X221141058 - Speaking Stata: Automating axis labels: Nice numbers and transformed scales

Supplemental Material, sj-zip-1-stj-10.1177_1536867X221141058 for Speaking Stata: Automating axis labels: Nice numbers and transformed scales by Nicholas J. Cox in The Stata Journal