Stata 15 help for legend_options

[G-3] legend_options -- Options for specifying legends

Syntax

legend_options Description ------------------------------------------------------------------------- legend([contents] [location]) standard legend, contents and location plegend([contents] [location]) contourline legend, contents and location clegend([suboptions]) contour plot legend; see [G-3] clegend_option ------------------------------------------------------------------------- legend(), plegend(), and clegend() are merged-implicit; see repeated options.

where contents and location specify the contents and the location of the legends.

contents Description ------------------------------------------------------------------------- order(orderinfo) which keys appear and their order label(labelinfo) override text for a key holes(numlist) positions in legend to leave blank all generate keys for all symbols

style(legendstyle) overall style of legend cols(#) # of keys per line rows(#) or # of rows [no]colfirst "1, 2, 3" in row 1 or in column 1? [no]textfirst symbol-text or text-symbol? stack symbol/text vertically stacked rowgap(relativesize) gap between lines colgap(relativesize) gap between columns symplacement(compassdirstyle) alignment/justification of key's symbol keygap(relativesize) gap between symbol-text symysize(relativesize) height for key's symbol symxsize(relativesize) width for key's symbol textwidth(relativesize) width for key's descriptive text forcesize always respect symysize(), symxsize(), and textwidth() bmargin(marginstyle) outer margin around legend textbox_options other text characteristics title_options titles, subtitles, notes, captions region(roptions) borders and background shading ------------------------------------------------------------------------- order(), labels(), holes(), and all have no effect on plegend().

location Description ------------------------------------------------------------------------- off or on suppress or force display of legend position(clockposstyle) where legend appears ring(ringposstyle) where legend appears (detail) bplacement(compassdirstyle) placement of legend when positioned in the plotregion span "centering" of legend at(#) allowed with by() only ------------------------------------------------------------------------- See Where legends appear under Remarks below, and see Positioning of titles in [G-3] title_options for definitions of clockposstyle and ringposstyle.

orderinfo, the argument allowed by legend(order()), is defined as

{#|-} ["text" ["text" ...]]

labelinfo, the argument allowed by legend(label()), is defined as

# "text" ["text" ...]

roptions, the arguments allowed by legend(region()), include

roptions Description ------------------------------------------------------------------------- style(areastyle) overall style of region color(colorstyle) line + fill color and opacity of region fcolor(colorstyle) fill color and opacity of region lstyle(linestyle) overall style of border lcolor(colorstyle) color and opacity of border lwidth(linewidthstyle) thickness of border lpattern(linepatternstyle) border pattern (solid, dashed, etc.) lalign(linealignmentstyle) border alignment (inside, outside, center) margin(marginstyle) margin between border and contents of legend -------------------------------------------------------------------------

Description

The legend() option allows you to control the look, contents, and placement of the legend. A sample legend is

+---------------------+ | o Observed | | --- Linear fit | | --- Quadratic fit | +---------------------+

The above legend has three keys. Each key is composed of a symbol and descriptive text describing the symbol (whatever the symbol might be, be it a marker, a line, or a color swatch).

contourline and contour plots have their own legends and do not place keys in the standard legend -- legend(); see [G-2] graph twoway contourline and [G-2] graph twoway contour. contourline plots place their keys in the plegend() and contour plots place their keys in the clegend(). The plegend() is similar to the legend() and is documented here. The clegend() is documented in [G-3] clegend_option.

The legend options (more correctly suboptions) are discussed using the legend() option, but most apply equally to the plegend() option.

Options

legend(contents, location) defines the contents of the standard legend, along with how it is to look, and whether and where it is to be displayed.

plegend(contents, location) defines the contents of the contourline plot legend, along with how it is to look, and whether and where it is to be displayed.

Content suboptions for use with legend() and plegend()

order(orderinfo) specifies which keys are to appear in the legend and the order in which they are to appear.

order(# # ...) is the usual syntax. order(1 2 3) would specify that key 1 is to appear first in the legend, followed by key 2, followed by key 3. order(1 2 3) is the default if there are three keys. If there were four keys, order(1 2 3 4) would be the default, and so on. If there were four keys and you specified order(1 2 3), the fourth key would not appear in the legend. If you specified order(2 1 3), first key 2 would appear, followed by key 1, followed by key 3.

A dash specifies that text be inserted into the legend. For instance, order(1 2 - "text" 3) specifies key 1 appear first, followed by key 2, followed by the text text, followed by key 3. Imagine that the default key were

+-------------------+ | o Observed | | --- Linear | | --- Quadratic | +-------------------+

Specifying order(1 - "Predicted:" 2 3) would produce

+-------------------+ | o Observed | | Predicted: | | --- Linear | | --- Quadratic | +-------------------+

and specifying order(1 - " " "Predicted:" 2 3) would produce

+-------------------+ | o Observed | | | | Predicted: | | --- Linear | | --- Quadratic | +-------------------+

Note carefully the specification of a blank for the first line of the text insertion; we typed " " and not "". Typing "" would insert nothing.

You may also specify quoted text after # to override the descriptive text associated with a symbol. Specifying order(1 "Observed 1992" - " " "Predicted" 2 3) would change "Observed" in the above to "Observed 1992". It is considered better style, however, to use the label() suboption to relabel symbols.

order() has no effect on plegend().

label(# "text" ["text" ...]) specifies the descriptive text to be displayed next to the #th key. Multiline text is allowed. Specifying label(1 "Observed 1992") would change the descriptive text associated with the first key to be "Observed 1992". Specifying label(1 "Observed" "1992-1993") would change the descriptive text to contain two lines, "Observed" followed by "1992-1993".

The descriptive text of only one key may be changed per label() suboption. Specify multiple label() suboptions when you wish to change the text of multiple keys.

label() has no effect on plegend().

holes(numlist) specifies where gaps appear in the presentation of the keys. holes() has an effect only if the keys are being presented in more than one row and more than one column.

Consider a case in which the default key is

+-----------------------------------------------+ | o Observed --- Linear fit | | --- Quadratic fit | +-----------------------------------------------+

Specifying holes(2) would result in

+-----------------------------------------------+ | o Observed | | --- Linear fit --- Quadratic fit | +-----------------------------------------------+

Here holes(2) would have the same effect as specifying order(1 - " " 2 3), and as a matter of fact, there is always an order() command that will achieve the same result as holes(). order() has the added advantage of working in all cases.

holes() has no effect on plegend().

all specifies that keys be generated for all the plots of the graph, even when the same symbol is repeated. The default is to generate keys only when the symbols are different, which is determined by the overall style. For example, in

. scatter ylow yhigh x, pstyle(p1 p1) || ...

there would be only one key generated for the variables ylow and yhigh because they share the style p1. That single key's descriptive text would indicate that the symbol corresponded to both variables. If, on the other hand, you typed

. scatter ylow yhigh x, pstyle(p1 p1) legend(all) || ...

then separate keys would be generated for ylow and yhigh.

In the above example, do not confuse our use of scatter's option pstyle() with legend()'s suboption legend(style()). The pstyle() option sets the overall style for the rendition of the points. legend()'s style() suboption is documented directly below.

all has no effect on plegend().

style(legendstyle) specifies the overall look of the legend -- whether it is presented horizontally or vertically, how many keys appear across the legend if it is presented horizontally, etc. The options listed below allow you to change each attribute of the legend, but style() is the starting point.

You need not specify style() just because there is something you want to change. You specify style() 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.

See [G-4] legendstyle for a list of available legend styles.

cols(#) and rows(#) are alternatives; they specify in how many columns or rows (lines) the keys are to be presented. The usual default is cols(2), which means that legends are to take two columns:

+-----------------------------------------------+ | o Observed --- Linear fit | | --- Quadratic fit | +-----------------------------------------------+

cols(1) would force a vertical arrangement,

+----------------------+ | o Observed | | --- Linear fit | | --- Quadratic fit | +----------------------+

and rows(1) would force a horizontal arrangement:

+---------------------------------------------------------------+ | o Observed --- Linear fit --- Quadratic fit | +---------------------------------------------------------------+

colfirst and nocolfirst determine whether, when the keys are presented in multiple columns, keys are to read down or to read across, resulting in this

+--------------------------------------------------+ | o Observed --- Quadratic fit | | --- Linear fit | +--------------------------------------------------+

or this

+--------------------------------------------------+ | o Observed --- Linear fit | | --- Quadratic fit | +--------------------------------------------------+

The usual default is nocolfirst, so colfirst is the option.

textfirst and notextfirst specify whether the keys are to be presented as descriptive text followed by the symbol or the symbol followed by descriptive text. The usual default is notextfirst, so textfirst is the option. textfirst produces keys that look like this

+--------------------------------------------------+ | Observed o Linear fit --- | | Quadratic fit --- | +--------------------------------------------------+

and textfirst cols(1) produces

+---------------------+ | Observed o | | Linear fit --- | | Quadratic fit --- | +---------------------+

stack specifies that the symbol-text be presented vertically with the symbol on top (or with the descriptive text on top if textfirst is also specified). legend(stack) would produce

+-----------------------------------------------+ | o ---------------- | | Observed Linear fit | | ----------------- | | Quadratic fit | +-----------------------------------------------+

legend(stack symplacement(left) symxsize(13) forcesize rowgap(4)) would produce

+-----------------------------------------------+ | o --- | | Observed Linear fit | | | | --- | | Quadratic fit | +-----------------------------------------------+

stack tends to be used to produce single-column keys. legend(cols(1) stack symplacement(left) symxsize(13) forcesize rowgap(4)) produces

+-----------------+ | o | | Observed | | | | --- | | Linear fit | | | | --- | | Quadratic fit | +-----------------+

This is the real use of stack: to produce narrow, vertical keys.

rowgap(relativesize) and colgap(relativesize) specify the distance between lines and the distance between columns. The defaults are rowgap(1.4) and colgap(4.9). See [G-4] relativesize.

symplacement(compassdirstyle) specifies how symbols are justified in the key. The default is symplacement(center), meaning that they are vertically and horizontally centered. The two most commonly specified alternatives are symplacement(right) (right alignment) and symplacement(left) (left alignment). See [G-4] compassdirstyle for other alignment choices.

keygap(relativesize), symysize(relativesize), symxsize(relativesize), and textwidth(relativesize) specify the height and width to be allocated for the key and the key's symbols and descriptive text:

keygap() |---|

+-----------------------------------+ --- | symbol | | descriptive text | | symysize() +-----------------------------------+ ---

|----------| |--------------------| symxsize() textwidth()

The defaults are

---------------------------------------------------------- symxsize() 13 keygap() 2 textwidth() according to longest descriptive text line symysize() according to height of font (*) ---------------------------------------------------------- (*) The size of the font is set by the textbox_option size(relativesize); see textbox_options below.

Markers are placed in the symbol area, centered according to symplacement().

Lines are placed in the symbol area vertically according to symplacement() and horizontally are drawn to length symxsize().

Color swatches fill the symysize() x symxsize() area.

See [G-4] relativesize for information on specifying relative sizes.

forcesize causes the sizes specified by symysize() and symxsize() to be respected. If forcesize is not specified, once all the symbols have been placed for all the keys, the symbol area is compressed (or expanded) to be no larger than necessary to contain the symbols.

bmargin(marginstyle) specifies the outer margin around the legend. That is, it specifies how close other things appearing near to the legend can get. Also see suboption margin() under Suboptions for use with legend(region()) below for specifying the inner margin between the border and contents. See [G-4] marginstyle for a list of margin choices.

textbox_options affect the rendition of the descriptive text associated with the keys. These are described in [G-3] textbox_options. One of the most commonly specified textbox_options is size(relativesize), which specifies the size of font to be used for the descriptive text.

title_options allow placing titles, subtitles, notes, and captions on legends. For instance, legend(col(1) subtitle("Legend")) produces

+---------------------+ | Legend | | | | o Observed | | --- Linear fit | | --- Quadratic fit | +---------------------+

Note our use of subtitle() and not title(); title()s are nearly always too big. See [G-3] title_options.

region(roptions) specifies the border and shading of the legend. You could remove the border around the legend by specifying legend(region(lstyle(none))) (thus doing away with the line) or legend(region(lcolor(none))) (thus making the line invisible). You could also give the legend a gray background tint by specifying legend(region(fcolor(gs5))). See Suboptions for use with legend(region()) below.

Suboptions for use with legend(region())

style(areastyle) specifies the overall style of the region in which the legend appears. The other suboptions allow you to change the region's attributes individually, but style() provides the starting point. See [G-4] areastyle for a list of choices.

color(colorstyle) specifies the color and opacity of the background of the legend and the line used to outline it. See [G-4] colorstyle for a list of color choices.

fcolor(colorstyle) specifies the background (fill) color and opacity for the legend. See [G-4] colorstyle for a list of color choices.

lstyle(linestyle) specifies the overall style of the line used to outline the legend, which includes its pattern (solid, dashed, etc.), its thickness, and its color. The other suboptions listed below allow you to change the line's attributes individually, but lstyle() is the starting point. See [G-4] linestyle for a list of choices.

lcolor(colorstyle) specifies the color and opacity of the line used to outline the legend. See [G-4] colorstyle for a list of color choices.

lwidth(linewidthstyle) specifies the thickness of the line used to outline the legend. See [G-4] linewidthstyle for a list of choices.

lpattern(linepatternstyle) specifies whether the line used to outline the legend is solid, dashed, etc. See [G-4] linepatternstyle for a list of choices.

lalign(linealignmentstyle) specifies whether the line used to outline the area is inside, outside, or centered. See [G-4] linealignmentstyle for a list of alignment choices.

margin(marginstyle) specifies the inner margin between the border and the contents of the legend. Also see bmargin() under Content suboptions for use with legend() and plegend() above for specifying the outer margin around the legend. See [G-4] marginstyle for a list of margin choices.

Location suboptions for use with legend()

off and on determine whether the legend appears. The default is on when more than one symbol (meaning marker, line style, or color swatch) appears in the legend. In those cases, legend(off) will suppress the display of the legend.

position(clockposstyle), ring(ringposstyle), and bplacement(compassdirstyle) override the default location of the legend, which is usually centered below the plot region. position() specifies a direction [sic] according to the hours on the dial of a 12-hour clock, and ring() specifies the distance from the plot region.

ring(0) is defined as being inside the plot region itself and allows you to place the legend inside the plot. ring(k), k>0, specifies positions outside the plot region; the larger the ring() value, the farther away from the plot region the legend is. ring() values may be integers or nonintegers and are treated ordinally.

When ring(0) is specified, bplacement() further specifies where in the plot region the legend is placed. bplacement(seast) places the legend in the southeast (lower-right) corner of the plot region.

position(12) puts the legend directly above the plot region (assuming ring()>0), position(3) directly to the right of the plot region, and so on.

See Where legends appear under Remarks below and Positioning of titles in [G-3] title_options for more information on the position() and ring() suboptions.

span specifies that the legend be placed in an area spanning the entire width (or height) of the graph rather than an area spanning the plot region. This affects whether the legend is centered with respect to the plot region or the entire graph. See Spanning in [G-3] title_options for more information on span.

at(#) is for use only when the twoway_option by() is also specified. It specifies that the legend appear in the #th position of the RxC array of plots, using the same coding as by(..., holes()). See Use of legends with by() under Remarks below, and see [G-3] by_option.

Remarks

Remarks are presented under the following headings:

When legends appear The contents of legends Where legends appear Putting titles on legends Use of legends with by() Problems arising with or because of legends

When legends appear

Standard legends appear on the graph whenever more than one symbol is used, where symbol is broadly defined to include markers, lines, and color swatches (such as those used to fill bars). When you draw a graph with only one symbol on it, such as

. sysuse uslifeexp

. line le year (click to run)

no legend appears. When there is more than one symbol, a legend is added:

. line le_m le_f year (click to run)

Even when there is only one symbol, a legend is constructed. It is merely not displayed. Specifying legend(on) forces the display of the legend:

. line le year, legend(on) (click to run)

Similarly, when there is more than one symbol and you do not want the legend, you can specify legend(off) to suppress it:

. line le_m le_f year, legend(off) (click to run)

A plegend() appears on any graph that includes a contourline plot.

The contents of legends

By default, the descriptive text for legends is obtained from the variable's variable label; see [D] label. If the variable has no variable label, the variable's name is used. In

. line le_m le_f year

the variable le_m had previously been labeled "Life expectancy, males", and the variable le_f had been labeled "Life expectancy, females". In the legend of this graph, repeating "life expectancy" is unnecessary. The graph would be improved if we changed the labels on the variables:

. label var le_m "Males"

. label var le_f "Females"

. line le_m le_f year

We can also specify the label() suboption to change the descriptive text. We obtain the same visual result without relabeling our variables:

. line le_m le_f year, legend(label(1 "Males") label(2 "Females")) (click to run)

The descriptive text for contourline legends is the values for the contour lines of the z variable.

Where legends appear

By default, standard legends appear beneath the plot, centered, at what is technically referred to as position(6) ring(3). By default, plegends() appear to the right of the plot region at position(3) ring(4). Suboptions position() and ring() specify the location of the legend. position() specifies on which side of the plot region the legend appears -- position(6) means 6 o'clock -- and ring() specifies the distance from the plot region -- ring(3) means farther out than the title_option b2title() but inside the title_option note(); see [G-3] title_options.

If we specify legend(position(3)), the legend will be moved to the 3 o'clock position:

. line le_m le_f year, legend(pos(3)) (click to run)

This may not be what we desired, but it is what we asked for. The legend was moved to the right of the graph and, given the size of the legend, the graph was squeezed to fit. When you move legends to the side, you invariably also want to specify the col(1) option:

. line le_m le_f year, legend(pos(3) col(1)) (click to run)

As a matter of syntax, we could have typed the above command with two legend() options

. line le_m le_f year, legend(pos(3)) legend(col(1))

instead of one combined: legend(pos(3) col(1)). We would obtain the same results either way.

If we ignore the syntax, the above graph would look better with less-descriptive text,

. line le_m le_f year, legend(pos(3) col(1) lab(1 "Males") lab(2 "Females")) (click to run)

and we can further reduce the width required by the legend by specifying the stack suboption:

. line le_m le_f year, legend(pos(3) col(1) lab(1 "Males") lab(2 "Females") stack) (click to run)

We can make this look better by placing a blank line between the first and second keys:

. line le_m le_f year, legend(pos(3) col(1) lab(1 "Males") lab(2 "Females") stack order(1 - " " 2)) (click to run)

ring() -- the suboption that specifies the distance from the plot region -- is seldom specified, but, when it is specified, ring(0) is the most useful. ring(0) specifies that the legend be moved inside the plot region:

. line le_m le_f year, legend(pos(5) ring(0) col(1) lab(1 "Males") lab(2 "Females")) (click to run)

Our use of position(5) ring(0) put the legend inside the plot region, at 5 o'clock, meaning in the bottom right corner. Had we specified position(2) ring(0), the legend would have appeared in the top left corner.

We might now add some background color to the legend:

. line le_m le_f year, legend(pos(5) ring(0) col(1) lab(1 "Males") lab(2 "Females") region(fcolor(gs15))) (click to run)

Putting titles on legends

Legends may include titles:

. line le_m le_f year, legend(pos(5) ring(0) col(1) lab(1 "Males") lab(2 "Females") region(fcolor(gs15))) legend(subtitle("Legend")) (click to run)

Above we specified subtitle() rather than title() because, when we tried title(), it seemed too big.

Legends may also contain notes() and captions(); see [G-3] title_options.

Use of legends with by()

If you want the legend to be located in the default location, no special action need be taken when you use by():

. sysuse auto, clear

. scatter mpg weight || lfit mpg weight ||, by(foreign, total row(1)) (click to run)

If, however, you wish to move the legend, you must distinguish between legend(contents) and legend(location). The former must appear outside the by(). The latter appears inside the by():

. scatter mpg weight || lfit mpg weight ||, legend(cols(1)) by(foreign, total legend(pos(4))) (click to run)

legend(col(1)) was placed in the command just where we would place it had we not specified by() but that legend(pos(4)) was moved to be inside the by() option. We did that because the cols() suboption is documented under contents in the syntax diagram, whereas position() is documented under location. The logic is that, at the time the individual plots are constructed, they must know what style of key they are producing. The placement of the key, however, is something that happens when the overall graph is assembled, so you must indicate to by() where the key is to be placed. Were we to forget this distinction and simply to type

. scatter mpg weight || lfit mpg weight ||, legend(cols(1) pos(4)) by(foreign, total)

the cols(1) suboption would have been ignored.

Another location suboption is provided for use with by(): at(#). You specify this option to tell by() to place the legend inside the RxC array it creates:

. scatter mpg weight || lfit mpg weight ||, legend(cols(1)) by(foreign, total legend(at(4) pos(0))) (click to run)

In the above, we specified at(4) to mean that the key was to appear in the fourth position of the 2x2 array, and we specified pos(0) to move the key to the middle (0 o'clock) position within the cell.

If you wish to suppress the legend, you must specify the legend(off) inside the by() option:

. scatter mpg weight || lfit mpg weight ||, by(foreign, total legend(off))

Problems arising with or because of legends

There are two potential problems associated with legends:

1. Text may flow outside the border of the legend box.

2. The presence of the legend may cause the title of the y axis to run into the values labeled on the axis.

The first problem arises because Stata uses an approximation to obtain the width of a text line. The solution is to specify the width(relativesize) textbox_option:

. graph ..., ... legend(width(#))

See Use of the textbox option width() in [G-3] added_text_option.

The second problem arises when the key is in its default position(6) (6 o'clock) location and the descriptive text for one or more of the keys is long. In position(6), the borders of the key are supposed to line up with the borders of the plot region. Usually the plot region is wider than the key, so the key is expanded to fit below it. When the key is wider than the plot region, however, it is the plot region that is widened. As the plot region expands, it will eat away at whatever is at it sides, namely, the y axis labels and title. Margins will disappear. In extreme cases, the title will be printed on top of the labels, and the labels themselves may end up on top of the axis!

The solution to this problem is to shorten the descriptive text, either by using fewer words or by breaking the long description into multiple lines. Use the legend(label(# "text")) option to modify the longest line of the descriptive text.


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