The contents of the key, i.e., the names given to each plotted data set and
function and samples of the lines and/or symbols used to represent them, are
determined by the title and with options of the {s}plot command.
Please see plot title (p. ![[*]](crossref.png)
) and plot with (p. ) for more information.
Syntax:
set key {on|off} {default}
{{inside | outside} | {lmargin | rmargin | tmargin | bmargin}
| {at <position>}}
{left | right | center} {top | bottom | center}
{vertical | horizontal} {Left | Right}
{{no}reverse} {{no}invert}
{samplen <sample_length>} {spacing <vertical_spacing>}
{width <width_increment>}
{height <height_increment>}
{{no}autotitle {columnheader}}
{title "<text>"} {{no}enhanced}
{{no}box { {linestyle | ls <line_style>}
| {linetype | lt <line_type>}
{linewidth | lw <line_width>}}}
unset key
show key
Plots may be drawn with no visible key by requesting set key off or unset key.
Elements within the key are stacked according to vertical or horizontal. In the case of vertical, the key occupies as few columns as possible. That is, elements are aligned in a column until running out of vertical space at which point a new column is started. In the case of horizontal, the key occupies as few rows as possible.
By default the key is placed in the upper right inside corner of the graph. The keywords left, right, top, bottom, center, inside, outside, lmargin, rmargin, tmargin, bmargin (, above, over, below and under) may be used to automatically place the key in other positions of the graph. Also an at 5#5position6#6 may be given to indicate precisely where the plot should be placed. In this case, the keywords left, right, top, bottom and center serve an analogous purpose for alignment.
To understand positioning, the best concept is to think of a region, i.e., inside/outside, or one of the margins. Along with the region, keywords left/center/right (l/c/r) and top/center/bottom (t/c/b) control where within the particular region the key should be placed.
When in inside mode, the keywords left (l), right (r), top (t), bottom (b), and center (c) push the key out toward the plot boundary as illustrated:
t/l t/c t/r
c/l c c/r
b/l b/c b/r
When in outside mode, automatic placement is similar to the above illustration, but with respect to the view, rather than the graph boundary. That is, a border is moved inward to make room for the key outside of the plotting area, although this may interfere with other labels and may cause an error on some devices. The particular plot border that is moved depends upon the position described above and the stacking direction. For options centered in one of the dimensions, there is no ambiguity about which border to move. For the corners, when the stack direction is vertical, the left or right border is moved inward appropriately. When the stack direction is horizontal, the top or bottom border is moved inward appropriately.
The margin syntax allows automatic placement of key regardless of stack direction. When one of the margins lmargin (lm), rmargin (rm), tmargin (tm), and bmargin (bm) is combined with a single, non-conflicting direction keyword, the following illustrated positions may contain the key:
l/tm c/tm r/tm
t/lm t/rm
c/lm c/rm
b/lm b/rm
l/bm c/bm r/bm
Keywords above and over are synonymous with tmargin. For version compatibility, above or over without an additional l/c/r or stack direction keyword uses center and horizontal. Keywords below and under are synonymous with bmargin. For compatibility, below or under without an additional l/c/r or stack direction keyword uses center and horizontal. A further compatibility issue is that outside appearing without an additional t/b/c or stack direction keyword uses top, right and vertical (i.e., the same as t/rm above).
The 5#5position6#6 can be a simple x,y,z as in previous versions, but these can
be preceded by one of five keywords (first, second, graph, screen,
character) which selects the coordinate system in which the position of
the first sample line is specified. See coordinates (p. ) for more details.
The effect of left, right, top, bottom, and center when 5#5position6#6
is given is to align the key as though it were text positioned using the
label command, i.e., left means left align with key to the right of
5#5position6#6, etc.
Justification of the labels within the key is controlled by Left or Right (default is Right). The text and sample can be reversed (reverse) and a box can be drawn around the key (box {...}) in a specified linetype and linewidth, or a user-defined linestyle. Note that not all terminal drivers support linewidth selection, though.
By default the first plot label is at the top of the key and successive labels are entered below it. The invert option causes the first label to be placed at the bottom of the key, with successive labels entered above it. This option is useful to force the vertical ordering of labels in the key to match the order of box types in a stacked histogram.
The length of the sample line can be controlled by samplen. The sample length is computed as the sum of the tic length and 5#5sample_length6#6 times the character width. samplen also affects the positions of point samples in the key since these are drawn at the midpoint of the sample line, even if the sample line itself is not drawn.
The vertical spacing between lines is controlled by spacing. The spacing is set equal to the product of the pointsize, the vertical tic size, and 5#5vertical_spacing6#6. The program will guarantee that the vertical spacing is no smaller than the character height.
The 5#5width_increment6#6 is a number of character widths to be added to or subtracted from the length of the string. This is useful only when you are putting a box around the key and you are using control characters in the text. gnuplot simply counts the number of characters in the string when computing the box width; this allows you to correct it.
The 5#5height_increment6#6 is a number of character heights to be added to or subtracted from the height of the key box. This is useful mainly when you are putting a box around the key, otherwise it can be used to adjust the vertical shift of automatically chosen key position by 5#5height_increment6#6/2.
All plotted curves of plots and splots are titled according to the default option autotitles. The automatic generation of titles can be suppressed by noautotitles; then only those titles explicitly defined by (s)plot ... title ... will be drawn.
The set key autotitle columnheader option is available if gnuplot was built with -enable-datastrings. This command causes the first entry in each column of plotted data to be interpreted as a text string and used as a title for the corresponding plot. If the quantity being plotted is a function of data from several columns, gnuplot may be confused as to which column to draw the title from. In this case it is necessary to specify the column explicitly in the plot command, e.g. plot "datafile" using (($2+$3)/$4) title 3 with lines.
A title can be put on the key (title "5#5text6#6") -- see also syntax (p. ) for the
distinction between text in single- or double-quotes. The key title uses the
same justification as do the plot titles.
An explicitly given title is typeset using enhanced text properties on
terminals supporting this, see enhanced text (p. ) for more details.
This default behavior can be switched off by the noenhanced option.
The defaults for set key are on, right, top, vertical, Right, noreverse, noinvert, samplen 4, spacing 1.25, title "", and nobox. The default 5#5linetype6#6 is the same as that used for the plot borders. Entering set key default returns the key to its default configuration.
The key is drawn as a sequence of lines, with one plot described on each line. On the right-hand side (or the left-hand side, if reverse is selected) of each line is a representation that attempts to mimic the way the curve is plotted. On the other side of each line is the text description (the line title), obtained from the plot command. The lines are vertically arranged so that an imaginary straight line divides the left- and right-hand sides of the key. It is the coordinates of the top of this line that are specified with the set key command. In a plot, only the x and y coordinates are used to specify the line position. For a splot, x, y and z are all used as a 3-d location mapped using the same mapping as the graph itself to form the required 2-d screen position of the imaginary line.
When using the TeX or PostScript drivers, or similar drivers where formatting information is embedded in the string, gnuplot is unable to calculate correctly the width of the string for key positioning. If the key is to be positioned at the left, it may be convenient to use the combination set key left Left reverse. The box and gap in the grid will be the width of the literal string.
If splot is being used to draw contours, the contour labels will be listed
in the key. If the alignment of these labels is poor or a different number
of decimal places is desired, the label format can be specified. See
set clabel (p. ) for details.
Examples:
This places the key at the default location:
set key default
This disables the key:
unset key
This places a key at coordinates 2,3.5,2 in the default (first) coordinate
system:
set key at 2,3.5,2
This places the key below the graph:
set key below
This places the key in the bottom left corner, left-justifies the text,
gives it a title, and draws a box around it in linetype 3:
set key left bottom Left title 'Legend' box 3