Axes and Legends

Labels, limits, scales, secondary axes, grids and legends. The snippets assume an axes from fig.add_subplot(111).

Labels and title

ax.set_xlabel('X Axis Label')
ax.set_ylabel('Y Axis Label')
ax.set_title('Plot Title')

Labels take matplotlib mathtext between $...$. See Contour Plots and Heatmaps for Greek letters and GLE’s own text markup.

fontname= sets the font of one title, as a GLE font name such as 'texcmr' or 'psh'. It is written as font on that title or xtitle line. Leave it out to keep the current font.

ax.set_title('Plot Title', fontname='texcmb')
ax.set_xlabel('t (s)', fontname='texcmr')

fontsize (points, or a name such as 'small'), color and labelpad (the gap to the tick labels, in points) work as in matplotlib, and so does pad on set_title (the gap above the axes). They are written as hei, color and dist on the same line:

ax.set_xlabel('T (K)', fontsize=9, color='gray', labelpad=4)
ax.set_title('Run 12', fontsize=11, pad=6)

Limits

ax.set_xlim(0, 10)
ax.set_ylim(-1, 1)

Passing the limits in descending order inverts the axis, as in matplotlib. This is useful for depth below ground, magnitudes, and anything else that counts downwards:

ax.set_ylim(500, 0)    # zero at the top, 500 at the bottom

ax.invert_yaxis() (and invert_xaxis) does the same by swapping the limits. gleplot has no inverted-but-automatic axis, so an automatic limit is replaced by the end of the data plotted so far: plot first, then invert.

The one exception is a log axis, which GLE cannot invert; a descending log range is drawn the usual way round, with a UserWarning.

Aspect ratio

ax.set_aspect('equal') gives a unit the same length on both axes, so a circle is drawn round; a number a makes a y unit a times as long as an x unit, and on a log axis a unit is a decade:

import numpy as np
import gleplot as glp

t = np.linspace(0, 2 * np.pi, 200)
fig, ax = glp.subplots(figsize=(6, 4))
ax.plot(np.cos(t), np.sin(t))
ax.set_aspect('equal')

When the figure is saved, the frame is shrunk about its centre to fit the ratio of the axis limits it is saved with. ax.axis('equal') only warns: use set_aspect. A figure opened again with open_gle keeps the shrunk frame but not the aspect, so changing its limits afterwards does not reshape the frame.

Log scales

ax.set_xscale('log')
ax.set_yscale('log')

ax.semilogx(x, y), ax.semilogy(x, y) and ax.loglog(x, y) set the scale and call plot.

A log axis can only show strictly positive values, and GLE refuses to compile a script that asks it to do otherwise. gleplot therefore resolves log limits before writing them, as matplotlib does: non-positive data is masked when autoscaling, and a non-positive limit passed to set_xlim/set_ylim is replaced by the smallest positive value plotted. Either repair emits a UserWarning saying what range was used instead; pass a positive range to choose your own.

GLE leaves a negative value on a log axis out of a line and joins the points either side of it, where matplotlib draws the line off the axis; a zero takes the line down to the axis edge. Saving warns when a plot or step line has a negative value on a log axis. Set those values to NaN to break the line there instead.

Secondary axes

The right-hand scale is yaxis="y2" on a series, with set_ylim, set_ylabel, set_yscale and set_tick_format taking axis="y2":

ax.plot(x, temperature, label='Temperature')
ax.plot(x, humidity, label='Humidity', yaxis='y2')
ax.set_ylabel('Temperature (°C)', axis='y')
ax.set_ylabel('Humidity (%)', axis='y2')

ax.twinx() is the matplotlib view of the same scale. The x axis stays the one the view was opened on; limits, log, tick format and the label set on the view belong to the right scale:

right = ax.twinx()
right.plot(x, humidity, label='Humidity')
right.set_ylabel('Humidity (%)')

Each y scale fits its own series, as with matplotlib’s twinx: the left range gleplot writes leaves out the series on y2, and GLE scales y2 from them. An axes with nothing at all on the left axis is the exception: its left range spans the y2 series, where matplotlib’s empty left axis runs from 0 to 1.

The top scale is the same idea, and ax.twiny() is the matplotlib view that binds it. The y axis stays the one the view was opened on; limits, log and the label set on the view belong to the top scale:

