Stata 15 help for clegend_option

[G-3] clegend_option -- Option for controlling the contour-plot legend

Syntax

clegend_option Description ------------------------------------------------------------------------- clegend([suboptions]) contour-legend contents, appearance, and location ------------------------------------------------------------------------- clegend() is merged-implicit; see repeated options.

suboptions Description ------------------------------------------------------------------------- Contour legend appearance width(relativesize) width of contour key height(relativesize) height of contour key

altaxis move the contour key's axis to the other side of the contour key bmargin(marginstyle) outer margin around legend title_options titles, subtitles, notes, captions region(roptions) borders and background shading

Contour legend location 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 at(#) allowed with by() only ------------------------------------------------------------------------- See Where contour legends appear under Remarks below, and see Positioning of titles in [G-3] title_options for definitions of clockposstyle and ringposstyle.

roptions Description ----------------------------------------------------------------------- style(areastyle) overall style of region color(colorstyle) line and 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.) lalign(linealignmentstyle) line alignment (inside, outside, center) margin(marginstyle) margin between border and contents of legend -----------------------------------------------------------------------

Description

The clegend() option allows you to control the contents, appearance, and placement of the contour-plot legend.

Contour-plot legends have a single key that displays all the colors used to fill the contour areas. They also have a c axis that provides a scale for the key and associated contour plot. That axis is controlled using the c-axis option described in [G-3] axis_options.

Option

clegend(suboptions) specifies the appearance of a contour-plot legend, along with how it is to look, and whether and where it is to be displayed.

Content and appearance suboptions for use with clegend()

width(relativesize) specifies the width of the contour key. See [G-4] relativesize.

height(relativesize) specifies the height of the contour key. See [G-4] relativesize.

altaxis specifies that the contour key's axis be placed on the alternate side of the contour key from the default side. For most schemes, this means that the axis is moved from the right side of the contour key to the left side.

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

title_options allow placing titles, subtitles, notes, and captions on contour-plot legends. See [G-3] title_options.

region(roptions) specifies the border and shading of the legend. You could give the legend a gray background tint by specifying clegend(region(fcolor(gs9))). See Suboptions for use with clegend(region()) below.

Suboptions for use with clegend(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 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 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 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 legend 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 and appearance suboptions for use with clegend() above for specifying the outer margin around the legend. See [G-4] marginstyle for a list of margin choices.

Location suboptions for use with clegend()

off and on determine whether the legend appears. The default is on when a twoway contour plot appears in the graph. In those cases, clegend(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 to the right of 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 the legend is from the plot region. ring() values may be integers or nonintegers and are treated ordinarily.

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(9) directly to the left of the plot region, and so on.

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

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 contour legends appear Where contour legends appear Putting titles on contour legends Controlling the axis in contour legends Use of legends with by()

When contour legends appear

Contour legends appear on the graph whenever the graph contains a twoway contour plot.

. sysuse sandstone . twoway contour depth northing easting, levels(10) (click to run)

You can suppress the contour legend by specifying clegend(off),

. twoway contour depth northing easting, levels(10) clegend(off) (click to run)

Where contour legends appear

By default, legends appear to the right of the plot region at what is technically referred to as position(3) ring(3). Suboptions position() and ring() specify the location of the legend. position() specifies on which side of the plot region the legend appears -- position(3) means 3 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 clegend(position(9)), the legend will be moved to the 9 o'clock position:

. twoway contour depth northing easting, levels(10) clegend(pos(9)) (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:

. twoway contour depth northing easting, levels(10) clegend(pos(5) ring(0)) (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 right corner.

We might now add a background color to the legend:

. twoway contour depth northing easting, levels(10) clegend(pos(2) ring(0) region(fcolor(gs15))) (click to run)

Putting titles on contour legends

By default, the z axis of a contour legend displays the z variable label or variable name as a title. You can suppress this axis title. You can also add an overall title for the legend. We do that for the previous graph by adding the ztitle("") and clegend(title("Depth")) options:

. twoway contour depth northing easting, levels(10) ztitle("") clegend(title("Depth") region(fcolor(gs15))) (click to run)

Legends may also contain subtitles(), notes(), and captions(), though these are rarely used; see [G-3] title_options.

Controlling the axis in contour legends

Contour-plot legends contain a z axis. You control this axis just as you would the x or y axis of a graph. Here we specify cutpoints for the contours and custom tick labels using the zlabel() option,

. twoway contour depth northing easting, levels(10) zlabel(7600 "low" 7800 "medium" 8000 "high") region(fcolor(gs15))) (click to run)

Minor ticks, axis scale (logged, reversed, etc.), and all other aspects of the z axis can be controlled using the zlabel(), zmlabel(), ztick(), zmtick(), zscale(), and ztitle() options; see [G-3] axis_options.

Use of legends with by()

Legends are omitted by default when by() is specified. You can turn legends on by specifying clegend(on) within by(). It will show in the default location.

. sysuse surface . twoway contour temperature longitude latitude, level(10) xlabel(,format(%9.0f)) by(date, clegend(on)) (click to run)

If you want to move the legend, consider the different options and their placement on the command line. Location suboptions for use with clegend() should be specified within the by() option, whereas Content and appearance suboptions for use with clegend() should be specified outside the by() option. For example, the position() option changes where the legend appears, so it would be specified within the by() option:

. twoway contour temperature longitude latitude, level(10) xlabel(,format(%9.0f)) by(date, clegend(on pos(9))) (click to run)

If you want to also change the appearance of the legend, specify an additional clegend() option outside the by() option:

. twoway contour temperature longitude latitude, level(10) xlabel(,format(%9.0f)) clegend(on, width(15)) by(date, clegend(on pos(9))) (click to run)

If you specify the location suboptions outside the by() option, the location suboptions will be ignored.


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