Matplotlib Migration Guide
gleplot intentionally mirrors the matplotlib style for core plotting tasks.
Quick Mapping
matplotlib |
gleplot |
|---|---|
|
|
|
same; gleplot tracks only the current figure, so |
|
|
|
same, including a |
|
same for a rect in figure fractions; the inset has no background unless given |
|
same, but without the |
|
same |
|
same, with matplotlib’s positional order |
|
same |
|
same |
|
same, see Fills |
|
same, see Segments |
|
not provided, see Not provided |
|
same on a uniform grid, see Cells |
|
same on a uniform grid, see Filled contours |
|
same, see Colorbars |
|
same, lines, scatters and function curves, see Polar axes |
|
same; |
|
same as |
|
same, including |
|
same; |
|
|
|
|
|
|
|
|
|
same |
|
same, a view of the right or top scale, see Secondary axes; their |
|
same; automatic limits are fixed to the data plotted so far, so plot first. On a |
|
same; |
|
same, after |
|
same, but the axis labels stay (with a warning); |
|
same, as GLE’s graph |
|
same, resizing the box about its centre; |
|
|
Minimal Porting Example
Matplotlib:
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0, 10, 100)
y = np.sin(x)
fig, ax = plt.subplots(figsize=(8, 5))
ax.plot(x, y, color='blue', label='sin(x)')
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.legend()
fig.savefig('plot.pdf')
gleplot:
import gleplot as glp
import numpy as np
x = np.linspace(0, 10, 100)
y = np.sin(x)
fig, ax = glp.subplots(figsize=(8, 5))
ax.plot(x, y, color='blue', label='sin(x)')
ax.set_xlabel('x')
ax.set_ylabel('y')
ax.legend()
fig.savefig('plot.pdf')
Default colours
A series given no colour takes the next of matplotlib’s 'C0' to 'C9', per axes, where matplotlib would: lines (plot, step, errorbar, hist, stackplot) and patches (scatter, bar, barh, fill, fill_between, fill_betweenx) have separate cycles, stem, hlines and vlines draw in 'C0', and a twinx()/twiny() view has cycles of its own. A colour that is given takes nothing from the cycle. The rules are in the GLEStyleConfig reference. A figure opened with open_gle continues each cycle after the series whose colours follow it.
To draw every uncoloured line, histogram and function curve in one colour, and every uncoloured marker in another, set GLEStyleConfig(default_color=..., default_marker_color=...). Bars, fills and stackplot layers always take the cycle.
Legends
ax.legend() becomes GLE’s graph-block key command. The kwargs that map
onto a key option are honoured; every other matplotlib legend kwarg raises
a UserWarning instead of being silently dropped.
label= on bar and fill_between is a real legend entry. GLE’s bar and
fill commands have no key qualifier, so the swatch is a following dataset
line: dN key "label" for a bar (the bar fill is already the swatch) and
dN keyfill COLOR key "label" for a fill. axvspan / axhspan use the same
fill swatch.
|
gleplot |
|---|---|
|
wired — all eleven matplotlib strings map onto GLE’s nine key anchors ( |
|
wired — points converted to cm as |
|
wired — |
|
wired — entries in the order they were added, packed like matplotlib (column-major; the first columns are one entry longer). When that order is the order GLE draws the series, the breaks are |
|
wired — the legend-box fill, emitted as GLE |
|
wired — gleplot/GLE flag, not a matplotlib name. |
|
wired — |
|
wired — font-size units, as in matplotlib, written in cm as GLE |
|
wired — one colour, written as |
handles/labels (first positional) |
warns — legend text always comes from each series’ |
|
warn. GLE’s key has no title; a text-only entry would sit in the label column of the first column, not above the legend. GLE’s row height ( |
# an 8.6 cm journal column wants legend text smaller than the axis labels
ax.legend(loc='upper left', fontsize=6.5, frameon=False)
# beside the graph, with shorter line swatches and grey text
ax.legend(loc='upper left', bbox_to_anchor=(1.02, 1.0), handlelength=1.5,
labelcolor='gray')
Text
ax.text(x, y, s) places a label in data coordinates, or in fractions of the
axes frame with transform=ax.transAxes.
|
gleplot |
|---|---|
|
wired — |
|
wired — |
|
wired — degrees counter-clockwise about the alignment point ( |
|
|
|
|
other keywords ( |
warn and are ignored. |
ax.text(1, 2, "peak", va="bottom", rotation=45, bbox={"facecolor": "white"})
ax.text(0.05, 0.95, "(a)", transform=ax.transAxes, va="top") # panel label
matplotlib’s text.usetex is GLEStyleConfig(usetex=True), set for the
figure rather than in rcParams; see the
Configuration Guide. There is no per-text usetex=
keyword.
Figure-level text and legend
fig.suptitle, fig.text and fig.legend work on the whole page, as in
matplotlib. They are written after every axes, so they sit on top of them.
Call |
gleplot |
|---|---|
|
centred at |
|
|
|
one legend listing the labelled series of every axes, axes by axes, each axes’ series in the order they were added. While it exists, an axes draws its own legend only if |
fig, axes = glp.subplots(1, 2)
fig.suptitle("Sample A")
fig.text(0.02, 0.98, "(a)", ha="left", va="top")
fig.legend(loc="lower center", ncol=3)
fig.subplots_adjust(bottom=0.2)
Annotations
ax.annotate(text, xy, xytext=..., arrowprops=...) is a text at xytext with an arrow to xy, both in data coordinates. The text takes the text() keywords above. The arrow is GLE join from the text’s named box to a saved point at xy, so it starts at the box edge (0.05 cm pad) rather than over the text. An xy inside the text’s own box draws the arrow back across the text, where matplotlib draws nothing: keep xytext clear of the point.
|
gleplot |
|---|---|
|
wired. Omitted: the text sits on |
|
only |
|
|
|
|
|
wired, in points ( |
|
straight |
|
warn and are ignored. |
|
warns; the annotation is always drawn. |
ax.annotate("peak", xy=(2, 3), xytext=(2.4, 3.5), arrowprops={"arrowstyle": "->"})
Step and stem plots
GLE draws these as a mode on the same dN line command. The points stay in the data file; only the join changes.
call |
GLE |
|---|---|
|
|
|
|
|
|
|
|
|
|
line hist is an outline through points that are already bin centres. Binning samples into counts is Axes.hist, below.
ax.step(x, y, where="pre")
ax.plot(x, y, drawstyle="steps-mid")
ax.stem(x, y)
argument |
gleplot |
|---|---|
|
|
|
the five matplotlib names above. |
|
read as |
|
warns. There is no line for the mode to qualify. |
|
a step, stem, hist, bar or impulse series stays unsmoothed. GLE would spline the points first and then draw the mode through the spline. A script that writes both keywords keeps the smooth it asked for. |
|
color, linestyle and marker are applied. Stems and heads are one dataset, so two different colors warn and the line color wins. |
|
warns unless it is |
|
warns, unless it asks for no baseline. No baseline is drawn. |
|
warns. Impulses are vertical. |
|
the axes. There is no |
|
warn and are ignored. |
Segments
ax.vlines(x, ymin, ymax) and ax.hlines(y, xmin, xmax) are line datasets: one per distinct colour, line style and width, with a missing value (*) between segments. The arguments are listed in the API reference for Axes.vlines. GLE breaks a line at * and drops a nan row, joining its neighbours, so ax.plot and ax.step write a NaN in a drawn line as *: the line breaks there, as in matplotlib. So does a line whose data comes from a data_provider at savefig. Such a line is not smoothed by GLEGraphConfig(smooth_curves=True), which would fit one curve through the pieces.
argument |
gleplot |
|---|---|
a dash tuple in |
warns and is drawn solid. |
|
warn and are ignored. |
return value |
the axes. There is no |
|
the segments come back as |
Line keywords
plot, step, semilogx, semilogy and loglog take matplotlib’s short
names lw, ls, c, ms and mfc for linewidth, linestyle,
color, markersize and markerfacecolor (and, except step, which sets
the draw style from where, ds for drawstyle), and None for one of
them means the default, as in
matplotlib. matplotlib raises for a name passed with its short name; gleplot
keeps the full name, with a warning, unless the full name is left at its
default. A linewidth that is NaN, infinite or negative raises
ValueError at the call, on these and the other line-drawing calls below,
line_from_file, function and hist(histtype='step'), where
matplotlib does not check it. So does a NaN or infinite position or edge on
axhline, axvline, axhspan or axvspan, which matplotlib draws as nothing.
GLE has no zero-width stroke, so lw=0 on
plot (and step, stem, semilogx, semilogy, loglog), errorbar,
line_from_file, axhline, axvline, hlines and vlines draws no
line, as linestyle='none' does; errorbar still draws its error bars.
function and hist(histtype='step') are only their line, so lw=0
there warns and draws the default width.
A keyword GLE cannot draw, such as alpha, markeredgecolor (mec),
markeredgewidth (mew), dashes, transform or clip_on, warns and is
ignored, and so does a misspelt one:
UserWarning: plot() ignores unsupported keyword(s): alpha. scatter and
stem warn the same way, under their own names, for keywords they do not
take, lw, ls and ms included.
The other line-drawing calls follow the same rule:
call |
short names honoured |
warns, for example |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
A linestyle is '-', '--', ':' or '-.', or matplotlib’s name for
one: 'solid', 'dashed', 'dotted' or 'dashdot'. 'none' (or '',
' ', 'None') draws no line. GLE has no custom dash patterns, so a dash
tuple such as (0, (5, 2)) warns and is drawn solid, and so does a value
that is not a line style. This holds for plot and the calls above, for
line_from_file, hist(histtype='step'), and the single linestyles of
contour and tricontour. A (offset, None) tuple is matplotlib’s solid
line and is drawn solid without a warning. Passing None asks for
matplotlib’s default: a solid line from plot, axhline, axvline and
line_from_file, and the style fmt gives from errorbar.
plot(x, y, fmt), step(x, y, fmt) and errorbar(..., fmt=...) read
matplotlib’s format strings in the form GLE draws directly: a colour letter
(or 'C0' to 'C9'), a marker character and a line style, such as 'ro',
'k--' or '--s'. A marker with no line style draws no line. A color,
marker or linestyle keyword wins over the format, with a warning, as in
matplotlib. A format outside that subset, such as a colour name 'red',
warns and is ignored. errorbar(fmt='none') draws only the error bars, with
no markers even when marker= is given.
errorbar’s yerr and xerr take matplotlib’s shapes: a scalar, N values
(one symmetric error per point), or shape (2, N) (a lower row and an upper
row, such as a (lower, upper) tuple). gleplot used to read every
two-element sequence as (lower, upper): yerr=[0.1, 0.2] on two points drew 0.1
below and 0.2 above both, and on any other number of points it was spread
over every point. It is now one error per point on two points, as in
matplotlib, and raises ValueError on any other number of points; pass
yerr=([0.1] * N, [0.2] * N) for the old drawing.
Marker spacing, thinning and data ranges
GLE has no “mark every Nth point”. plot(markevery=...) warns and is ignored. Use mdist instead: it places the markers every mdist cm along the drawn curve, whatever the point spacing. That is closest to matplotlib’s float form of markevery. These keywords are gleplot’s names for GLE’s dataset qualifiers, and scatter passes them on to plot:
keyword |
GLE |
|---|---|
|
|
|
|
|
|
|
the series’ own data range: it is drawn as if its axes ran over that range, and nothing outside it is drawn. This rescales the series; it is not a clip window, and the tick labels keep the axis’ own range. An omitted edge is the limit of the axis the series is drawn against. |
A bad value raises ValueError at the call. A range GLE cannot draw warns when the figure is saved: a lone edge at or beyond the far axis limit (GLE fills the missing edge from that limit and stops with “invalid range”), or an edge at or below zero on a log axis. A series with its own deresolve gets no preview-only decimation. errorbar and errorbar_from_file take the data range, and draw their error bars against it too, but not mdist or deresolve: GLE thins the markers but not the whiskers under deresolve. open_gle keeps either one on an error-bar dataset that has it.
Scatter colours
ax.scatter(x, y, c=values, cmap='viridis', vmin=0, vmax=300) colours each point, as in matplotlib. A GLE dataset has one colour, so the script gets a glp_cdata_<marker>_<cmap> sub that draws each point in its own colour. Each point’s value comes from GLE’s mdata and is mapped onto the colormap by a let. The values go into the series’ data file as given. Where gleplot differs:
|
gleplot |
|---|---|
|
wired, with |
|
the same as |
|
one series per distinct colour, in the order each colour first appears. Only the first series carries |
|
warns and draws the colours, every point at the middle size: a GLE dataset carries one per-point value. Pass one size, or one colour. |
|
warn and are ignored, as in matplotlib. |
|
warns and is ignored: colours are always mapped linearly from |
fig.colorbar(ax=ax), or fig.colorbar() when only one axes has something to show, draws a bar for the axes’ colour-mapped scatter, from its vmin to its vmax. matplotlib’s fig.colorbar(sc) is not available: scatter returns the axes, not a mappable. See Colorbars.
Cells
ax.pcolormesh(X, Y, C) draws one flat colour per cell, with the cell edges where matplotlib puts them. It is a heatmap, so it is the axes’ one colormap, as imshow is. How gleplot writes it is in Contour Plots and Heatmaps.
|
gleplot |
|---|---|
|
wired. |
|
|
|
warn and are ignored: a GLE colormap is opaque and maps colours linearly from |
|
|
|
gleplot’s own: the bitmap resolution, as for |
axis limits beyond the mesh |
the edge cells show half a cell wider there, and saving warns; see Contour Plots and Heatmaps. |
Filled contours
ax.contourf(X, Y, Z, levels) fills the bands between levels by drawing a heatmap through a band palette; how, and when it falls back to a smooth heatmap, is in Contour Plots and Heatmaps. It returns the heatmap rather than a QuadContourSet; cf['levels'] holds the levels.
|
gleplot |
|---|---|
|
wired. |
|
|
levels closer together than 6 significant digits |
raise |
|
warn and are ignored: the bands are coloured from the colormap. |
|
warn and are ignored. |
|
gleplot’s own: the bitmap resolution, as for |
Heatmaps and contour lines
imshow and tripcolor take the arguments listed in their API entries. A NaN or masked cell in imshow’s Z raises ValueError rather than leaving the cell blank, as for pcolormesh: choose its value with np.ma.filled(Z, value). imshow’s extent gives the first and last grid nodes, where contour puts them, not the box the image fills: matplotlib’s pixels reach half a pixel past the outer centres, and gleplot’s colormap stops at those nodes. To match a matplotlib figure, pass the outer pixel centres as extent.
Every other keyword, such as alpha, norm or aspect, warns and is
ignored: a GLE colormap is opaque and one per axes (see “One Heatmap Per
Axes” in Contour Plots and Heatmaps).
contour and tricontour take matplotlib’s linewidth (lw) and
linestyle (ls) for linewidths and linestyles, one value each: GLE
draws every level as one dataset, so a per-level list of differing values,
or of colors, warns and its first entry is used. None for colors, linewidths or
linestyles means the default. Their other keywords
warn and are ignored, among them extent and origin: pass the grid’s
coordinates, contour(x, y, Z), to place it. A misspelt keyword warns the
same way.
matplotlib labels contours with a separate ax.clabel(cs) call; gleplot takes
clabel=True (and clabel_fmt) on contour and tricontour. The labels are
drawn by contour_labels from GLE’s contour.gle, which writes them in blue,
0.25 cm high, in a white box, whatever the line colour; matplotlib draws them
in the line’s colour.
The colormaps are GLE’s own: viridis, magma, inferno, plasma,
cividis, coolwarm, gray, rainbow (jet) and the ColorBrewer maps, and
their _r forms but rainbow_r. GLE draws the sequential and diverging
ColorBrewer maps in 9 or 11 steps where matplotlib blends them. rainbow_r and
jet_r warn and draw rainbow, and per-point scatter colours and contourf
bands draw rainbow as viridis; “Palette Gallery” in
Contour Plots and Heatmaps lists each one.
Line caps and joins
matplotlib caps and joins each line on its own; GLE sets them once for the
whole figure. Set them with GLEStyleConfig(line_cap=..., line_join=...),
described in the Configuration Guide. plot accepts
solid_capstyle, dash_capstyle, solid_joinstyle and dash_joinstyle with
matplotlib’s values. One that asks for what the figure already draws is
honoured; one that differs warns and is not applied. As in matplotlib, the
solid_* keywords concern a solid line and the dash_* ones a dashed line.
'projecting' is GLE’s square and 'miter' is its mitre. With nothing
set, GLE draws butt caps and mitre joins, not matplotlib’s projecting solid
caps and round joins.
Bars
ax.bar(x, height) emits bar dN fill rgb255(31,119,180) color rgb255(31,119,180) lwidth 0: the first colour of the axes’ patch cycle (see Default colours), and no edge (see below). One GLE dataset has one face and one edge. A colour sequence therefore becomes one bar command per bar, and each of those carries an explicit width, because a one-point dataset has no gap for GLE to measure. A single colour, including the same colour repeated, stays one command.
edgecolor, linewidth and linestyle are the stroke: color, lwidth and lstyle. As in matplotlib, a bar has no edge unless one is asked for. GLE strokes every bar, and lwidth 0 alone is a black hairline, so a bar with no edge is stroked with that hairline in the colour under the edge (color C lwidth 0): the fill, or the face of a hatched bar. That is a bar given none of the three, and one given edgecolor='none', linestyle='none' or linewidth=0. Unlike matplotlib, linewidth or linestyle without edgecolor draws an edge, in GLE’s black. A hatched bar with color='none' has no face to match, and its outline is drawn in the hatch ink. color='none' is GLE’s CLEAR fill. With no edge it is drawn as a black outline, since GLE strokes every bar, and that warns. bottom stacks the bar from that baseline to bottom + height, written bar dTo from dFrom. A zero baseline is not written. ax.barh(y, width) emits horiz. Its thickness is height and defaults to GLE’s own derivation, not matplotlib’s 0.8. align='edge' warns and is drawn centered.
hatch is GLE’s pattern. Every GLE pattern is diagonal, so only these hatches have one: '/' is SHADE, '\\' is RSHADE and 'x' (or 'X') is GRID. Repeated ('//', 'xx', …) they are the 2 variants, at half the spacing; a longer run is no denser. '|', '-', '+', 'o', 'O', '.', '*' and any mix such as '/\\' warn, and those bars are drawn solid. A sequence gives one hatch per bar, like a colour sequence, and splits the call the same way. GLE’s fill is the hatch ink and background the colour under it, so ax.bar(x, h, color='yellow', hatch='//') emits fill BLACK pattern SHADE2 background YELLOW. As in matplotlib, the ink is edgecolor, or black when edgecolor is not given or is 'none', and color='none' is a CLEAR background. The legend swatch is hatched too. In a legend gleplot writes as a begin key block, the swatch hatches on white: there, background would colour the whole key. GLE’s hatch lines are thinner than matplotlib’s, and their spacing is fixed in centimetres.
yerr and xerr draw whiskers at the tip of each bar. A scalar or a length-n sequence is symmetric. Shape (2, n) is asymmetric (first row minus, second row plus); (2, 1) broadcasts. The whisker is a separate markerless error-bar series, because GLE’s horiz swaps axes only while drawing the bar and an err/herr dataset is not swapped. A vertical bar’s tip is (x, bottom + height). A horizontal bar’s tip is (left + width, y). yerr stays vertical and xerr stays horizontal, so barh(..., xerr=) is a herr along the length.
ecolor defaults to black. One colour is one series; a sequence of different colours is one series per bar. capsize is the cap width in points (errwidth / herrwidth). Leave it out and GLE draws its own cap, one third of the font height. capsize=0 is that same default: GLE reads a zero width as “not given”. There is no way to omit the cap. capsize_cm is the width in centimetres and overrides capsize. error_kw may set ecolor, capsize, capsize_cm and zorder (the last wins, then 0.01 is added so the whisker sits above the bar). Other error_kw keys, including elinewidth, warn and are ignored: a markerless error dataset does not carry lwidth, so the stem uses the line width already in force. The bar’s label is the only legend entry.
An autoscaled x axis now includes xerr, the way the y axis already included yerr. A horizontal whisker is not clipped by the xaxis gleplot writes. This applies to errorbar as well as to bars.
Two matplotlib calls with shifted x are two commands. GLE’s side-by-side group bar d1,d2 fill c1,c2, read from a script whose data file gleplot wrote, round-trips as one command (on a data file of your own the whole command stays raw GLE, see Opening GLE Files), dist included, and so do pattern and background when they give each dataset at most one pattern, a fill, and a background only under a pattern. 3d, style, side, top and notop have no series field; the whole command stays raw GLE.
call |
GLE |
|---|---|
|
|
|
one |
|
|
|
|
|
|
|
|
width stays a keyword. The third positional argument is color, as it has always been.
Not provided
GLE has no pie chart or box plot command, and gleplot does not build one out
of subroutines, so pie and boxplot are not provided: calling them raises
AttributeError, as for any other matplotlib name gleplot lacks. Earlier
versions drew them with gleplot’s own gleplot_wedge and gleplot_box
subroutines. A .gle file written with them still opens and compiles: the
subroutines and their calls are kept as raw GLE, with a note.
GLE has no broken axis either, so Figure.add_broken_xaxes,
add_broken_yaxes and BrokenAxes are gone. A logarithmic axis shows two
scales in one panel, and two subplots show two ranges. A .gle file an
earlier version wrote with a broken axis opens as its separate graphs, with
the seam marks and shared titles kept as raw GLE. A project saved with one
loads its segments as separate axes drawn over each other in its place, with
a warning.
Colorbars
fig.colorbar(im, ax=ax) takes the heatmap imshow, pcolormesh, tripcolor or contourf returned (a contourf’s bar shows its bands, but has no extend end caps; thinned ticks start at the first level rather than nearest zero; and with uneven levels each band’s room is in proportion to its range, ticked in equal steps, where matplotlib gives every band the same room and ticks the levels), so each axes of a grid can carry its own bar. On an axes with no heatmap, fig.colorbar(ax=ax) shows its colour-mapped scatter (scatter(..., c=values)); scatter returns the axes, so the scatter cannot be passed as mappable. The rest of the call differs from matplotlib. See “Colorbars” in Contour Plots and Heatmaps.
|
gleplot |
|---|---|
|
wired. |
|
warns and is ignored. The bar is drawn beside its heatmap’s or scatter’s axes. |
|
accepted. The grid always makes room for the bar. |
|
a GLE |
|
not accepted. Use |
a contour set as |
not supported: contour lines draw in one colour, so there is no scale to show. |
Polar axes
GLE has no polar axis. fig.add_subplot(projection='polar') hides the graph’s axes and draws a grid of rings and spokes with a glp_polar_grid call in layer 200, below the curves. The angle and radius labels are written by a glp_polar_labels call after the graph block. Both subroutines are defined once at the top of the script. Each curve’s data file keeps theta and r, and a let dK = dJ*cos(x),dJ*sin(x) turns them into the x and y GLE draws, so markers, line styles and legend entries work as on any axes. The x and y ranges are chosen so both axes have the same scale and the angle labels fit inside the frame; the rings stay round in a subplot that is not square.
ax = fig.add_subplot(projection="polar")
ax.plot(theta, r, marker="o", label="r")
ax.set_ylim(0, 2)
matplotlib |
gleplot |
|---|---|
|
same. |
|
same. A lower limit other than 0 raises |
|
not available. Rings are evenly spaced, at most five; spokes and angle labels are every 45°, counter-clockwise from the right; ring labels lie along 22.5°. |
|
does nothing: the polar grid is always drawn. |
|
raise |
|
same; every axes of the grid is polar. |
The figure-wide GLEGraphConfig(smooth_curves=True) does not apply to a polar axes: GLE would smooth the drawn x and y, which need not be in order. A figure’s sharex/sharey leaves a polar axes’ limits alone.
Histograms
ax.hist(samples, bins=20, range=(0, 1), histtype="step") keeps the samples in the data file. GLE bins them with let dK = hist dJ from 0 to 1 bins 20 and draws the counts. The heights are counts. The window is the data min and max when range is omitted, widened by half a unit when every finite sample is the same value, and it is always written into the let so GLE does not re-bin over the axis. A sample on the right edge falls in the last bin; samples outside the window are not counted. Non-finite and masked samples are dropped, with a warning that names them.
|
GLE |
|---|---|
|
|
|
|
|
warn, and draw the step outline in |
argument |
gleplot |
|---|---|
|
an integer, or equal-width edges. Unequal edges warn and are equalized over the first and last edge. |
|
warn and are ignored. The drawing stays counts from zero. |
|
warns unless it is |
|
warns. The histogram is vertical. |
|
sets the y axis to log. |
|
a step histogram can use it. A filled one warns and stays on the primary axis: |
|
a step histogram can use the top scale. A filled one warns and stays on the primary x axis: |
return value |
the axes. |
Fills
fill_between still emits fill dA,dB for two curves. Three other GLE fill forms are available.
call |
GLE |
|---|---|
|
|
|
|
|
|
|
one |
|
|
|
|
|
one |
ax.fill_between(x, y, where=(x > 0))
ax.fill_between(x, y, baseline="x1")
ax.fill(x, y, alpha=0.4)
ax.fill_betweenx(y, x, alpha=0.4)
ax.stackplot(x, y, y, labels=["a", "b"], baseline="sym")
argument |
gleplot |
|---|---|
|
a boolean array the same length as |
|
|
|
the same clip, in data coordinates. These are not |
|
warns and is ignored. |
|
as on |
|
cycled over the layers. Omitted, each layer takes the next colour of the axes’ line cycle, as in matplotlib (see Default colours). A |
|
|
|
the first polygon is drawn. The rest warn and are ignored. |
|
warn and are ignored. GLE fills the interior and does not stroke it. |
|
warns and is ignored, on |
|
unchanged: below 1 the colour is |
Saving
savefig writes the .gle script and, for a .pdf, .png, .eps, .svg
or .jpg name, compiles it with GLE.
|
gleplot |
|---|---|
|
wired — a PNG gets an alpha channel instead of a white background (GLE |
|
gleplot keyword, not a matplotlib one: the colours GLE draws become their grey level (GLE |
|
warn. The page is always the figure’s |
|
warn and are ignored, whatever the value: |
transparent and grayscale act when GLE compiles, so they warn when only
the .gle script is saved.
fig.savefig("plot.png", transparent=True)
fig.savefig("plot.pdf", grayscale=True)
Secondary axes
The right-hand scale is yaxis="y2" on a series or the ax.twinx() view, and ax.twiny() opens the top scale. Both are described in Axes and Legends.
Key Behavioral Differences
Primary output model is GLE script generation.
Saving to
.glealways works without external compiler.Saving to
.pdf,.png,.epsrequires a working GLE installation.Sidecar
.datfiles are generated for in-memory series unless file-based series methods are used.ax.grid(visible, which=, axis=, color=, linestyle=, linewidth=)maps to GLE’sxaxis grid(+xsubticks onforwhich='both'). A minor-only grid is not expressible and is normalized to both, with a warning.fontname=onset_xlabel,set_ylabelandset_titletakes a GLE font name ('texcmr','psh'), not a matplotlib family such as'serif'. GLE centres every title, solocother than'center'warns, as dofontweight,fontdictand the other text keywords. Unlike matplotlib,set_titlekeeps the size and pad of the previous call unless they are passed again.GLE has no separate top and right spines: the x line’s style is copied onto the top line and the y line’s onto the right one. Set
'x2'or'y2'withset_axis_lineto style those on their own. Hiding the top or right line withvisible=Falsealso removes the tick marks GLE mirrors there, and anytwiny/twinxscale drawn on that edge (which warns).Display strings follow matplotlib’s contract: plain text renders literally (
'lambda_tail'is not a subscript) and math is opt-in via$...$. Unlike matplotlib, a backslash outside$...$still opens GLE’s own text markup (r'\chi{}'), as do braced scripts ('T_{N}').A second or translucent
imshoworpcolormeshis not possible; see Contours and Heatmaps for why and what to use instead.ax.tick_paramshonourswhich,reset,direction,length,widthandcolor. Its other keywords (pad,labelsize,labelcolor,bottom,labelbottom,grid_*, …) warn and are ignored. GLE has no separate top and right ticks:axis='x'styles the top ticks too. Minor ticks with no colour of their own take the major ticks’ colour. On an axis with a grid, GLE’s grid lines are the ticks, so the tick marks are not written and saving warns. See Axes and Legends.imshowcolours an array; it does not show a picture read withimread. Place the image file itself withax.image(fname, extent=...); see Plot Types.An RGBA colour’s alpha is honoured by
histonly. Elsewhere the colour is drawn opaque and a warning says so: pass an RGB colour and use thealpha=keyword where the function has one (fill_between,fill,axhspan,axvspan). As in matplotlib,alpha=overrides the colour’s own alpha, and then nothing warns.A guide (
axhline,axvline,axhspan,axvspan) on an axis gleplot cannot range, because the axes has no data and no limit for it or its data collapses to one value, is drawn after the graph against the range GLE picks. It is then drawn above the data, the grid and the ticks rather than under them, and a line outside the frame is not clipped. Give the axes a limit withset_xlim/set_ylimto keep the guide under the data. See Reference Lines and Shaded Spans.A masked value (
numpy.ma) is read as NaN wherever matplotlib leaves a masked point out: the data ofplot,step,stem,scatter(x,y,cands), the heights andyerr/xerrofbarandbarh,errorbar,fill_between,fill_betweenx,hist,hlinesandvlines. It then behaves as a NaN does there: ascatterpoint with a NaN size and abarwhisker with a NaN error are left out, andhistwarns that it dropped the masked samples. As in matplotlib,fill,stackplotand thebarpositions andbottomuse the values under the mask.A line on a log axis leaves a negative point out and joins its neighbours, where matplotlib draws the line off the axis there; a zero goes down to the axis edge, as in matplotlib. Saving warns when a
plotorstepline has a negative value on a log axis. Set those values to NaN to break the line there, see Axes and Legends.
Migration Strategy
Port plotting code with minimal edits (
plt->glp).Validate scripts first by saving as
.gle.Add
data_prefixfor deterministic sidecar names in batch pipelines.Replace custom file parsers with
errorbar_from_file()/line_from_file()where possible.Add project-specific style defaults via
GlobalConfig.