legend_option.hlp

是一个经济学管理应用软件 很难找的 但是经济学学生又必须用到

    See {hi:Spanning} in
    {it:{help title_options}} for more information on {cmd:span}.

{phang}
{cmd:at(}{it:#}{cmd:)}
    is for use only when the {it:twoway_option} {cmd:by()} is also
    specified.  It specifies that the legend appear in the
    {it:#}th position of the
    {it:RxC} array of plots, using the same coding as
    {cmd:by(}...{cmd:,} {cmd:holes())}.  See
    {help legend_option##remarks5:Use of legends with by()} under {hi:Remarks}
    below, and see {it:{help by_option}}.


{title:Remarks}

{pstd}
Remarks are presented under the headings

	{help legend_option##remarks1:When legends appear}
	{help legend_option##remarks2:The contents of legends}
	{help legend_option##remarks3:Where legends appear}
	{help legend_option##remarks4:Putting titles on legends}
	{help legend_option##remarks5:Use of legends with by()}
	{help legend_option##remarks6:Problems arising with or due to legends}


{marker remarks1}{...}
{title:When legends appear}

{pstd}
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

	{cmd:. sysuse uslifeexp, clear}

	{cmd:. line le year}
	  {it:({stata "gr_example uslifeexp: line le year":click to run})}
{* graph legend1}{...}

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

	{cmd:. line le_m le_f year}
	  {it:({stata "gr_example uslifeexp: line le_male le_female year":click to run})}
{* graph legend2}{...}

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

	{cmd:. line le year, legend(on)}
	  {it:({stata "gr_example uslifeexp: line le year, legend(on)":click to run})}
{* graph legend3}{...}

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

	{cmd:. line le_m le_f year, legend(off)}
	  {it:({stata "gr_example uslifeexp: line le_male le_female year, legend(off)":click to run})}
{pstd}


{marker remarks2}{...}
{title:The contents of legends}

{pstd}
By default, the descriptive text is obtained from the variable's variable
label; see {helpb labels}.  If the variable has no variable label, the
variable's name is used.  In

	{cmd:. line le_m le_f year}

{pstd}
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:

	{cmd:. label var le_m "Males"}

	{cmd:. label var le_f "Females"}

	{cmd:. line le_m le_f year}

{pstd}
Alternatively, we can specify the {cmd:label()} suboption to change the
descriptive text.  We obtain the same visual result without relabeling our
variables:

{phang2}
	{cmd:. line le_m le_f year, legend( label(1 "Males") label(2 "Females") )}
{p_end}
	  {it:({stata `"gr_example uslifeexp: line le_male le_female year, legend(label(1 "Males") label(2 "Females"))"':click to run})}
{* graph legend5}{...}


{marker remarks3}{...}
{title:Where legends appear}

{pstd}
By default, legends appear beneath the plot, centered, at what is technically
referred to as {cmd:position(6)} {cmd:ring(3)}.  Suboptions {cmd:position()}
and {cmd:ring()} specify the location of the label.  {cmd:position()}
specifies on which side of the plot region the legend
appears{hline 2}{cmd:position(6)} means 6 o'clock{hline 2}and {cmd:ring()}
specifies the distance from the plot region{hline 2}{cmd:ring(3)} means
farther out than the {it:title_option} {cmd:b2title()} but inside the
{it:title_option} {cmd:note()}; see {it:{help title_options}}.

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

	{cmd:. line le_m le_f year, legend( pos(3) )}
	  {it:({stata "gr_example uslifeexp: line le_male le_female year, legend(pos(3))":click to run})}
{* graph legend6}{...}

{pstd}
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 {cmd:col(1)} option:

	{cmd:. line le_m le_f year, legend( pos(3) col(1) )}
	  {it:({stata "gr_example uslifeexp: line le_male le_female year, legend(pos(3) col(1))":click to run})}
{* graph legend7}{...}

{pstd}
As a matter of syntax, we could have typed the above command with two
{cmd:legend()} options

{phang2}
	{cmd:. line le_m le_f year, legend(pos(3)) legend(col(1))}

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

{pstd}
Putting aside syntax, the above graph would look better with less-descriptive
text,

	{cmd:. line le_m le_f year, legend( pos(3) col(1)}
				       {cmd:lab(1 "Males") lab(2 "Females") )}
	  {it:({stata `"gr_example uslifeexp: line le_m le_f year, legend(pos(3) col(1) lab(1 "Males") lab(2 "Females"))"':click to run})}
{* graph legend8}{...}

{pstd}
and we can further reduce the width required by the legend by specifying
the {cmd:stack} suboption:

	{cmd:. line le_m le_f year, legend( pos(3) col(1)}
				       {cmd:lab(1 "Males") lab(2 "Females") stack )}
	  {it:({stata `"gr_example uslifeexp: line le_m le_f year, legend(pos(3) col(1) lab(1 "Males") lab(2 "Females") stack)"':click to run})}
{* graph legend9}{...}

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

	{cmd:. line le_m le_f year, legend( pos(3) col(1)}
				       {cmd:lab(1 "Males") lab(2 "Females") stack}
				       {cmd:order(1 - " " 2) )}
	  {it:({stata `"gr_example uslifeexp: line le_m le_f year, legend(pos(3) col(1) lab(1 "Males") lab(2 "Females") stack order(1 - " " 2))"':click to run})}
{* graph legend10}{...}

{pstd}
{cmd:ring()}{hline 2}the suboption that specifies the distance from the plot
region{hline 2}is seldom specified, but, when it is specified, {cmd:ring(0)} is
the most useful.  {cmd:ring(0)} specifies that the legend be moved inside the
plot region:

	{cmd:. line le_m le_f year, legend( pos(5) ring(0) col(1)}
				       {cmd:lab(1 "Males") lab(2 "Females") )}
	  {it:({stata `"gr_example uslifeexp: line le_m le_f year, legend(pos(5) ring(0) col(1) lab(1 "Males") lab(2 "Females"))"':click to run})}
{* graph legend11}{...}

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

{pstd}
We might now add some background color to the legend:

	{cmd:. line le_m le_f year, legend( pos(5) ring(0) col(1)}
				       {cmd:lab(1 "Males") lab(2 "Females")}
				       {cmd:region(fcolor(gs15)) )}
	  {it:({stata `"gr_example uslifeexp: 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})}
{* graph legend12}{...}


{marker remarks4}{...}
{title:Putting titles on legends}

{pstd}
Legends may include titles:

	{cmd:. line le_m le_f year, legend( pos(5) ring(0) col(1)}
				       {cmd:lab(1 "Males") lab(2 "Females")}
				       {cmd:region(fcolor(gs15)) )}
			       {cmd:legend( subtitle("Legend") )}
	  {it:({stata `"gr_example uslifeexp: 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})}
{* graph legend13}{...}


{pstd}
Above we specified {cmd:subtitle()} rather than {cmd:title()} because, when
we tried {cmd:title()}, it seemed too big.

{pstd}
Legends may also contain {cmd:notes()} and {cmd:captions()}; see 
{it:{help title_options}}.


{* legends, use with by() tt}{...}
{* index by() tt, use of legends with}{...}
{marker use_of_legends_with_by}{...}
{marker remarks5}{...}
{title:Use of legends with by()}

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

	{cmd:. sysuse auto, clear}

{phang2}
	{cmd:. scatter mpg weight || lfit mpg weight ||, by(foreign, total row(1))}
{p_end}
	  {it:({stata "gr_example auto: scatter mpg weight || lfit mpg weight ||, by(foreign, total row(1))":click to run})}
{* graph legend14}{...}

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

	{cmd:. scatter mpg weight || lfit mpg weight ||,}
		  {cmd:legend(cols(1))}
		  {cmd:by(foreign, total legend(pos(4)))}
	  {it:({stata "gr_example auto: scatter mpg weight || lfit mpg weight ||, legend(cols(1)) by(foreign, total legend(pos(4)))":click to run})}
{* graph legend15}{...}

{pstd}
Note that {cmd:legend(col(1))} was placed in the command just where we
would place it had we not specified {cmd:by()} but that
{cmd:legend(pos(4))} was moved to be inside the {cmd:by()} option.
We did that because the {cmd:cols()} suboption is documented under
{it:contents} in the syntax diagram, whereas {cmd:position()} is documented
under {it: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 {cmd:by()} where the key is to be
placed.  Were we to forget this distinction and simply to type

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

{pstd}
the {cmd:cols(1)} suboption would have been ignored.

{pstd}
An additional {it:location} suboption is provided for use in the case
of {cmd:by()}:  {cmd:at(}{it:#}{cmd:)}.  You specify this option to tell
{cmd:by()} to place the legend inside the {it:RxC} array it creates:

	{cmd:. scatter mpg weight || lfit mpg weight ||,}
		  {cmd:legend(cols(1))}
		  {cmd:by(foreign, total legend(at(4) pos(0)))}
	  {it:({stata "gr_example auto: scatter mpg weight || lfit mpg weight ||, legend(cols(1)) by(foreign, total legend(at(4) pos(0)))":click to run})}
{* graph legend16}{...}

{pstd}
In the above, we specified {cmd:at(4)} to mean that the key was to appear
in the 4th position of the 2{it:x}2 array, and we specified
{cmd:pos(0)} to move the key to the middle (0 o'clock) position within
the cell.

{pstd}
If you wish to suppress the legend altogether, you must specify the
{cmd:legend(off)} inside
the {cmd:by()} option:

	{cmd:. scatter mpg weight || lfit mpg weight ||,}
		  {cmd:by(foreign, total legend(off))}


{* index legends, problems}{...}
{marker remarks6}{...}
{title:Problems arising with or due to legends}

{pstd}
There are two potential problems associated with legends:

{phang2}
    1.  Text may flow outside the border of the legend box.

{phang2}
    2.  The presence of the legend may cause the title of the {it:y} axis
	to run into the values labeled on the axis.

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

{phang2}
	{cmd:. graph} ...{cmd:,} ... {cmd:legend(width(}{it:#}{cmd:))}

{pstd}
See
{hi:Use of the textbox option width()}
in 
{it:{help added_text_option}}.

{pstd}
The second problem arises when the key is in its default {cmd:position(6)}
(6 o'clock) location and the descriptive text for one or more of the keys is
very long.  In {cmd: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
{it: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!

{pstd}
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 {cmd:legend(label(}{it:#} {cmd:"}{it:text}{cmd:"))} option to modify
the longest line of the descriptive text.


{title:Also see}

{psee}
Manual:  {bf:[G] {it:legend_option}}

{psee}
Online:  {it:{help title_options}}
{p_end}