help legend_option
-------------------------------------------------------------------------------
Title
[G] legend_option -- Option for specifying legend
Syntax
legend_option description
---------------------------------------------------------------------
legend([contents] [location]) legend contents and location
---------------------------------------------------------------------
legend() is merged-implicit; see repeated options.
where contents and location specify the contents and the location of the
legend.
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
---------------------------------------------------------------------
location description
---------------------------------------------------------------------
off or on suppress or force display of legend
position(clockposstyle) where legend appears
ring(ringposstyle) where legend appears (detail)
span "centering" of legend
at(#) allowed with by() only
---------------------------------------------------------------------
See Where legends appear under Remarks below, and see Positioning of
titles in [G] 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 of region
fcolor(colorstyle) fill color of region
lstyle(linestyle) overall style of border
lcolor(colorstyle) color of border
lwidth(linewidthstyle) thickness of border
lpattern(linepatternstyle) border pattern (solid, dashed, etc.)
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).
Option
legend(contents, location) defines the contents of a legend, along with
how it is to look, and whether and where it is to be displayed.
Content suboptions for use with legend()
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.
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.
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.
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 the scatter_option
pstyle() with legend()'s suboption legend(style()). The
scatter_option pstyle() sets the overall style for the rendition of
the points. legend()'s style() suboption is documented directly
below.
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] 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] 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] 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] 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] marginstyle for a list of margin
choices.
textbox_options affect the rendition of the descriptive text associated
with the keys. These are described in textbox_options. One of the
most commonly specified [G] 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] 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] areastyle for a list of choices.
color(colorstyle) specifies the color of the background of the legend and
the line used to outline it. See [G] colorstyle for a list of color
choices.
fcolor(colorstyle) specifies the background (fill) color for the legend.
See [G] 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] linestyle for a list of choices.
lcolor(colorstyle) specifies the color of the line used to outline the
legend. See [G] colorstyle for a list of color choices.
lwidth(linewidthstyle) specifies the thickness of the line used to
outline the legend. See [G] linewidthstyle for a list of choices.
lpattern(linepatternstyle) specifies whether the line used to outline the
legend is solid, dashed, etc. See [G] linepatternstyle for a list of
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() above for specifying the outer margin around
the legend. See [G] 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) and ring(ringposstyle) 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.
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] 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]
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] 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
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)
The contents of legends
By default, the descriptive text 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)
Where legends appear
By default, legends appear beneath the plot, centered, at what is
technically referred to as position(6) ring(3). Suboptions position()
and ring() specify the location of the label. 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] 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] 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] 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.
Also see
Manual: [G] legend_option
Help: [G] title_options
