Configuration Guide
This guide explains how to customize gleplot’s appearance and behavior through the configuration system.
Overview
gleplot provides three levels of configuration:
Global defaults - Applied to all new figures
Per-figure configuration - Applied to individual figures
Per-element settings - Applied to individual plot elements (lines, markers, etc.)
Global Configuration
Access and modify global defaults through GlobalConfig:
import gleplot as glp
# Modify global defaults
glp.GlobalConfig.style.font = 'texcmss' # TeX Computer Modern Sans Serif
glp.GlobalConfig.style.fontsize = 12
glp.GlobalConfig.graph.legend_position = 'tl'
# All new figures will use these settings
fig = glp.figure()
Copy-at-construction. A figure created with no explicit style=/graph=/
marker= takes an independent COPY of the current GlobalConfig values at
the moment it is constructed – not a live reference to GlobalConfig
itself. So the order above matters (set the global default, then create
the figure), and the reverse is also true: once fig = glp.figure() has
run, editing fig.style.font in place changes only fig – it cannot leak
into other figures, and it cannot write back into GlobalConfig.style
either. (This is the fix for a real bug in earlier gleplot releases, where
fig.style for a default-styled figure was GlobalConfig.style itself,
so an in-place edit on one figure silently changed every other
default-styled figure in the process.) An explicit style=/graph=/
marker= object you construct and pass in yourself is unaffected by this –
it is still stored by reference, as it always was.
Style Configuration (GLEStyleConfig)
Controls text and line rendering:
style = glp.GLEStyleConfig(
font='texcmss', # a GLE font name; see Available Fonts below
fontsize=10, # Points (default: 12)
default_linewidth=1.0, # Line width in points (default: 1.5)
default_color='BLUE', # Uncoloured lines (default: None, the colour cycle)
default_marker_color='BLUE', # Uncoloured markers (default: None, the cycle)
)
fig = glp.figure(style=style)
Available Fonts
font takes a GLE font name, not a family name such as 'helvetica', which
GLE rejects with invalid font name. Leave it empty (the default) for GLE’s
own default font. Common names:
texcmr,texcmss,texcmtt- TeX Computer Modern Roman, Sans Serif, Typewriterrm,ss,tt- Roman, Sans Serif, Typewriterpstr,psh,psc- PostScript Times-Roman, Helvetica, Courier
The font tables in the GLE manual
list every name. GLE’s Cairo backend, which draws SVG output and any figure
compiled with -cairo (semi-transparent colours, or savefig(..., cairo=True)),
cannot draw the PostScript fonts, and rm, ss and tt are PostScript fonts
too. gleplot compiles those figures with -cairo, so GLE draws such text in
texcmr instead, and saving warns. Use the TeX Computer Modern (texcm*)
fonts for figures drawn that way to choose the font yourself.
Line Styles
Customize how different line styles are rendered:
style = glp.GLEStyleConfig()
style.line_style_solid = 1 # `-` (solid)
style.line_style_dashed = 3 # `--` (dashed)
style.line_style_dotted = 2 # `:` (dotted)
style.line_style_dashdot = 6 # `-.` (dash-dot)
The numbers are GLE’s own lstyle codes, and they are not in
solid/dashed/dotted/dash-dot order: GLE renders 2 as dotted, 3 as dashed and 6
as dash-dot. The defaults above are the codes that match their names.
Line Caps, Joins and Dash Length
GLE sets how lines end, how they turn corners, and how long a dash is for the whole page, so these are figure-wide:
style = glp.GLEStyleConfig(
line_cap='round', # GLE `set cap`: 'butt', 'round' or 'square'
line_join='round', # GLE `set join`: 'mitre', 'round' or 'bevel'
dashlen=0.1, # GLE `set dashlen`, in cm
)
Each is None by default, which writes nothing and keeps GLE’s own butt caps,
mitre joins and 0.04 cm dash unit. The digits of an lstyle code are
multiples of dashlen. GLE does not lengthen dashes for a thicker line, so a
thick dashed line can read as dotted until dashlen is raised. matplotlib’s
per-line solid_capstyle and friends are covered in
Migrating from matplotlib.
LaTeX Labels (usetex)
usetex=True typesets every label with LaTeX, as matplotlib’s text.usetex
does, so a figure for a LaTeX document can share its fonts and math:
fig = glp.figure(style=glp.GLEStyleConfig(usetex=True))
ax = fig.add_subplot(111)
ax.set_xlabel(r'$\mu_0 H$ (T)')
fig.savefig('plot.pdf')
The script gets GLE’s set texlabels 1. Titles, axis labels, tick labels,
legend entries, text and annotate strings reach LaTeX as written: $...$
is LaTeX math rather than gleplot’s mathtext translation, and text outside it
must be valid LaTeX, so an underscore is \_ and a percent sign \%. Set
it when creating the figure: a label set before usetex was turned on keeps its GLE
markup. The font setting does not reach LaTeX labels, and their size is the
standard LaTeX size nearest fontsize.
Saving the .gle script needs nothing extra. Compiling needs a LaTeX
installation that GLE can run, and a LaTeX error fails the compile with
LaTeX’s message in the GLECompileError. PDF, EPS, PNG and JPG work; SVG
raises ValueError, because GLE cannot put LaTeX in SVG. GLE keeps LaTeX’s
working files in a .gle directory beside the script. Once the compile
succeeds, savefig removes the figure’s own files there, and the directory
if nothing else is left in it; pass keep_intermediates=True to keep them.
Graph Configuration (GLEGraphConfig)
Controls graph layout and rendering:
graph = glp.GLEGraphConfig(
scale_mode='auto', # 'auto' (default) or 'fullsize'; see Scale Modes
title_distance=None, # Default Axes.title_dist (cm)
xlabel_distance=None, # Default Axes.xlabel_dist (cm)
ylabel_distance=None, # Default Axes.ylabel_dist (cm)
legend_position='tr', # Legend position: 'tr', 'tl', 'br', 'bl', etc.
legend_offset_x=0.0, # Legend x-offset (cm)
legend_offset_y=0.0, # Legend y-offset (cm)
smooth_curves=False, # Spline-smooth lines (GLE `smooth`); opt-in
show_grid=False, # Default grid on new axes
)
fig = glp.figure(graph=graph)
Curve Smoothing (smooth_curves)
A line series is drawn as a polyline through your points. Straight segments join consecutive measurements; nothing is drawn that is not in the data.
smooth_curves=True opts into GLE’s smooth keyword instead, which draws a
fitted piecewise-cubic spline. The curve then passes near, not through, the
points: it overshoots steep steps and rings around noise. That is a model of
the data, not the data, so keep it off for anything meant to be read
quantitatively. The legitimate uses are cosmetic – a guide to the eye through
widely spaced points, or a densely sampled model curve where the spline and
the polyline are indistinguishable anyway.
# Per figure
fig = glp.figure(graph=glp.GLEGraphConfig(smooth_curves=True))
# Or globally, for every figure created afterwards
glp.GlobalConfig.graph.smooth_curves = True
The flag is per figure and is the default for every line series in it
(plot, line_from_file, and the line drawn by errorbar), except a
plot line broken by NaN, which warns and is drawn unsmoothed: a spline
would join its pieces. Fills and contour lines are never smoothed: GLE’s fill command takes no smooth
qualifier, and contour polylines come out of GLE’s own contouring of the
gridded surface, where splining would move the level off the surface it was
computed from.
Per-series smoothing
A plot() series can override the figure default, and can use GLE’s other
smoothing option, by setting two fields on the series itself:
ax.plot(x, y)
ax.lines[0]["smooth_mode"] = "smoothm" # 'none' | 'smooth' | 'smoothm'
ax.lines[0]["svg_smooth"] = 3 # Savitzky-Golay iterations
smooth_mode— leave it unset to followsmooth_curves; set it to override that one series.'smooth'is the piecewise-cubic fit described above, which is a fit of a function of x (gleplot sorts the series’ rows by x for it).'smoothm'is GLE’s multi-valued variant, for curves that have more than one y per x — a hysteresis loop, a closed contour; those keep their point order.'none'switches smoothing off for the series even when the figure default is on.svg_smooth— the number of passes of GLE’s 7-point Savitzky–Golay filter (an integer ≥ 1; unset means off). This is a filter of the values, not a fit through them, and is independent ofsmooth_mode: set both and both are applied.
Both are limited to plot() line series. Error bars and line_from_file
series still follow the figure-wide flag.
Behaviour change in 1.9.0. Before 1.9.0,
smooth_curvesdefaulted toTrue: every line gleplot drew was a spline through the data, and no figure showed the measured polyline unless its author had found the flag and turned it off. Figures regenerated with 1.9.0 render as polylines – visibly more angular between sparse points, with no overshoot past local maxima. That is the correct rendering. If a curve now looks jagged, the jaggedness is in the data and was previously being hidden.To reproduce a pre-1.9.0 figure exactly, ask for smoothing explicitly:
glp.figure(graph=glp.GLEGraphConfig(smooth_curves=True)), or oneglp.GlobalConfig.graph.smooth_curves = Trueat the top of the script to restore the old behaviour everywhere in it.
Point order
A series is drawn, and written to its .dat file, in the order you passed its
points – as in matplotlib. Consecutive points are joined in that order, so a
curve whose x is non-monotonic by design comes out as drawn: a hysteresis loop
closes, a parametric curve traces its parameter, a field sweep taken up and
back down shows both legs.
# A circle, parameterised by angle: x runs 1 -> -1 -> 1
t = np.linspace(0, 2 * np.pi, 200)
ax.plot(np.cos(t), np.sin(t))
Smoothing is the one exception. GLE’s smooth fits a piecewise cubic as
a function of x and needs the points in ascending x, so a series that will
actually be drawn with smooth – it draws a line and smooth_curves is on
– has its rows sorted by x (stably: points sharing an x keep their input
order). A closed or doubling-back curve cannot be smoothed meaningfully for
that reason; leave smooth_curves off for one, which is the default.
Sorting never applies to a series that draws no line (scatter), to
fill_between, or to line_from_file/errorbar_from_file (which reference
your file’s rows and write nothing).
Behaviour change in 1.9.0. Before 1.9.0,
plot()anderrorbar()sorted their points by ascending x before writing the data file – a habit left over from when smoothing was on by default. Any series with non-monotonic x was silently reordered, both on screen and on disk. Figures regenerated with 1.9.0 draw the points in the order they were given; a loop that previously came out torn into two overlapping arcs now closes. If a figure depended on the old ordering, sort before plotting:order = np.argsort(x); ax.plot(x[order], y[order]).
Draw order (zorder)
By default gleplot emits data series in a fixed layer stack (fills and guide bands at the back, reference lines next, then bars, lines, scatters, and error bars, with file-based series last). That stack matches the historical behaviour: markers and error bars stay on top of plain fit lines unless you say otherwise.
Pass matplotlib’s zorder on plot, scatter, or errorbar to
raise or lower a series relative to the others on the same axes. Higher
zorder is drawn on top in the compiled figure. When two series share the
same zorder, call order breaks the tie.
ax.errorbar(t, y, yerr=e, fmt='o', zorder=1, label='data')
ax.plot(t, y_fit, '--', zorder=2, label='fit') # dashed fit above markers
Guide calls (axvline, axhspan, …) keep their fixed under-data layer in
this release; use zorder on the data series when you need fits above
points.
Scale Modes
'auto'(default) - gleplot sizes and places every axes frame itself, from its subplot grid cell or itsadd_axesrect, leaving margins for labels and titles. Change the layout withfigsize,subplots_adjustoradd_axes.'fullsize'- A figure with a single axes, other than one made withadd_axes, leaves the graph size to GLE’sfullsizekeyword: the graph fills the page with no margins, so labels and titles may overlap the axes, andset_aspectcannot apply (it warns). This replaces the placement of a single-graph file opened withopen_gletoo. A figure with several axes, or an axes made withadd_axes, keeps gleplot’s layout as under'auto'.'fixed'- Has no effect and warns: the figure is written exactly as under'auto'.
Any other value raises ValueError.
Legend Positions
legend_position takes GLE’s two-letter key positions ('tr', 'tl', …) or
the long forms such as 'top right'. The full list is under
GLEGraphConfig.legend_position in the
configuration API reference.
Marker Configuration (GLEMarkerConfig)
Controls marker/symbol appearance:
marker_cfg = glp.GLEMarkerConfig(
default_marker='fcircle', # Default marker type
msize_scale=1.0, # Marker size scaling factor
mdist=None, # cm between markers on marked lines (None = every point)
)
fig = glp.figure(marker=marker_cfg)
Available Markers
Standard markers (matplotlib-compatible):
'o','circle'- Circle's','square'- Square'^','triangle'- Triangle'd','diamond'- Diamond'+','cross'- Cross
GLE-specific markers:
'fcircle'(default) - Filled circle'fsquare'- Filled square'ftriangle'- Filled triangle'fdiamond'- Filled diamond'wcircle'- White-filled circle'wsquare'- White-filled square'wtriangle'- White-filled triangle'wdiamond'- White-filled diamond
Usage Examples
Example 1: Change Global Defaults
import gleplot as glp
# Set global defaults
glp.GlobalConfig.style.font = 'texcmss' # TeX Computer Modern Sans Serif
glp.GlobalConfig.style.fontsize = 12
glp.GlobalConfig.graph.legend_position = 'tl'
# Create figure (uses global defaults)
fig = glp.figure()
ax = fig.add_subplot(111)
x = [1, 2, 3, 4, 5]
y = [1, 4, 9, 16, 25]
ax.plot(x, y, 'b-', label='Data')
ax.set_xlabel('X')
ax.set_ylabel('Y')
ax.legend()
fig.savefig('plot.pdf')
Example 2: Per-Figure Configuration
style = glp.GLEStyleConfig(
font='texcmtt', # TeX Computer Modern Typewriter
fontsize=10,
default_linewidth=2.0,
)
graph = glp.GLEGraphConfig(
legend_position='br',
)
fig = glp.figure(figsize=(10, 6), style=style, graph=graph)
ax = fig.add_subplot(111)
# ... plot commands ...
Example 3: Different Styles for Different Figures
# Figure 1: Publication (serif font, small labels)
pub_style = glp.GLEStyleConfig(
font='texcmr', # TeX Computer Modern Roman
fontsize=8,
default_linewidth=1.5,
)
fig1 = glp.figure(style=pub_style)
# Figure 2: Presentation (sans-serif, larger labels)
pres_style = glp.GLEStyleConfig(
font='texcmss', # TeX Computer Modern Sans Serif
fontsize=14,
default_linewidth=2.0,
)
fig2 = glp.figure(style=pres_style)
Example 4: Tight Layout with No Margins
graph = glp.GLEGraphConfig(scale_mode='fullsize')
fig = glp.figure(graph=graph)
ax = fig.add_subplot(111)
# Plot + legends/labels will be in graph coordinate space
# (May require manual positioning to avoid overlaps)
Accessing Current Configuration
Get the current configuration of a figure:
fig = glp.figure()
# Access style config
print(f"Font: {fig.style.font}")
print(f"Font size: {fig.style.fontsize}")
# Access graph config
print(f"Scale mode: {fig.graph.scale_mode}")
print(f"Legend position: {fig.graph.legend_position}")
# Access marker config
print(f"Default marker: {fig.marker_config.default_marker}")
Layout and Output Naming Configuration
Margins and panel spacing (subplots_adjust) are in
Figures and Subplots.
Data Sidecar Naming with data_prefix
Set a figure-level data_prefix for deterministic sidecar .dat filenames in
batch workflows.
import gleplot as glp
import numpy as np
x = np.linspace(0, 1, 50)
fig = glp.figure(data_prefix='run42')
ax = fig.add_subplot(111)
ax.plot(x, x**2)
fig.savefig('run42_result.gle')
Typical side files:
run42_0.datrun42_1.dat(if additional series are generated)
subplots takes data_prefix too:
fig, axes = glp.subplots(2, 1, sharex=True, data_prefix='experimentB')
For semantic per-series names, pass data_name to generated-data methods such
as plot() and fill_between(). The label is sanitized into a filename stem
(lowercased, punctuation collapsed to underscores), and reused names are
disambiguated with _1, _2, and so on:
ax.plot(x, y_obs, data_name='Observed Signal') # observed_signal.dat
ax.fill_between(x, y_lo, y_hi, data_name='Confidence Band 95') # confidence_band_95.dat
Allowed characters
The prefix is used verbatim, so the sidecar names stay predictable —
data_prefix='experimentA' yields experimentA_0.dat, not experimenta_0.dat.
In exchange it is validated when the figure is created, and an unusable prefix
raises ValueError immediately instead of producing a .gle script that fails
at compile time:
glp.figure(data_prefix='mk+white')
# ValueError: data_prefix 'mk+white' contains characters that cannot appear
# in a GLE data filename: '+' at index 2. ...
Rejected: whitespace, control characters, and !, ", + (GLE cannot parse
these in the unquoted filename of a data statement), plus the path separators
/ and \. An empty or whitespace-only prefix is rejected too; pass None for
the default data_N.dat naming.
Most other punctuation is allowed, including ., -, _ and #. Note that
data_name behaves differently: it takes a free-form label and sanitizes it
into a filename stem, because no caller depends on its exact spelling.
Number precision
Sidecar numbers are written with 6 significant figures. A column that 6 figures
would damage (two distinct values written alike, a value such as 1e-12
written 0, or a value above 1e10 shortened) is written with as many
figures as it needs instead, and so is an axis range set with set_xlim or
set_ylim. Unix timestamps are the common case:
fig = glp.figure(data_prefix='stamps')
ax = fig.add_subplot(111)
ax.plot([1.7e9, 1.7e9 + 60, 1.7e9 + 121], [1, 2, 3])
fig.savefig('stamps.gle') # stamps_0.dat holds 1700000000, 1700000060, ...
Only a difference larger than a millionth of the range a column covers counts.
A densely sampled curve keeps 6 figures where neighbouring samples near a peak
round alike, and floating-point noise such as np.cos(np.pi / 2) in a column
of values near 1 is still written 0. A column of nothing but noise is written
as it is, as matplotlib plots it.
A lone number in data units is held to a millionth of its axis’s range instead.
This covers a text position, a reference line or span (drawn in the graph or
after it), a tick position from set_xticks (including ftick), a rug tick, a
column holding one value (a lone bar, say, or a histogram’s samples), a
histogram’s bin window, and a single axis limit. Numbers whose spread is too
small to count beside their size, such as the edges of a band 0.001 wide at
1.7e9, are held the same way. On the axis above, ax.axvline(1.7e9 + 30) is
written 1.70000003e+09 rather than 1.7e+09. On a log axis these numbers
keep 6 figures. So do the coordinates of placed images.
Resetting to Defaults
Reset all global configurations to defaults:
glp.GlobalConfig.reset()
Configuration Objects Reference
Every field of GLEStyleConfig, GLEGraphConfig, GLEMarkerConfig and
GlobalConfig, with its default, is in the
configuration API reference.
Performance Notes
Configuration objects are lightweight and can be created/modified freely without
performance impact. Configurations are only used during GLE script generation
(when calling savefig()), not during plot creation.
Troubleshooting
“GLE compiler error: unknown option”
Some GLE versions may not support certain features
Check GLE version:
gle --versionRefer to your GLE manual for supported options
“invalid font name”
fontmust be a GLE font name such as'texcmr','ss'or'psh', not a family name such as'helvetica'See Available Fonts
“Overlapping labels with fullsize mode”
fullsizeleaves no automatic marginsUse
scale_mode='auto'(default) for automatic spacingOr manually adjust with
title_distance,xlabel_distance,ylabel_distance