top = ax.twiny()
top.plot(x_alt, y)
top.set_xlim(0, 10)
top.set_xlabel("wavelength")

xaxis="x2" on plot, scatter, errorbar, step, stem, hist (step outline), line_from_file and errorbar_from_file is the same binding without the view. set_xlim, set_xlabel, set_xscale and set_tick_format take axis="x2".

GLE copies an xaxis command onto x2. min and max are not copied, but log is, so a linear top scale under a log bottom axis is written x2axis lin after the xaxis line. A figure whose bottom axis is log and whose top scale is unused does not gain that line. x2labels on is written when the top scale has limits, a log scale, a title, or tick-label styling; a series on x2 is enough for GLE to number that axis on its own. There is no x2 grid. A filled histogram cannot use x2, and bar has no x2axis.

Grid

ax.grid(True)                 # major grid
ax.grid(True, which='both')   # major and minor grid

Axis lines and tick placement

set_axis_line sets the colour and width (points) of an axis line, written as GLE’s xside. The ticks, tick labels and grid keep their colour.

ax.set_axis_line(color='gray', linewidth=1.2)   # the x and y lines
ax.set_axis_line('x2', color='red')             # the top line on its own

GLE copies the x line’s style onto the top line and the y line’s onto the right one, so 'x' or 'both' styles all four sides unless 'x2' or 'y2' is set too.

visible=False hides one side, matplotlib’s spines[...].set_visible(False):

ax.set_axis_line('x2', visible=False)   # no top line
ax.set_axis_line('y2', visible=False)   # no right line

The bottom and left lines keep their ticks and tick labels when hidden. The top and right sides lose the tick marks GLE mirrors there too, and a twiny/twinx scale on that side with them, which warns.

set_xticks and set_yticks also take GLE’s own placement keywords: nticks (number of major ticks), ftick (where the first one goes), shift (move the tick labels along the axis, in cm), symticks=True (ticks inside and outside the frame) and noticks (positions with no tick). GLE copies them onto the top and right axes.

ax.set_xticks(nticks=5, ftick=0)
ax.set_yticks(symticks=True, noticks=[0])

Tick marks and minor ticks

tick_params sets the length, width (both in points), colour and direction of the tick marks, written as GLE’s xticks (major) and xsubticks (minor). minorticks_on and minorticks_off switch the minor ticks of both axes.

ax.tick_params(axis='x', length=4, width=0.8, direction='in')
ax.tick_params(axis='y', which='minor', length=2)
ax.minorticks_off()

GLE draws ticks inside the frame by default; matplotlib draws them outside. direction='out' is a negative GLE length, so with no length it uses matplotlib’s default (3.5 points, 2 for minor ticks). direction='inout' is GLE’s symticks, one setting for an axis’ major and minor ticks. An axis with a grid draws the grid lines in place of its ticks, so its tick marks are not written and saving warns; style the grid with grid(color=..., linewidth=...) instead.

set_xticks and set_yticks also take nsubticks (minor ticks between two major ones), loglabels (which sub-decades of a log axis get a label: 'off', 'l1', 'l25', 'l25b' or 'n1') and nofirst / nolast (leave out the first or last tick label).

ax.set_xscale('log')
ax.set_xticks(loglabels='l25', nofirst=True)
ax.set_yticks(nsubticks=4)

set_math_mode draws the x and y axes through the origin instead of around the plot, with ticks on both sides. It is written as GLE’s math. Both axes move together. The top and right axes are hidden unless a series or label uses them. Both limits must include 0, and neither axis can be log.

ax.set_math_mode()          # axes cross at (0, 0)
ax.set_math_mode(False)     # back to a box around the plot

Legends

ax.plot(x, y1, label='Series 1')
ax.plot(x, y2, label='Series 2')
ax.legend()                   # default location
ax.legend(loc='upper right')  # custom location

The legend is GLE’s key command. Which legend() keywords are honoured, and what happens to the rest, is listed in the Matplotlib Migration Guide.

One legend for several axes is fig.legend(). It lists the labelled series of every axes, and while it exists an axes draws its own legend only if ax.legend() was called on it:

fig, axes = glp.subplots(1, 2)
axes[0].plot(x, y1, label='Series 1')
axes[1].plot(x, y2, label='Series 2')
fig.legend(loc='lower center', ncol=2)
fig.subplots_adjust(bottom=0.2)