API Reference
Module: gleplot
gleplot - Matplotlib-like plotting library for GLE
A Python library for creating scientific plots using matplotlib-like syntax that compiles directly to GLE (Graphics Layout Engine) format for publication- quality vector graphics.
Features
Matplotlib-compatible API (plot, scatter, bar, fill_between, errorbar)
Text annotations in data coordinates (text)
Subplots with flexible grid layouts (subplots, add_subplot)
Native vector graphics output (PDF, PNG, EPS)
Inline display in Jupyter notebooks (view)
Support for line styles, markers, and colors
Error bars (symmetric, asymmetric, horizontal)
Logarithmic scales
Legend and axis labels
Semantic per-series data file naming (data_name) and figure-level prefixes (data_prefix)
Direct GLE script generation
Usage
import gleplot as glp
fig = glp.figure(figsize=(8, 6)) ax = fig.add_subplot(111)
ax.plot([1, 2, 3], [1, 4, 9], ‘b-’, label=’quadratic’) ax.scatter([1, 2, 3], [1, 2, 3], color=’red’, label=’points’)
ax.set_xlabel(‘X axis’) ax.set_ylabel(‘Y axis’) ax.set_title(‘Example Plot’) ax.legend()
fig.savefig(‘output.pdf’) # Saves as PDF fig.savefig(‘output.gle’) # Saves as GLE script only fig.view() # Display inline in Jupyter notebook
Classes
- Figure
Matplotlib-like figure container
- Axes
Matplotlib-like axes for plotting
Functions
- figure(figsize=(8, 6), dpi=100)
Create a new figure
Core Classes
Figure
- class gleplot.Figure(figsize=(8, 6), dpi=100, style=None, graph=None, marker=None, sharex=False, sharey=False, data_prefix=None)[source]
Matplotlib-like figure for GLE plotting.
- Parameters:
figsize (tuple, optional) – Figure size (width, height) in inches. Default: (8, 6)
dpi (int, optional) – Dots per inch. Default: 100
style (GLEStyleConfig, optional) – Style configuration. If None, uses global default.
graph (GLEGraphConfig, optional) – Graph configuration. If None, uses global default.
marker (GLEMarkerConfig, optional) – Marker configuration. If None, uses global default.
sharex (bool)
sharey (bool)
data_prefix (str | None)
- subplots_adjust(*, left=None, right=None, bottom=None, top=None, wspace=None, hspace=None)[source]
Store subplot layout overrides (matplotlib-compatible API).
Parameters are normalized figure fractions except wspace/hspace, which follow matplotlib semantics (fraction of average subplot width/height).
- savefig_gle(filepath, **kwargs)[source]
Save figure as GLE script.
- Parameters:
filepath (str) – Output file path
**kwargs – Additional options
- Returns:
Path to created GLE file
- Return type:
Path
- savefig(filepath, format=None, dpi=None, **kwargs)[source]
Save figure as GLE script and/or compiled output.
- Parameters:
- Returns:
Path to output file (GLE script or compiled output)
- Return type:
Path
- view(dpi=None, format='png')[source]
Display the figure inline (in Jupyter notebooks) or save to a temporary file.
This method renders the figure to an image format and displays it if running in a Jupyter notebook or IPython environment. Otherwise, it saves to a temporary file and returns the path.
- Parameters:
dpi (int, optional) – Resolution in dots per inch. If None, uses figure’s dpi setting.
format ({'png', 'pdf'}, optional) – Output format. Default is ‘png’ for inline display.
- Returns:
Path to the generated file, or None when displayed inline in Jupyter.
- Return type:
Path or None
- Raises:
RuntimeError – If GLE compiler is not available.
Examples
>>> import gleplot as glp >>> fig = glp.figure() >>> ax = fig.add_subplot(111) >>> ax.plot([1, 2, 3], [1, 4, 9]) >>> fig.view() # Display in notebook
Notes
Requires GLE to be installed for compilation. In non-Jupyter environments, saves to a temporary file instead.
Axes
- class gleplot.Axes(figure, position=None)[source]
Matplotlib-like axes for plotting.
- plot(x, y, linestyle='-', color=None, marker=None, markersize=6, linewidth=1, label=None, yaxis='y', **kwargs)[source]
Plot line or scatter plot (if marker without line).
- Parameters:
x (array-like) – Data coordinates
y (array-like) – Data coordinates
linestyle (str) – Line style (‘-’, ‘–’, ‘:’, ‘-.’)
color (str, optional) – Color name or code (‘b’, ‘red’, etc.)
marker (str, optional) – Marker symbol (‘o’, ‘s’, ‘^’, etc.) - omit for line only
markersize (float) – Marker size (matplotlib convention, 1-100)
linewidth (float) – Line width
label (str, optional) – Legend label
yaxis (str, optional) – Which y-axis to use: ‘y’ (left, default) or ‘y2’ (right)
**kwargs – Additional matplotlib-compatible arguments
- Returns:
Line object (for compatibility)
- Return type:
Line2D
- errorbar(x, y, yerr=None, xerr=None, fmt='-', color=None, marker=None, markersize=6, linewidth=1, label=None, capsize=None, capsize_cm=None, yaxis='y', **kwargs)[source]
Plot data with error bars.
- Parameters:
x (array-like) – Data coordinates
y (array-like) – Data coordinates
yerr (scalar, array-like, or tuple of (lower, upper), optional) – Vertical error bar sizes. Can be: - scalar: constant symmetric error for all points - 1D array: per-point symmetric error - tuple (lower, upper): per-point asymmetric error bars
xerr (scalar, array-like, or tuple of (left, right), optional) – Horizontal error bar sizes. Same format as yerr.
fmt (str) – Format string for the line/marker (e.g., ‘-o’, ‘–s’, ‘none’)
color (str, optional) – Color name or code
marker (str, optional) – Marker symbol (‘o’, ‘s’, ‘^’, etc.)
markersize (float) – Marker size (matplotlib convention, 1-100)
linewidth (float) – Line width
label (str, optional) – Legend label
capsize (float, optional) – Width of error bar caps in matplotlib points (typical: 3-5). Automatically converted to GLE cm units (points * 0.0353). Default: None (no caps)
capsize_cm (float, optional) – Width of error bar caps directly in GLE cm units (typical: 0.05-0.15). If specified, this overrides capsize. Use this for direct control.
yaxis (str, optional) – Which y-axis to use: ‘y’ (left, default) or ‘y2’ (right)
**kwargs – Additional arguments
- Return type:
self
Examples
Symmetric vertical error bars:
>>> ax.errorbar(x, y, yerr=0.5)
Asymmetric vertical error bars:
>>> ax.errorbar(x, y, yerr=([0.2, 0.3], [0.5, 0.4]))
Both vertical and horizontal error bars:
>>> ax.errorbar(x, y, yerr=0.5, xerr=0.3)
- errorbar_from_file(data_file, x_col, y_col, yerr_col=None, color=None, marker='o', markersize=6, label=None, capsize=None, yaxis='y')[source]
Plot by referencing columns in an existing external data file.
This avoids writing generated
data_*.datfiles. Column indices are 1-based to match GLE conventions.
- line_from_file(data_file, x_col, y_col, color=None, linestyle='-', linewidth=1, label=None, yaxis='y')[source]
Plot a line by referencing columns in an external data file.
This avoids creating generated
data_*.datfiles for overlay lines. Column indices are 1-based to match GLE conventions.
- scatter(x, y, color=None, s=20, marker='o', label=None, yaxis='y', **kwargs)[source]
Create scatter plot.
- Parameters:
x (array-like) – Data coordinates
y (array-like) – Data coordinates
color (str, optional) – Point color
s (float) – Marker size (matplotlib convention)
marker (str) – Marker symbol
label (str, optional) – Legend label
yaxis (str, optional) – Which y-axis to use: ‘y’ (left, default) or ‘y2’ (right)
**kwargs – Additional arguments
- Return type:
self
- bar(x, height, color=None, label=None, **kwargs)[source]
Create bar chart.
Note: Due to GLE limitations, all bars in a chart use the same color. If a list of colors is provided, only the first color is used.
- Parameters:
x (array-like) – Bar positions or categories
height (array-like) – Bar heights
color (str or list of str, optional) – Bar color. If a list is provided, only the first color is used due to GLE limitations. Default is ‘red’.
label (str, optional) – Legend label (currently not supported by GLE for bar charts)
**kwargs – Additional arguments
- Return type:
self
Examples
>>> fig = glp.figure() >>> ax = fig.add_subplot(111) >>> categories = np.array([1, 2, 3, 4, 5]) >>> values = np.array([10, 24, 36, 18, 7]) >>> ax.bar(categories, values, color='blue') >>> fig.savefig('bar_chart.pdf')
- fill_between(x, y1, y2, color=None, alpha=0.3, label=None, **kwargs)[source]
Fill area between two curves.
- text(x, y, s, color=None, fontsize=None, ha='left', va='center', bbox=None, **kwargs)[source]
Add free-form text annotation in data coordinates.
- Parameters:
x (float) – Data coordinates.
y (float) – Data coordinates.
s (str) – Text to render.
color (str, optional) – Text color.
fontsize (float, optional) – Font size in points.
ha (str, optional) – Horizontal alignment: ‘left’, ‘center’, or ‘right’.
va (str, optional) – Vertical alignment placeholder for API compatibility.
bbox (dict, optional) – Optional text box settings. Supported key:
facecolor.
- grid(visible=True, **kwargs)[source]
Toggle grid (placeholder for future implementation).
- Parameters:
visible (bool)
Configuration Classes
GLEStyleConfig
- class gleplot.GLEStyleConfig(font='', fontsize=12, default_linewidth=1.5, default_color='BLUE', default_marker_color='BLUE', line_style_solid=1, line_style_dashed=2, line_style_dotted=3, line_style_dashdot=4)[source]
GLE rendering style configuration.
- Parameters:
- font
GLE font name (e.g., ‘times8’, ‘psagb’, ‘plti’). If None or empty string, uses GLE’s default font. Default: None
- Type:
str or None
- fontsize
Font size in points. Default: 12 (optimized for GLE/PDF readability)
- Type:
- default_linewidth
Default line width in points (unit: 1/72 inch). Default: 1.5 points ≈ 0.053 cm (increased for visibility in PDFs)
- Type:
- default_color
Default line/plot color (GLE color name). Default: ‘BLUE’
- Type:
- default_marker_color
Default marker color. Default: ‘BLUE’
- Type:
- line_style_solid
GLE line style for solid lines. Default: 1
- Type:
- line_style_dashed
GLE line style for dashed lines (–). Default: 2
- Type:
- line_style_dotted
GLE line style for dotted lines (:). Default: 3
- Type:
- line_style_dashdot
GLE line style for dash-dot lines (-.). Default: 4
- Type:
- font: str = ''
- fontsize: float = 12
- default_linewidth: float = 1.5
- default_color: str = 'BLUE'
- default_marker_color: str = 'BLUE'
- line_style_solid: int = 1
- line_style_dashed: int = 2
- line_style_dotted: int = 3
- line_style_dashdot: int = 4
GLEGraphConfig
- class gleplot.GLEGraphConfig(scale_mode='auto', title_distance=0.1, xlabel_distance=0.1, ylabel_distance=0.1, legend_position='tr', legend_offset_x=0.0, legend_offset_y=0.0, smooth_curves=True, show_grid=False)[source]
GLE graph configuration.
- Parameters:
- scale_mode
Graph scaling mode: ‘auto’ (auto-sizes and centers), ‘fixed’ (uses specified size), or ‘fullsize’ (axes fill entire box, no margins). Default: ‘auto’
- Type:
- title_distance
Distance (cm) from graph top to title. Default: 0.1
- Type:
- xlabel_distance
Distance (cm) from graph bottom to x-axis label. Default: 0.1
- Type:
- ylabel_distance
Distance (cm) from graph left to y-axis label. Default: 0.1
- Type:
- legend_position
Default legend position: ‘tl’, ‘tr’, ‘bl’, ‘br’, ‘tc’, ‘bc’, ‘lc’, ‘rc’, ‘cc’. Options: ‘top right’, ‘top left’, ‘bottom right’, ‘bottom left’, ‘center’. Default: ‘tr’ (top right)
- Type:
- legend_offset_x
Legend x-offset from position (cm). Default: 0.0
- Type:
- legend_offset_y
Legend y-offset from position (cm). Default: 0.0
- Type:
- smooth_curves
Enable smooth curve fitting on line plots (GLE smooth keyword). Default: True
- Type:
- show_grid
Show background grid. Default: False
- Type:
- scale_mode: str = 'auto'
- title_distance: float = 0.1
- xlabel_distance: float = 0.1
- ylabel_distance: float = 0.1
- legend_position: str = 'tr'
- legend_offset_x: float = 0.0
- legend_offset_y: float = 0.0
- smooth_curves: bool = True
- show_grid: bool = False
GLEMarkerConfig
- class gleplot.GLEMarkerConfig(default_marker='fcircle', msize_scale=1.0, mdist=None)[source]
Marker style configuration.
- default_marker
Default marker type when creating scatter plots. Options: ‘circle’, ‘square’, ‘triangle’, ‘diamond’, ‘cross’, ‘fcircle’, ‘fsquare’, ‘ftriangle’, ‘fdiamond’ (filled variants). Default: ‘fcircle’ (filled circle)
- Type:
- msize_scale
Scaling factor for marker sizes. Multiplies the msize value. Default: 1.0
- Type:
- mdist
Default marker distance (space between markers on continuous lines). If None, markers appear at every point. Default: None
- Type:
Optional[float]
- default_marker: str = 'fcircle'
- msize_scale: float = 1.0
GlobalConfig
- class gleplot.GlobalConfig[source]
Global gleplot configuration.
Provides singleton-like access to default configuration settings that apply to all new figures created.
Access style, graph, and marker configurations directly as class attributes:
Examples
>>> from gleplot.config import GlobalConfig >>> # Change default font globally >>> GlobalConfig.style.font = 'helvetica' >>> # All new figures will use this font
>>> # Or reset to defaults >>> GlobalConfig.reset()
Functions
- gleplot.figure(figsize=(8, 6), dpi=100, style=None, graph=None, marker=None, data_prefix=None)[source]
Create a new figure.
- Parameters:
figsize (tuple, optional) – Figure size (width, height) in inches. Default: (8, 6)
dpi (int, optional) – Dots per inch. Default: 100
style (GLEStyleConfig, optional) – Style configuration. If None, uses global default.
graph (GLEGraphConfig, optional) – Graph configuration. If None, uses global default.
marker (GLEMarkerConfig, optional) – Marker configuration. If None, uses global default.
data_prefix (str, optional) – Custom prefix for data file names (e.g., ‘test9’ creates ‘test9_0.dat’, ‘test9_1.dat’). If None, uses global counter with
data_prefix.
- Returns:
New figure object
- Return type:
Examples
Create a figure with default settings:
>>> fig = glp.figure()
Create a figure with custom style:
>>> style = glp.GLEStyleConfig(font='helvetica', fontsize=12) >>> fig = glp.figure(style=style)
Or modify global defaults:
>>> glp.GlobalConfig.style.font = 'helvetica' >>> fig = glp.figure() # Will use helvetica font
- gleplot.subplots(nrows=1, ncols=1, figsize=None, dpi=100, style=None, graph=None, marker=None, sharex=False, sharey=False, data_prefix=None)[source]
Create a figure and a set of subplots.
Convenience function matching
matplotlib.pyplot.subplots().- Parameters:
nrows (int, optional) – Number of rows of subplots. Default: 1
ncols (int, optional) – Number of columns of subplots. Default: 1
figsize (tuple, optional) – Figure size (width, height) in inches. If None, auto-scales based on grid size (6 inches per column, 4 inches per row).
dpi (int, optional) – Dots per inch. Default: 100
style (GLEStyleConfig, optional) – Style configuration.
graph (GLEGraphConfig, optional) – Graph configuration.
marker (GLEMarkerConfig, optional) – Marker configuration.
sharex (bool, optional) – If True, all subplots share the same x-axis. Only the bottom row will show x-axis labels and ticks. Default: False
sharey (bool, optional) – If True, all subplots share the same y-axis. Only the leftmost column will show y-axis labels and ticks. Default: False
data_prefix (str, optional) – Custom prefix for data file names (e.g., ‘test9’ creates ‘test9_0.dat’, ‘test9_1.dat’). If None, uses global counter with
data_prefix.
- Returns:
fig (Figure) – The figure object.
axes (Axes or list of Axes) – A single Axes if nrows*ncols == 1, otherwise a list of Axes arranged in row-major order.
Examples
Single plot:
>>> fig, ax = glp.subplots() >>> ax.plot(x, y)
2x2 grid:
>>> fig, axes = glp.subplots(2, 2, figsize=(12, 10)) >>> axes[0].plot(x, y1) # top-left >>> axes[1].scatter(x, y2) # top-right >>> axes[2].bar(x, y3) # bottom-left >>> axes[3].plot(x, y4) # bottom-right
Shared x-axis (stacked plots):
>>> fig, axes = glp.subplots(3, 1, sharex=True, figsize=(8, 12)) >>> # Only bottom subplot shows x-axis label and ticks
- gleplot.view(dpi=None, format='png')[source]
Display current figure inline (in Jupyter notebooks).
- Parameters:
dpi (int, optional) – Resolution in dots per inch. If None, uses figure’s dpi setting.
format ({'png', 'pdf'}, optional) – Output format. Default is ‘png’ for inline display.
- Returns:
Path to the generated file, or None when displayed inline in Jupyter.
- Return type:
Path or None
Examples
>>> import gleplot as glp >>> fig = glp.figure() >>> ax = fig.add_subplot(111) >>> ax.plot([1, 2, 3], [1, 4, 9]) >>> glp.view() # Display in notebook
Utilities
- gleplot.rgb_to_gle(color)[source]
Convert matplotlib color specification to GLE color name.
- Parameters:
color (str or tuple) – Matplotlib color (name, code, or RGB tuple)
- Returns:
GLE color name in uppercase
- Return type:
Examples
>>> rgb_to_gle('blue') 'BLUE' >>> rgb_to_gle('b') 'BLUE' >>> rgb_to_gle((0.0, 0.0, 1.0)) 'BLUE'
Compiler
- class gleplot.GLECompiler(gle_path=None)[source]
Wrapper for GLE command-line compiler.
- Parameters:
gle_path (str | None)
- compile(input_file, output_format='pdf', dpi=150, verbose=False)[source]
Compile GLE file to output format.
- Parameters:
- Returns:
Path to output file
- Return type:
Path
- Raises:
RuntimeError – If compilation fails