8.7 Graph legends

By default, plots are displayed with legends in their top-right corners. The textual description of each dataset is auto-generated from the command used to plot it. Alternatively, the user may specify his own description for each dataset by following the plot command with the title modifier, as in the following examples:

plot sin(x) title 'A sine wave'
plot cos(x) title ''

In the latter case a blank title is specified, which indicates to Pyxplot that no entry should be made for the dataset in the legend. This allows for legends which contain only a subset of the datasets on a plot. Alternatively, the production of the legend can be completely turned off for all datasets using the command set nokey. Having issued this command, the production of keys can be resumed using the set key command.

The set key command can also be used to dictate how legends should be positioned on graphs, using a syntax along the lines of:

set key top right

The following recognised positional keywords are self-explanatory: top, bottom, left, right, xcenter and ycenter. Any single instance of the set key command can be followed by one horizontal alignment keyword and one vertical alignment keyword; these keywords also affect the justification of the legend – for example, the keyword left aligns the legend with its left edge against the left edge of the plot.

Alternatively, the position of the legend can be indicated using one of the keywords outside, below or above. These cannot be combined with the horizontal and vertical alignment keywords above, and are used to indicate that the legend should be placed, respectively, outside the plot on its right side, centered beneath the plot, and centered above the plot.

Two comma-separated positional offset coordinates may be specified following any of the named positions listed above to fine-tune the position of the legend – the first value is assumed to be a horizontal offset and the second a vertical offset. Either may have units of length, or, if they are dimensionless, are assumed to be measured in centimeters, as the following examples demonstrate:

set key bottom left 0.0 -2
set key top xcenter 2*unit(mm),2*unit(mm)

By default, entries in the legend are automatically sorted into an appropriate number of columns. The number of columns to be used, can, instead, be stipulated using the set keycolumns command. This should be followed by either the integer number of desired columns, or by the keyword auto to indicate that the default behaviour of automatic formatting should be resumed:

set keycolumns 2
set keycolumns auto