Stata 15 help for axis_label_options

[G-3] axis_label_options -- Options for specifying axis labels


axis_label_options are a subset of axis_options; see [G-3] axis_options. axis_label_options control the placement and the look of ticks and labels on an axis.

axis_label_options Description ------------------------------------------------------------------------- {y|x|t|z}label(rule_or_values) major ticks plus labels {y|x|t|z}tick(rule_or_values) major ticks only {y|x|t|z}mlabel(rule_or_values) minor ticks plus labels {y|x|t|z}mtick(rule_or_values) minor ticks only ------------------------------------------------------------------------- The above options are merged-explicit; see [G-4] concept:repeated options.

where rule_or_values is defined as

[rule] [numlist ["label" [numlist ["label" [...]]]]] [, suboptions]

Either rule or numlist must be specified, and both may be specified.

rule Example Description ---------------------------------------------------------------------- ## #6 approximately 6 nice values ### ##10 10-1=9 values between major ticks; allowed with mlabel() and mtick() only #(#)# -4(.5)3 specified range: -4 to 3 in steps of .5 minmax minmax minimum and maximum values none none label no values . . skip the rule ----------------------------------------------------------------------

where numlist is as described in [U] 11.1.8 numlist.

tlabel(), ttick(), tmlabel(), and tmtick() also accept a datelist and an extra type of rule

rule Example Description ---------------------------------------------------------------------- date(#)date 1999m1(1)1999m12 specified date range: each month assuming the axis has the %tm format ----------------------------------------------------------------------

where date and datelist may contain dates, provided that the t (time) axis has a date format; see [U] 11.1.9 datelist.

suboptions Description ------------------------------------------------------------------------- axis(#) which axis, 1 < # < 9 add combine options [no]ticks suppress ticks [no]labels suppress labels valuelabel label values using first variable's value label format(%fmt) format values per %fmt angle(anglestyle) angle the labels alternate offset adjacent labels norescale do not rescale the axis

tstyle(tickstyle) labels and ticks: overall style

labgap(relativesize) labels: margin between tick and label labstyle(textstyle) labels: overall style labsize(textsizestyle) labels: size of text labcolor(colorstyle) labels: color and opacity of text

tlength(relativesize) ticks: length tposition(outside|crossing| inside) ticks: position/direction tlstyle(linestyle) ticks: linestyle of tlwidth(linewidthstyle) ticks: thickness of line tlcolor(colorstyle) ticks: color and opacity of line

custom tick- and label-rendition options apply only to these labels

[no]grid grid: include [no]gmin grid: grid line at minimum [no]gmax grid: grid line at maximum gstyle(gridstyle) grid: overall style [no]gextend grid: extend into plot region margin glstyle(linestyle) grid: linestyle of glwidth(linewidthstyle) grid: thickness of line glcolor(colorstyle) grid: color and opacity of line glpattern(linepatternstyle) grid: line pattern of line -------------------------------------------------------------------------


axis_label_options control the placement and the look of ticks and labels on an axis.


ylabel(rule_or_values), xlabel(rule_or_values), tlabel(rule_or_values), and zlabel(rule_or_values) specify the major values to be labeled and ticked along the axis. For instance, to label the values 0, 5, 10, ..., 25 along the x axis, specify xlabel(0(5)25). If the t axis has the %tm format, tlabel(1999m1(1)1999m12) will label all the months in 1999.

ytick(rule_or_values), xtick(rule_or_values), ttick(rule_or_values), and ztick(rule_or_values) specify the major values to be ticked but not labeled along the axis. For instance, to tick the values 0, 5, 10, ..., 25 along the x axis, specify xtick(0(5)25). Specify ttick(1999m1(1)1999m12) to place ticks for each month in the year 1999.

ymlabel(rule_or_values), xmlabel(rule_or_values), tmlabel(rule_or_values), and zmlabel(rule_or_values) specify minor values to be labeled and ticked along the axis.

ymtick(rule_or_values), xmtick(rule_or_values), tmtick(rule_or_values), and zmtick(rule_or_values) specify minor values to be ticked along the axis.

zlabel(rule_or_values), ztick(rule_or_values), zmlabel(rule_or_values), and zmtick(rule_or_values); see Contour axes -- zlabel(), etc. below.


axis(#) specifies to which scale this axis belongs and is specified when dealing with multiple x (t) or y axes; see [G-3] axis_choice_options.

add specifies what is to be added to any xlabel(), ylabel(), xtick(), ..., or ymtick() option previously specified. Labels or ticks are added to any default labels or ticks or to any labels or ticks specified in previous xlabel(), ylabel(), xtick(), ..., or ymtick() options. Only value specifications are added; rule specifications always replace any existing rule. See Interpretation of repeated options below.

noticks and ticks suppress/force the drawing of ticks. ticks is the usual default, so noticks makes {y|x}label() and {y|x}mlabel() display the labels only.

nolabels and labels suppress/force the display of the labels. labels is the usual default, so nolabels turns {y|x}label() into {y|x}tick() and {y|x}mlabel() into {y|x}mtick(). Why anyone would want to do this is difficult to imagine.

valuelabel specifies that values should be mapped through the first y variable's value label (y*() options) or the x variable's value label (x*() options). Consider the command scatter yvar xvar and assume that xvar has been previously given a value label:

. label define cat 1 "Low" 2 "Med" 3 "Hi" . label values xvar cat


. scatter yvar xvar, xlabel(1 2 3, valuelabel)

would, rather than putting the numbers 1, 2, and 3, put the words Low, Med, and Hi on the x axis. It would have the same effect as

scatter yvar xvar, xlabel(1 "Low" 2 "Med" 3 "Hi")

format(%fmt) specifies how numeric values on the axes should be formatted. The default format() is obtained from the variables specified with the graph command, which for ylabel(), ytick(), ymlabel(), and ymtick() usually means the first y variable, and for xlabel(), ..., xmtick(), means the x variable. For instance, in

. scatter y1var y2var xvar

the default format for the y axis would be y1var's format, and the default for the x axis would be xvar's format.

You may specify the format() suboption (or any suboption) without specifying values if you want the default labeling presented differently. For instance,

. scatter y1var y2var xvar, ylabel(,format(%9.2fc))

would present default labeling of the y axis, but the numbers would be formatted with the %9.2fc format. Note carefully the comma in front of format. Inside the ylabel() option, we are specifying suboptions only.

angle(anglestyle) causes the labels to be presented at an angle. See [G-4] anglestyle.

alternate causes adjacent labels to be offset from one another and is useful when many values are being labeled. For instance, rather than obtaining

----------------------------- 1.0 1.1 1.2 1.3 1.4 1.5 1.6

with alternate, you would obtain

----------------------------- 1.0 1.2 1.4 1.6 1.1 1.3 1.5

norescale specifies that the ticks or labels in the option be placed directly on the graph without rescaling the axis or associated plot region for the new values. By default, label options automatically rescale the axis and plot region to include the range of values in the new labels or ticks. norescale allows you to plot ticks or labels outside the normal bounds of an axis.

tstyle(tickstyle) specifies the overall look of ticks and labels; see [G-3] tickstyle. The options documented below will allow you to change each attribute of a tick and its label, but the tickstyle specifies the starting point.

You need not specify tstyle() just because there is something you want to change about the look of ticks or labels. You specify tstyle() when another style exists that is exactly what you desire or when another style would allow you to specify fewer changes to obtain what you want.

labgap(relativesize), labstyle(textstyle), labsize(textsizestyle), and labcolor(colorstyle) specify details about how the labels are presented. See [G-4] relativesize, [G-4] textstyle, [G-4] textsizestyle, and [G-4] colorstyle.

tlength(relativesize) specifies the overall length of the ticks; see [G-4] relativesize.

tposition(outside|crossing|inside) specifies whether the ticks are to extend outside (from the axis out, the usual default), crossing (crossing the axis line, extending in and out), or inside (from the axis into the plot region).

tlstyle(linestyle), tlwidth(linewidthstyle), and tlcolor(colorstyle) specify other details about the look of the ticks. See [G-4] linestyle, [G-4] linewidthstyle, and [G-4] colorstyle. Ticks are just lines. See [G-4] concept: lines for more information.

custom specifies that the label-rendition suboptions, the tick-rendition options, and the angle() option apply only to the labels added on the current {y|x[m]t}label() or {y|x|t}mlabel() option, rather than being applied to all major or minor labels on the axis. Customizable suboptions are tstyle(), labgap(), labstyle(), labsize(), labcolor(), tlength(), tposition(), tlstyle(), tlwidth(), and tlcolor().

custom is usually combined with suboption add to emphasize points on the axis by extending the length of the tick, changing the color or size of the label, or otherwise changing the look of the custom labels or ticks.

grid and nogrid specify whether grid lines are to be drawn across the plot region in addition to whatever else is specified in the {y|x}[m]label() or {y|x}[m]tick() option in which grid or nogrid appears. Typically, nogrid is the default, and grid is the option for all except ylabel(), where things are reversed and grid is the default and nogrid is the option. (Which is the default and which is the option is controlled by the scheme; see [G-4] schemes intro.)

For instance, specifying option

ylabel(, nogrid)

would suppress the grid lines in the y direction and specifying

xlabel(, grid)

would add them in the x. Specifying

xlabel(0(1)10, grid)

would place major labels, major ticks, and grid lines at x = 0, 1, 2, ..., 10.

[no]gmin and [no]gmax are relevant only if grid is in effect (because grid is the default and nogrid was not specified or because grid was specified). [no]gmin and [no]gmax specify whether grid lines are to be drawn at the minimum and maximum values. Consider

. scatter yvar xvar, xlabel(0(1)10, grid)

Clearly the values 0, 1, ..., 10 are to be ticked and labeled, and clearly, grid lines should be drawn at 1, 2, ..., 9; but should grid lines be drawn at 0 and 10? If 0 and 10 are at the edge of the plot region, you probably do not want grid lines there. They will be too close to the axis and border of the graph.

What you want will differ from graph to graph, so the graph command tries to be smart, meaning that neither gmin nor nogmin (and neither gmax nor nogmax) is the default: The default is for graph to decide which looks best; the options force the decision one way or the other.

If graph decided to suppress the grids at the extremes and you wanted them, you could type

. scatter yvar xvar, xlabel(0(1)10, grid gmin gmax)

gstyle(gridstyle) specifies the overall style of the grid lines, including whether the lines extend beyond the plot region and into the plot region's margins, along with the style, color, width, and pattern of the lines themselves. The options that follow allow you to change each attribute, but the gridstyle provides the starting point. See [G-4] gridstyle.

You need not specify gstyle() just because there is something you want to change. You specify gstyle() when another style exists that is exactly what you desire or when another style would allow you to specify fewer changes to obtain what you want.

gextend and nogextend specify whether the grid lines should extend beyond the plot region and pass through the plot region's margins; see [G-3] region_options. The default is determined by the gstyle() and scheme, but usually, nogextend is the default and gextend is the option.

glstyle(linestyle), glwidth(linewidthstyle), glcolor(colorstyle), and glpattern(linepatternstyle) specify other details about the look of the grid. See [G-4] linestyle, [G-4] linewidthstyle, [G-4] colorstyle, and [G-4] linepatternstyle. Grids are just lines. See [G-4] concept lines for more information. Of these options, glpattern() is of particular interest because, with it, you can make the grid lines dashed.


axis_label_options are a subset of axis_options; see [G-3] axis_options for an overview. The other appearance options are

axis_scale_options (see [G-3] axis_scale_options)

axis_title_options (see [G-3] axis_title_options)

Remarks are presented under the following headings:

Default labeling and ticking Controlling the labeling and ticking Adding extra ticks Adding minor labels and ticks Adding grid lines Suppressing grid lines Substituting text for labels Contour axes -- zlabel(), etc.

Appendix: Details of syntax Suboptions without rules, numlists, or labels Rules Rules and numlists Rules and numlists and labels Interpretation of repeated options

Default labeling and ticking

By default, approximately five values are labeled and ticked on each axis. For example, in

. sysuse auto

. scatter mpg weight (click to run)

four values are labeled on each axis because choosing five would have required widening the scale too much.

Controlling the labeling and ticking

We would obtain the same results as we did in the above example if we typed

. scatter mpg weight, ylabel(#5) xlabel(#5)

Options ylabel() and xlabel() specify the values to be labeled and ticked, and #5 specifies that Stata choose approximately five values for us. If we wanted many values labeled, we might type

. scatter mpg weight, ylabel(#10) xlabel(#10) (click to run)

As with #5, #10 was not taken too seriously; we obtained seven labels on the y axis and eight on the x axis.

We can also specify precisely the values we want labeled by specifying #(#)# or by specifying a list of numbers:

. scatter mpg weight, ylabel(10(5)45) xlabel(1500 2000 3000 4000 4500 5000) (click to run)

In option ylabel(), we specified the rule 10(5)45, which means to label 10 to 45 in steps of 5. In option xlabel(), we typed out the values to be labeled.

Adding extra ticks

Options ylabel() and xlabel() draw ticks plus labels. Options ytick() and xtick() draw ticks only, so you can do things such as

. scatter mpg weight, ytick(#10) xtick(#15) (click to run)

Of course, as with ylabel() and xlabel(), you can specify the exact values you want ticked.

Adding minor labels and ticks

Minor ticks and minor labels are smaller than regular ticks and regular labels. Options ymlabel() and xmlabel() allow you to place minor ticks with labels, and ymtick() and xmtick() allow you to place minor ticks without labels. When using minor ticks and labels, in addition to the usual syntax of #5 to mean approximately 5 values, 10(5)45 to mean 10 to 45 in steps of 5, and a list of numbers, there is an additional syntax: ##5. ##5 means that each major interval is divided into 5 minor intervals.

The graph below is intended more for demonstration than as an example of a good-looking graph:

. scatter mpg weight, ymlabel(##5) xmtick(##10) (click to run)

##5 means four ticks, and ##10 means nine ticks because most people think in reciprocals they say to themselves, "I want to tick the fourths so I want 4 ticks between," or, "I want to tick the tenths so I want 10 ticks between". They think incorrectly. They should think that if they want fourths, they want 4-1=3 ticks between, or if they want tenths, they want 10-1=9 ticks between. Stata subtracts one so that they can think -- and correctly -- when they want fourths that they want ##4 ticks between and that when they want tenths they want ##10 ticks between.

For ### rules to work, the major ticks must be evenly spaced. This format is guaranteed only when the major ticks or labels are specified using the #(#)# rule. The ### rule also works in almost all cases, the exception being daily data where the date variable is specified in the %td format. Here "nice" daily labels often do not have a consistent number of days between the ticks and thus the space between each major tick cannot be evenly divided. If the major ticks are not evenly spaced, the ### rule does not produce any minor ticks.

Adding grid lines

To obtain grid lines, specify the grid suboption of ylabel(), xlabel(), ymlabel(), or xmlabel(). grid specifies that, in addition to whatever else the option would normally do, grid lines be drawn at the same values. In the example below,

. sysuse uslifeexp, clear

. line le year, xlabel(,grid) (click to run)

we specify xlabel(,grid), omitting any mention of the specific values to use. Thus xlabel() did what it does ordinarily (labeled approximately five nice values), and it drew grid lines at those same values.

Of course, we could have specified the values to be labeled and gridded:

. line le year, xlabel(#10, grid)

. line le year, xlabel(1900(10)2000, grid)

. line le year, xlabel(1900 1918 1940(20)2000, grid)

The grid suboption is usually specified with xlabel() (and with ylabel() if, given the scheme, grid is not the default), but it may be specified with any of the axis_label_options. In the example below, we "borrow" ymtick() and xmtick(), specify grid to make them draw grids, and specify style(none) to make the ticks themselves invisible:

. sysuse auto, clear

. scatter mpg weight, ymtick(#20, grid tstyle(none)) xmtick(#20, grid tstyle(none)) (click to run)

If you look carefully at the graph above, you will find that no grid line was drawn at x=5,000. Stata suppresses grid lines when they get too close to the axes or borders of the graph. If you want to force Stata to draw them anyway, you can specify the gmin and gmax options:

. scatter mpg weight, ymtick(#20, grid tstyle(none)) xmtick(#20, grid tstyle(none) gmax)

Suppressing grid lines

Some commands, and option ylabel(), usually draw grid lines by default. For instance, in the following, results are the same as if you specified ylabel(,grid):

. sysuse auto, clear

. scatter mpg weight, by(foreign) (click to run)

To suppress the grid lines, specify ylabel(,nogrid):

. scatter mpg weight, by(foreign) ylabel(,nogrid)

Substituting text for labels

In addition to specifying explicitly the values to be labeled by specifying things such as ylabel(10(10)50) or ylabel(10 20 30 40 50), you can specify text to be substituted for the label. If you type

. graph ..., ...ylabel(10 20 30 "mean" 40 50)

The values 10, 20, ..., 50 will be labeled, just as you would expect, but for the middle value, rather than the text "30" appearing, the text "mean" (without the quotes) would appear.

In the advanced example, below we specify

xlabel(1 "J" 2 "F" 3 "M" 4 "A" 5 "M" 6 "J" 7 "J" 8 "A" 9 "S" 10 "O" 11 "N" 12 "D")

so that rather than seeing the numbers 1, 2, ..., 12 (which are month numbers), we see J, F, ..., D; and we specify

ylabel(12321 "12,321 (mean)", axis(2) angle(0))

so that we label 12321 but, rather than seeing 12321, we see "12,321 (mean)". The axis(2) option puts the label on the second y axis (see [G-3] axis_choice_options) and angle(0) makes the text appear horizontally rather than vertically (see Options above):

. sysuse sp500, clear

. generate month = month(date)

. sort month

. by month: egen lo = min(volume)

. by month: egen hi = max(volume)

. format lo hi %10.0gc

. summarize volume

Variable | Obs Mean Std. Dev. Min Max -------------+-------------------------------------------------------- volume | 248 12320.68 2585.929 4103 23308.3

. by month: keep if _n==_N

. twoway rcap lo hi month, xlabel(1 "J" 2 "F" 3 "M" 4 "A" 5 "M" 6 "J" 7 "J" 8 "A" 9 "S" 10 "O" 11 "N" 12 "D") xtitle("Month of 2001") ytitle("High and Low Volume") yaxis(1 2) ylabel(12321 "12,321 (mean)", axis(2) angle(0)) ytitle("", axis(2)) yline(12321, lstyle(foreground)) msize(*2) title("Volume of the S&P 500", margin(b+2.5)) note("Source: Yahoo!Finance and Commodity Systems Inc.") (click to run)

Contour axes -- zlabel(), etc.

The zlabel(), ztick(), zmlabel(), and zmtick() options are unusual in that they apply not to axes on the plot region, but to the axis that shows the scale of a contour legend. They have effect only when the graph includes a twoway contour plot; see [G-2] graph twoway contour. In all other respects, they act like the x*, y*, and t* options.

For an example using zlabel(), see Controlling the number of contours and their values in [G-2] graph twoway contour.

The options associated with grids have no effect when specified on contour axes.

Appendix: Details of syntax

Suboptions without rules, numlists, or labels

What may appear in each of the options {y|x}{label|tick|mlabel|mtick}() is a rule or numlist followed by suboptions:

[rule] [numlist ["label" [numlist ["label" [...]]]]] [, suboptions]

rule, numlist, and label are optional. If you remove those, you are left with

, suboptions

That is, the options {y|x}{label|tick|mlabel|mtick}() may be specified with just suboptions and, in fact, they are often specified that way. If you want default labeling of the y axis and x axis, but you want grid lines in the x direction as well as the y, specify

. scatter yvar xvar, xlabel(,grid)

When you do not specify the first part -- the rule, numlist, and label -- you are saying that you do not want that part to change. You are saying that you merely wish to change how the rule, numlist, and label are displayed.

Of course, you may specify more than one suboption. You might type

. scatter yvar xvar, xlabel(,grid format(%9.2f))

if, in addition to grid lines, you wanted the numbers presented on the x axis to be presented in a %9.2f format.


What may appear in each of the axis-label options is a rule or numlist

[rule] [numlist ["label" [numlist ["label" [...]]]]] [, suboptions]

where either rule or numlist must be specified and both may be specified. Let us ignore the "label" part right now. Then the above simplifies to

[rule] [numlist] [, suboptions]

where rule or numlist must be specified, both may be specified, and most often you will simply specify the rule, which may be any of the following:

rule Example Description ---------------------------------------------------------------------- ## #6 6 nice values ### ##10 10-1=9 values between major ticks; allowed with mlabel() and mtick() only #(#)# -4(.5)3 specified range: -4 to 3 in steps of .5 minmax minmax minimum and maximum values none none label no values . . skip the rule ----------------------------------------------------------------------

The most commonly specified rules are ## and ###.

Specifying ## says to choose # nice values. Specifying #5 says to choose five nice values, #6 means to choose six, and so on. If you specify ylabel(#5), then five values will be labeled (on the y axis). If you also specify ymtick(#10), then 10 minor ticks will also be placed on the axis. Actually, ylabel(#5) and ymtick(#10) will result in approximately five labels and 10 minor ticks because the choose-a-nice-number routine will change your choice a little if, in its opinion, that would yield a nicer overall result. You may not agree with the routine about what is nice, and then the #(#)# rule will let you specify exactly what you want, assuming that you want evenly spaced labels and numbers.

### is allowed only with the {y|x}mlabel() and {y|x}mtick() options -- the options that result in minor ticks. ### says to put #-1 minor ticks between the major ticks. ##5 would put four, and ##10 would put nine. Here # is taken seriously, at least after subtraction, and you are given exactly what you request.

#(#)# can be used with major or minor labels and ticks. This rule says to label the first number specified, increment by the second number, and keep labeling, as long as the result is less than or equal to the last number specified. ylabel(1(1)10) would label (and tick) the values 1, 2, ..., 10. ymtick(1(.5)10) would put minor ticks at 1, 1.5, 2, 2.5, ..., 10. It would be perfectly okay to specify both of those options. When specifying rules, minor ticks and labels will check what is specified for major ticks and labels and remove the intersection so as not to overprint. The results will be the same as if you specified ymtick(1.5(1)9.5).

The rule minmax specifies that you want the minimum and maximum. ylabel(minmax) would label only the minimum and maximum.

Rule none means precisely that: the rule that results in no labels and no ticks.

Rule . makes sense only when add is specified, although it is allowed at other times, and then . means the same as none.

Rules and numlists

After the rule -- or instead of it -- you can specify a numlist. A numlist is a list of numbers, for instance, "1 2 5 7" (without the quotes) or "3/9" (without the quotes). Other shorthands are allowed (see [U] 11.1.8 numlist), and in fact, one of numlist's syntaxes looks just like a rule: #(#)#. It has the same meaning, too.

There is, however, a subtle distinction between, for example,

ylabel(1(1)10) (a rule) and ylabel(none 1(1)10) (a numlist)

Rules are more efficient. Visually, however, there is no difference.

Use numlists when the values you wish to label or to tick are unequally spaced,

ylabel(none 1 2 5 7)

or when there is one or more extra values you want to label or to tick:

ylabel(1(1)10 3.5 7.5)

Rules and numlists and labels

Numlists serve an additional purpose -- you can specify text that is to be substituted for the value to be labeled. For instance,

ylabel(1(1)10 3.5 "Low" 7.5 "Hi")

says to label 1, 2, ..., 10 (that is the rule part) and to label the special values 3.5 and 7.5. Rather than actually printing "3.5" and "7.5" next to the ticks at 3.5 and 7.5, however, graph will instead print the words "Low" and "Hi".

Interpretation of repeated options

Each of the axis-label options may be specified more than once in the same command. If you do that and you do not specify suboption add, the rightmost of each is honored. If you specify suboption add, then the option just specified and the previous options are merged. add specifies that any new ticks or labels are added to any existing ticks or labels on the axis. All suboptions are rightmost; see [G-4] concept: repeated options.

© Copyright 1996–2018 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index