API Reference

glyphx.plot

glyphx.plot(x=None, y=None, kind='line', data=None, legend='top-right', **kwargs)

Unified high-level plotting function.

This is the quickest way to create a single chart. Specify kind plus x/y (or data for distribution charts) and GlyphX handles scaling, theming, rendering, and display automatically.

Parameters:

• x (list or None) – X-axis values. Not required for pie, donut, hist, box, or heatmap.

• y (list or None) – Y-axis values or raw data for distribution charts.

• kind (str) – Chart type. One of "line", "bar", "scatter", "pie", "donut", "hist", "box", "heatmap".

• data (list or None) – Explicit data array for hist / box / pie / donut (takes priority over y).

• legend (str) – Legend position ("top-right", "top-left", etc.) or False to suppress.

• **kwargs – Extra keyword arguments forwarded to the Series constructor (e.g. color, label, bins, linestyle) or to Figure (e.g. width, height, theme, xscale).

Returns:

The Figure object (auto-displayed unless auto_display=False).

Return type:

Figure

Examples

>>> plot([1, 2, 3], [4, 5, 6], kind="line", title="My Line")
>>> plot(y=[4, 5, 6], kind="bar")
>>> plot(data=[1, 3, 2, 2, 1, 4], kind="hist")

glyphx.plot3d

glyphx.plot3d(x=None, y=None, z=None, kind='scatter', data=None, title='', theme='default', auto_display=True, **kwargs)

Unified 3D plotting function — the fast path to any 3D chart type.

Parameters:

• x – Data arrays. For "surface" x and y are 1-D grid arrays and z is a 2-D matrix.

• y – Data arrays. For "surface" x and y are 1-D grid arrays and z is a 2-D matrix.

• z – Data arrays. For "surface" x and y are 1-D grid arrays and z is a 2-D matrix.

• kind – "scatter", "surface", "line", "bar3d".

• data – Alias for z (useful for surface: plot3d(data=Z_matrix))

• title – Chart title.

• theme – Theme name.

• auto_display – Call .show() automatically.

• **kwargs – Passed to the series constructor.

Returns:

Figure3D

Examples:

import numpy as np
from glyphx import plot3d

# 3D scatter
xs = np.random.randn(300)
plot3d(xs, np.random.randn(300), np.random.randn(300), kind="scatter")

# Surface
x = np.linspace(-3, 3, 40)
X, Y = np.meshgrid(x, x)
Z = np.sin(np.sqrt(X**2 + Y**2))
plot3d(x, x, Z, kind="surface", cmap="plasma", title="sin(r)")

glyphx.from_prompt

glyphx.nlp.from_prompt(prompt: str, df=None, api_key: str = None, model: str = 'claude-sonnet-4-20250514', auto_display: bool = True) → Figure

Generate a GlyphX Figure from a plain-English description.

Parameters:

• prompt (str) – Natural language description of the desired chart, e.g. "bar chart of monthly revenue grouped by region".

• df (pd.DataFrame | None) – DataFrame to plot. Column names, dtypes, and a sample are sent to the model so it can choose sensible x/y mappings.

• api_key (str | None) – Anthropic API key. Falls back to the ANTHROPIC_API_KEY environment variable.

• model (str) – Anthropic model name.

• auto_display (bool) – Auto-render and show the figure when True.

Returns:

A fully configured and rendered GlyphX Figure.

Return type:

Figure

Raises:

• ImportError – If the anthropic package is not installed.

• ValueError – If no API key is found.

• json.JSONDecodeError – If the model returns unparseable JSON (rarely happens; usually recoverable).

Examples:

# Simple — no data, just a chart type hint
fig = from_prompt("show me a sample line chart of sin(x)", auto_display=False)

# With a DataFrame
import pandas as pd
df = pd.DataFrame({"month": range(1,13), "sales": [120,135,98,...]})
fig = from_prompt("line chart of sales over time", df=df)

# Grouped bar
fig = from_prompt(
    "top 5 products by total revenue, grouped by region",
    df=sales_df,
)

Figure

class glyphx.Figure(width: int = 640, height: int = 480, padding: int = 50, title: str | None = None, theme: str | dict[str, Any] | None = None, rows: int = 1, cols: int = 1, auto_display: bool = True, legend: str | bool | None = 'outside-right', xscale: str = 'linear', yscale: str = 'linear')

Bases: object

Central class for creating and rendering GlyphX visualizations.

Every mutating method returns self so calls can be chained:

fig = (
    Figure(width=900)
    .set_theme("dark")
    .set_title("Monthly Revenue")
    .add(LineSeries(months, revenue, label="Revenue"))
    .annotate("Peak", x="Oct", y=5400)
    .share("report.html")
)

Parameters:

• width – Canvas width in pixels.

• height – Canvas height in pixels.

• padding – Inner margin between canvas edge and plot area.

• title – Optional title rendered above all plots.

• theme – Theme name (str) or custom theme dict.

• rows – Number of subplot rows.

• cols – Number of subplot columns.

• auto_display – Auto-render when plot() or __repr__ is called.

• legend – Legend position string, or False to suppress.

• xscale – "linear" or "log".

• yscale – "linear" or "log".

set_title(title: str) → Figure

Set the figure title and return self for chaining.

set_theme(theme: str | dict[str, Any]) → Figure

Apply a named theme or a custom dict and return self.

set_size(width: int, height: int) → Figure

Resize the canvas and return self.

set_xlabel(label: str) → Figure

Set the X-axis label and return self.

set_ylabel(label: str) → Figure

Set the Y-axis label and return self.

set_legend(position: str | bool | None) → Figure

Set legend position (or False to hide) and return self.

add_axes(row: int = 0, col: int = 0) → Axes

Create or retrieve the Axes at a grid position.

add(series: Any, use_y2: bool = False) → Figure

Add a series to the figure.

Returns self so calls can be chained:

fig.add(LineSeries(...)).add(BarSeries(...)).show()

line(x, y, color=None, label=None, linestyle='solid', width=2, yerr=None, xerr=None, use_y2=False, **kwargs) → Figure

Add a LineSeries. Returns self.

bar(x, y, color=None, label=None, bar_width=0.8, yerr=None, use_y2=False, **kwargs) → Figure

Add a BarSeries. Returns self.

scatter(x, y, color=None, label=None, size=5, c=None, cmap='viridis', use_y2=False, **kwargs) → Figure

Add a ScatterSeries. Returns self.

hist(data, bins=20, color=None, label=None, **kwargs) → Figure

Add a HistogramSeries. Returns self.

box(data, categories=None, color=None, box_width=20, **kwargs) → Figure

Add a BoxPlotSeries. Returns self.

heatmap(matrix, row_labels=None, col_labels=None, show_values=False, cmap=None, **kwargs) → Figure

Add a HeatmapSeries. Returns self.

pie(values, labels=None, colors=None, **kwargs) → Figure

Add a PieSeries. Returns self.

donut(values, labels=None, colors=None, **kwargs) → Figure

Add a DonutSeries. Returns self.

area(x, y1, y2=0, color=None, alpha=0.25, line_width=1, label=None, **kwargs) → Figure

Add a FillBetweenSeries. Returns self.

kde(data, filled=False, alpha=0.2, color=None, width=2, label=None, **kwargs) → Figure

Add a KDESeries. Returns self.

ecdf(data, color=None, label=None, complementary=False, **kwargs) → Figure

Add a ECDFSeries. Returns self.

raincloud(data, categories=None, seed=42, violin_width=40, **kwargs) → Figure

Add a RaincloudSeries. Returns self.

candlestick(dates, open, high, low, close, label=None, **kwargs) → Figure

Add a CandlestickSeries. Returns self.

waterfall(labels, values, show_values=True, **kwargs) → Figure

Add a WaterfallSeries. Returns self.

treemap(labels, values, cmap='viridis', show_values=True, **kwargs) → Figure

Add a TreemapSeries. Returns self.

bubble(x, y, size, color=None, c=None, cmap='viridis', alpha=0.65, min_radius=4, max_radius=40, labels=None, label=None, use_y2=False, **kwargs) → Figure

Add a BubbleSeries. Returns self.

sunburst(labels, parents, values, cmap='viridis', **kwargs) → Figure

Add a SunburstSeries. Returns self.

parallel_coords(data, axes, hue=None, cmap='viridis', alpha=0.45, **kwargs) → Figure

Add a ParallelCoordinatesSeries. Returns self.

diverging_bar(categories, values, pos_color='#2563eb', neg_color='#dc2626', show_values=True, **kwargs) → Figure

Add a DivergingBarSeries. Returns self.

stream(max_points=100, color=None, label=None, **kwargs) → Figure

Add a StreamingSeries and return it.

Unlike other shorthand methods, this returns the series (not self) so callers can push data to it:

stream = fig.stream(max_points=100, label="Sensor")
stream.push(42.0)

axhspan(ymin: float, ymax: float, color: str = '#facc15', alpha: float = 0.2, label: str | None = None) → Figure

Add a horizontal shaded band across the full chart width.

Equivalent to Matplotlib’s ax.axhspan(). Y values are in data space; the band is clipped to the plot area.

Parameters:

• ymin – Lower Y bound (data units).

• ymax – Upper Y bound (data units).

• color – Fill color.

• alpha – Fill opacity 0–1.

• label – Optional legend label.

Returns:

self for chaining.

Example:

fig.axhspan(90, 110, color="#22c55e", alpha=0.15, label="Target range")

axvspan(xmin, xmax, color: str = '#a855f7', alpha: float = 0.2, label: str | None = None) → Figure

Add a vertical shaded band across the full chart height.

Equivalent to Matplotlib’s ax.axvspan(). X values may be numeric data values or category label strings.

Parameters:

• xmin – Left X bound (data units or category label).

• xmax – Right X bound.

• color – Fill color.

• alpha – Fill opacity 0–1.

• label – Optional legend label.

Returns:

self for chaining.

Example:

fig.axvspan("Jul", "Sep", color="#f59e0b", alpha=0.15, label="Q3")

set_xticks(ticks: list, labels: list | None = None) → Figure

Set explicit X-axis tick positions (and optionally their labels).

Equivalent to Matplotlib’s ax.set_xticks() + ax.set_xticklabels().

Returns:

self for chaining.

Example:

fig.set_xticks([0, 25, 50, 75, 100])
fig.set_xticks([1, 6, 12], labels=["Jan", "Jun", "Dec"])

set_yticks(ticks: list, labels: list | None = None) → Figure

Set explicit Y-axis tick positions (and optionally their labels).

Returns:

self for chaining.

Example:

fig.set_yticks([0, 500_000, 1_000_000], labels=["$0", "$500k", "$1M"])

set_tick_format(formatter) → Figure

Apply a callable formatter to all numeric tick labels on both axes.

Equivalent to Matplotlib’s FuncFormatter.

Parameters:

formatter – Callable (value: float) -> str.

Returns:

self for chaining.

Example:

fig.set_tick_format(lambda v: f"${v:,.0f}")
fig.set_tick_format(lambda v: f"{v:.1%}")

set_minor_ticks(n: int = 4) → Figure

Draw minor tick subdivisions between each pair of major ticks.

Parameters:

n – Number of minor ticks between major ticks.

Returns:

self for chaining.

Example:

fig.set_minor_ticks(4)

set_spine_visible(left: bool = True, right: bool = True, top: bool = False, bottom: bool = True) → Figure

Control axis spine (border line) visibility.

Equivalent to Matplotlib’s ax.spines[...].set_visible().

Parameters:

• left – Left (Y) spine.

• right – Right (Y2) spine.

• top – Top spine.

• bottom – Bottom (X) spine.

Returns:

self for chaining.

Example:

fig.set_spine_visible(top=False, right=False)   # clean minimal look

text(x: float, y: float, s: str, color: str = '#333', font_size: int = 12, anchor: str = 'middle', transform: str = 'canvas') → Figure

Add free-form text anywhere on the canvas.

Equivalent to Matplotlib’s fig.text() / ax.text().

Parameters:

• x – X position. When transform='canvas' this is a fraction of canvas width (0–1). When transform='data' it is a data-space value.

• y – Y position. Canvas fraction (0 = top, 1 = bottom) or data-space value depending on transform.

• s – Text string. Use $...$ for math (rendered via MathJax when the chart is opened in a browser).

• color – Font color.

• font_size – Font size in points.

• anchor – SVG text-anchor: "start", "middle", "end".

• transform – "canvas" (0–1 fractions) or "data" (data coords).

Returns:

self for chaining.

Example:

fig.text(0.5, 0.02, "Source: World Bank", font_size=9, color="#888")
fig.text(0.5, 0.5, "$R^2 = 0.95$", font_size=14)

supxlabel(label: str, font_size: int = 13, color: str | None = None) → Figure

Set a shared X-axis label below all subplots.

Equivalent to Matplotlib’s fig.supxlabel(). Useful when all subplots in a grid share the same X-axis meaning.

Parameters:

• label – Label text.

• font_size – Font size.

• color – Text color (defaults to theme text color).

Returns:

self for chaining.

supylabel(label: str, font_size: int = 13, color: str | None = None) → Figure

Set a shared Y-axis label beside all subplots.

Equivalent to Matplotlib’s fig.supylabel().

Parameters:

• label – Label text.

• font_size – Font size.

• color – Text color (defaults to theme text color).

Returns:

self for chaining.

stacked_bar(x: list, series: dict, normalize: bool = False, colors: list | None = None, bar_width: float = 0.75, **kwargs) → Figure

Add a StackedBarSeries. Returns self.

bump(x: list, rankings: dict, colors: list | None = None, show_labels: bool = True, **kwargs) → Figure

Add a BumpChartSeries. Returns self.

sparkline(data: list, color: str = '#2563eb', kind: str = 'line', fill: bool = True, label: str | None = None, **kwargs) → Figure

Add a SparklineSeries. Returns self.

vline(x, color='#888', width=1, linestyle='dashed', label=None) → Figure

Draw a vertical reference line at data coordinate x. Returns self.

hline(y, color='#888', width=1, linestyle='dashed', label=None) → Figure

Draw a horizontal reference line at data coordinate y. Returns self.

copy() → Figure

Return a deep copy of this figure.

Useful for creating small variations without re-building from scratch:

base = Figure().add(LineSeries(x, y))
dark = base.copy().set_theme("dark")
light = base.copy().set_theme("default")

Returns:

A new Figure with all series, annotations, and settings duplicated.

annotate(text: str, x: float, y: float, color: str = '#333', font_size: int = 12, anchor: str = 'start', arrow: bool = False, ax_x: float | None = None, ax_y: float | None = None) → Figure

Add a text annotation in data-space coordinates.

Returns self for chaining.

Parameters:

• text – Label text.

• x – Data-space X coordinate of the annotation point.

• y – Data-space Y coordinate.

• color – Text and arrow colour.

• font_size – Label font size in points.

• anchor – SVG text-anchor ("start", "middle", "end").

• arrow – Draw a small leader line from text to point.

• ax_x – Arrow tail X pixel offset (default −8).

• ax_y – Arrow tail Y pixel offset (default −8).

to_alt_text() → str

Generate a plain-English description of this figure for screen readers.

Returns:

A human-readable string suitable for aria-label or <desc>.

render_svg(viewbox: bool = False) → str

Render the complete figure and return an SVG string.

The SVG includes: - role="img" and aria-labelledby on the root element - <title> and <desc> ARIA landmark children - tabindex="0" on every interactive data point

Returns:

Complete SVG document markup.

show() → Figure

Render and display the figure. Returns self for chaining.

save(filename: str = 'glyphx_output.svg', dpi: int = 96) → Figure

Save the rendered figure to disk.

Supported extensions: .svg, .html, .png, .jpg, .pptx. PNG/JPG/PPTX require optional extras:

pip install "glyphx[export]"    # PNG/JPG
pip install "glyphx[pptx]"      # PowerPoint

Parameters:

• filename – Output path. Extension determines the format.

• dpi – Output resolution for raster formats (PNG/JPG). Default 96; use 192 or 300 for high-DPI / print. Has no effect on SVG or HTML output.

Returns:

self for chaining.

Example:

fig.save("chart.png", dpi=192)   # crisp on retina displays
fig.save("chart.png", dpi=300)   # print-quality

tight_layout() → Figure

Auto-adjust padding to prevent label clipping and overlap.

For single-axis figures, delegates to tight_layout(). For subplot grids, applies constrained_layout() which aligns the left edges of all subplot cells so tick labels never overlap across rows.

Returns self for chaining.

constrained_layout() → Figure

Align subplot cells so their plot areas share a common left edge.

Equivalent to Matplotlib’s constrained_layout=True. Computes the widest Y-tick label across all cells in each column, then sets a uniform left padding for all cells in that column so the actual data area (to the right of the Y-axis) is flush.

Returns self for chaining.

Example:

fig = Figure(rows=2, cols=2, width=900, height=600)
# ... add_axes and add_series ...
fig.constrained_layout()   # aligns all subplot left edges

add_stat_annotation(x1: Any, x2: Any, p_value: float = 0.05, label: str | None = None, style: str = 'stars', color: str = '#222', y_offset: float = 0.0) → Figure

Add a significance bracket between two groups.

Draws *** / ** / * / ns above the bracket based on p_value. Works with both numeric and categorical X axes.

Parameters:

• x1 – First group (label or numeric X value).

• x2 – Second group.

• p_value – Statistical p-value.

• label – Override the auto-generated significance label.

• style – "stars" or "numeric".

• color – Bracket and text color.

• y_offset – Extra upward shift in pixels (stack multiple brackets).

Returns:

self for chaining.

enable_crosshair() → Figure

Enable the synchronized crosshair on the next share() / show() call.

The crosshair draws a vertical line across all GlyphX charts on the same HTML page and highlights the nearest data point in each.

Returns self.

share(filename: str | None = None, title: str | None = None) → str

Generate a fully self-contained, shareable HTML document.

The output embeds all JavaScript inline — no CDN, no server, works offline. Pass filename to also write it to disk.

Returns:

Complete HTML document string.

plot() → Figure

Shortcut for show() respecting auto_display. Returns self.

Figure3D

class glyphx.Figure3D(width: int = 900, height: int = 650, title: str = '', theme: str = 'default', azimuth: float = 45.0, elevation: float = 30.0, xlabel: str = 'X', ylabel: str = 'Y', zlabel: str = 'Z')

Bases: object

3D chart canvas.

Renders to self-contained HTML with interactive Three.js WebGL, or falls back to an orthographic SVG for static export.

Parameters:

• width – HTML canvas width ("100%" or pixel value).

• height – HTML canvas height.

• title – Chart title.

• theme – Theme name (same as Figure).

• azimuth – Initial camera azimuth in degrees (SVG and HTML).

• elevation – Initial camera elevation in degrees (SVG only).

• xlabel – X-axis label.

• ylabel – Y-axis label.

• zlabel – Z-axis label.

Example:

from glyphx import Figure3D
from glyphx.surface3d import Surface3DSeries
import numpy as np

x = np.linspace(-3, 3, 50)
y = np.linspace(-3, 3, 50)
X, Y = np.meshgrid(x, y)
Z = np.sin(np.sqrt(X**2 + Y**2))

fig = Figure3D(title="sin(r)", theme="dark")
fig.add(Surface3DSeries(x, y, Z, cmap="plasma"))
fig.show()

add(series: Any) → Figure3D

Add a 3D series and return self for chaining.

scatter(x, y, z, color='#2563eb', c=None, cmap='viridis', size=5, label=None, alpha=0.85) → Figure3D

Add a Scatter3DSeries. Returns self.

surface(x, y, z, cmap='viridis', alpha=0.9, wireframe=True) → Figure3D

Add a Surface3DSeries. Returns self.

line3d(x, y, z, color='#dc2626', width=2, linestyle='solid', label=None) → Figure3D

Add a Line3DSeries. Returns self.

bar3d(x, y, z, cmap='viridis', alpha=0.85, label=None) → Figure3D

Add a Bar3DSeries. Returns self.

set_xlabel(label: str) → Figure3D

set_ylabel(label: str) → Figure3D

set_zlabel(label: str) → Figure3D

set_view(azimuth: float, elevation: float) → Figure3D

Set the initial camera angle for SVG output.

render_svg() → str

Render a static orthographic SVG projection.

render_html() → str

Render a complete interactive HTML document with Three.js.

show() → Figure3D

Render and display. Uses Jupyter if available, else browser.

save(filename: str = 'glyphx3d.html') → Figure3D

Save the figure to disk.

.html → interactive Three.js WebGL viewer (default) .svg → static orthographic SVG

Returns self for chaining.

Axes

class glyphx.layout.Axes(width=600, height=400, padding=50, show_grid=True, theme=None, legend=None, xscale='linear', yscale='linear')

Bases: object

Manages axis scaling, tick rendering, and series layout within a plot.

Supports: - Dual Y-axes (primary and secondary) - Categorical X-axis labels - Linear and log-scale axes - Configurable tick counts and grid lines - Axis title / xlabel / ylabel labels

width

Plot area width in pixels.

Type:

int

height

Plot area height in pixels.

Type:

int

padding

Space from canvas edge to the plot area.

Type:

int

show_grid

Whether to render background grid lines.

Type:

bool

theme

Color and font styling dictionary.

Type:

dict

xscale

"linear" or "log".

Type:

str

yscale

"linear" or "log".

Type:

str

series

Series on the primary Y-axis.

Type:

list

y2_series

Series on the secondary Y-axis.

Type:

list

add(series, use_y2=False)

Proxy for add_series; allows Figure/Axes to share call syntax.

add_series(series, use_y2=False)

Register a series on the primary or secondary Y-axis.

Parameters:

• series (BaseSeries) – Any series with .x and .y attributes.

• use_y2 (bool) – If True, bind to the right-hand Y-axis.

axhspan(ymin: float, ymax: float, color: str = '#ffff00', alpha: float = 0.2, label: str | None = None) → Axes

Add a horizontal shaded band spanning the full plot width.

The band is drawn in data-space Y coordinates. Values outside the current Y domain are clipped to the plot boundary.

Parameters:

• ymin – Lower Y data value of the band.

• ymax – Upper Y data value of the band.

• color – Fill color.

• alpha – Fill opacity 0–1.

• label – Optional legend label.

Returns:

self for chaining.

Example:

ax.axhspan(90, 110, color="#22c55e", alpha=0.15, label="Normal range")

axvspan(xmin, xmax, color: str = '#a855f7', alpha: float = 0.2, label: str | None = None) → Axes

Add a vertical shaded band spanning the full plot height.

xmin / xmax may be numeric data values or category label strings (resolved to their numeric position).

Parameters:

• xmin – Left X data value of the band.

• xmax – Right X data value of the band.

• color – Fill color.

• alpha – Fill opacity 0–1.

• label – Optional legend label.

Returns:

self for chaining.

Example:

ax.axvspan("Jul", "Sep", color="#f59e0b", alpha=0.15, label="Summer")

compute_domain(series_list)

Compute (x_domain, y_domain) from a list of series.

Categorical string X-values are converted to numeric indices. The conversion is stored on the series as ._numeric_x so the original series.x is never mutated.

When multiple series each carry different categories (e.g. one bar per group from a groupby aggregation), all unique categories are merged into a single global ordering so each gets a distinct x position.

Parameters:

series_list (list) – Series objects with .x and .y.

Returns:

(x_domain, y_domain) each as (min, max) or

(None, None) if no valid data is found.

Return type:

tuple

finalize()

Compute all scale functions after series have been registered.

Must be called before any rendering method.

render_axes()

Render X, Y, and (if y2_series exist) Y2 axis lines plus labels.

Returns:

SVG elements for axes.

Return type:

str

render_grid(ticks=5)

Render tick marks, grid lines, and numeric labels.

Categorical X-axes replace numeric labels with the original category names.

Parameters:

ticks (int) – Number of major ticks per axis.

Returns:

SVG elements for grid and tick labels.

Return type:

str

set_minor_ticks(n: int, length: float = 2.0) → Axes

Draw n minor tick subdivisions between each pair of major ticks.

Parameters:

• n – Number of minor ticks between major ticks (e.g. 4 gives 5 equal sub-intervals).

• length – Minor tick length in pixels.

Returns:

self for chaining.

Example:

ax.set_minor_ticks(4)   # quarterly subdivisions on annual axis

set_spine_visible(left: bool = True, right: bool = True, top: bool = False, bottom: bool = True) → Axes

Control which axis spines (border lines) are visible.

By default the top spine is hidden (matches Matplotlib’s ax.spines best-practice for clean scientific plots).

Parameters:

• left – Show left (Y) spine.

• right – Show right (Y2) spine.

• top – Show top spine.

• bottom – Show bottom (X) spine.

Returns:

self for chaining.

Example:

ax.set_spine_visible(top=False, right=False)  # clean minimal look

set_tick_format(formatter) → Axes

Apply a callable formatter to all numeric tick labels.

The formatter receives a float and must return a string. It applies to both X and Y axes (use set_xticklabels / set_yticklabels to override one axis independently).

Parameters:

formatter – Callable (value: float) -> str.

Returns:

self for chaining.

Example:

ax.set_tick_format(lambda v: f"${v:,.0f}")
ax.set_tick_format(lambda v: f"{v:.1%}")

set_tick_length(length: float) → Axes

Set the major tick mark length in pixels (default: 4).

set_xticklabels(labels: list[str]) → Axes

Override X-tick display strings without changing positions.

set_xticks(ticks: list, labels: list[str] | None = None) → Axes

Set explicit X-axis tick positions.

Parameters:

• ticks – List of data-space positions where ticks should appear.

• labels – Optional list of strings to display instead of formatted values. Must be the same length as ticks.

Returns:

self for chaining.

Example:

ax.set_xticks([0, 25, 50, 75, 100])
ax.set_xticks([1, 6, 12], labels=["Jan", "Jun", "Dec"])

set_yticklabels(labels: list[str]) → Axes

Override Y-tick display strings without changing positions.

set_yticks(ticks: list, labels: list[str] | None = None) → Axes

Set explicit Y-axis tick positions.

Parameters:

• ticks – List of data-space positions.

• labels – Optional display labels (same length as ticks).

Returns:

self for chaining.

Example:

ax.set_yticks([0, 1_000_000, 2_000_000], labels=["$0", "$1M", "$2M"])

tight_layout() → Axes

Auto-adjust padding so tick labels, axis labels, and titles don’t clip or overlap.

Estimates pixel widths of the longest tick labels and increases self.padding accordingly. Also triggers auto-rotation of crowded X-axis labels.

Returns self for chaining.

layout.grid

glyphx.layout.grid(figures, rows=1, cols=1, gap=20)

Arrange multiple Figure instances in a grid and return a single HTML page.

Parameters:

• figures (list[Figure]) – GlyphX Figure objects to arrange.

• rows (int) – Number of rows in the grid.

• cols (int) – Number of columns.

• gap (int) – Pixel margin around each subplot.

Returns:

Full HTML document with all SVGs embedded.

Return type:

str

SubplotGrid

class glyphx.figure.SubplotGrid(rows: int, cols: int)

Bases: object

Standalone 2-D grid for laying out existing Figure objects into one page.

Example:

sg = SubplotGrid(2, 2)
sg.add(fig_revenue, 0, 0)
sg.add(fig_costs,   0, 1)
html = sg.render()
open("dashboard.html", "w").write(html)

Parameters:

• rows – Number of rows.

• cols – Number of columns.

add(figure: Figure, row: int, col: int) → SubplotGrid

Place a Figure at a grid position. Returns self.

add_axes(row: int, col: int, figure: Figure) → SubplotGrid

Alias for add() kept for backward compatibility.

render(gap: int = 20) → str

Render all figures into a self-contained HTML page.

Returns:

Full HTML document string.

Core Series

class glyphx.series.BaseSeries(x, y=None, color=None, label=None, title=None)

Bases: object

Base class for all GlyphX series.

x

X-axis values.

Type:

list

y

Y-axis values (None for chart types that don’t use axes).

Type:

list

color

Primary color for this series.

Type:

str

label

Legend / tooltip label.

Type:

str | None

title

Per-series subtitle drawn above the chart area.

Type:

str | None

css_class

CSS class applied to interactive SVG elements.

Type:

str

class glyphx.series.LineSeries(x, y, color=None, label=None, legend=None, linestyle='solid', width=2, title=None, yerr=None, xerr=None, threshold=None)

Bases: BaseSeries

Line chart series with optional error bars.

Parameters:

• x (list) – X values.

• y (list) – Y values.

• color (str | None) – Line/point color.

• label (str | None) – Legend label.

• linestyle (str) – "solid", "dashed", "dotted", or "longdash".

• width (int) – Stroke width in pixels.

• title (str | None) – Chart subtitle.

• yerr (list | None) – Symmetric Y error bar values (same length as y).

• xerr (list | None) – Symmetric X error bar values (same length as x).

to_svg(ax, use_y2=False)

class glyphx.series.BarSeries(x, y, color=None, label=None, legend=None, bar_width=0.8, title=None, yerr=None)

Bases: BaseSeries

Bar chart series with optional error bars.

Parameters:

• x – X-axis labels/values.

• y – Bar heights.

• color – Fill color.

• label – Legend label.

• bar_width (float) – Fraction of available slot width (0–1).

• title – Per-series subtitle.

• yerr – Symmetric Y error values.

to_svg(ax, use_y2=False)

class glyphx.series.ScatterSeries(x, y, color=None, label=None, legend=None, size=5, marker='circle', title=None, c=None, cmap='viridis', threshold=None)

Bases: BaseSeries

Scatter plot with configurable marker type, size, and continuous color encoding.

Parameters:

• marker (str) – "circle" or "square".

• size (int) – Marker radius / half-width in pixels.

• c (list | None) – Per-point values for color encoding. When set, each point’s color is determined by mapping this value through cmap. Overrides color.

• cmap (str) – Colormap name (default: "viridis"). See list_colormaps() for options.

to_svg(ax, use_y2=False)

class glyphx.series.HistogramSeries(data, bins=10, color=None, label=None)

Bases: BaseSeries

Frequency distribution histogram.

Parameters:

• data (array-like) – Raw numeric values.

• bins (int) – Number of histogram bins.

• color – Bar fill color.

• label – Legend label.

to_svg(ax, use_y2=False)

class glyphx.series.BoxPlotSeries(data, categories=None, color='#1f77b4', label=None, box_width=20, width=None)

Bases: BaseSeries

Box-and-whisker plot.

Supports a single array (one box) or a list of arrays (multiple boxes drawn at categorical X positions).

Parameters:

• data (array-like or list of arrays) – Input data.

• categories (list | None) – Category labels for multiple boxes.

• color – Box fill color.

• label – Legend / tooltip label.

• box_width (int) – Pixel width of each box.

to_svg(ax, use_y2=False)

class glyphx.series.HeatmapSeries(matrix, cmap=None, row_labels=None, col_labels=None, show_values=False, **kwargs)

Bases: BaseSeries

Heatmap for 2-D matrix data with a color-scale legend.

Parameters:

• matrix (list[list[float]]) – 2-D data grid (rows × cols).

• cmap (list[str] | None) – Ordered list of hex colors (low → high).

• row_labels (list | None) – Row labels shown on the Y-axis.

• col_labels (list | None) – Column labels shown on the X-axis.

• show_values (bool) – Render numeric value inside each cell.

to_svg(ax, use_y2=False)

class glyphx.series.PieSeries(values, labels=None, colors=None, title=None, label_position='outside', radius=None)

Bases: BaseSeries

Pie chart series.

Parameters:

• values (list) – Numeric slice sizes.

• labels (list | None) – Label for each slice.

• colors (list | None) – Color per slice (cycles if fewer than slices).

• title (str | None) – Chart title rendered above the pie.

• label_position (str) – "outside" (default) or "inside".

• radius (float) – Explicit radius in pixels; auto-computed if None.

to_svg(ax=None)

class glyphx.series.DonutSeries(values, labels=None, colors=None, show_labels=True, hover_animate=True, inner_radius_frac=0.5)

Bases: BaseSeries

Donut (annular pie) chart series.

Parameters:

• values (list) – Numeric slice sizes.

• labels (list | None) – Label per slice; auto-generated if None.

• colors (list | None) – Color per slice.

• show_labels (bool) – Draw callout labels outside the ring.

• hover_animate (bool) – Add glyphx-point class for CSS hover.

• inner_radius_frac (float) – Hole radius as fraction of outer radius.

to_svg(ax=None)

Statistical Series

class glyphx.ecdf.ECDFSeries(data: list | ndarray, color: str | None = None, label: str | None = None, show_points: bool = False, point_radius: float = 3.0, line_width: float = 2.0, complementary: bool = False)

Bases: BaseSeries

Empirical CDF rendered as a step function.

Parameters:

• data – Raw observations (1-D array-like).

• color – Line color.

• label – Legend label.

• show_points – Draw a circle at each step.

• point_radius – Radius of step-point circles.

• line_width – Stroke width of the step line.

• complementary – If True, plot 1 − ECDF (survival function).

to_svg(ax: object, use_y2: bool = False) → str

Render the ECDF step function as SVG.

class glyphx.raincloud.RaincloudSeries(data: list, categories: list[str] | None = None, colors: list[str] | None = None, jitter_width: float = 18.0, point_radius: float = 3.0, violin_width: float = 40.0, box_width: float = 10.0, seed: int = 42, label: str | None = None)

Bases: object

Raincloud plot: jitter + half-violin + box for each category.

Parameters:

• data – List of 1-D arrays, one per category.

• categories – Category labels (same length as data).

• colors – Per-category colors; cycles if fewer than categories.

• jitter_width – Max horizontal pixel displacement of raw points.

• point_radius – Radius of each jittered data point.

• violin_width – Max pixel width of the half-violin.

• box_width – Pixel width of the IQR box.

• seed – Random seed for reproducible jitter.

• label – Legend label for the series.

to_svg(ax: object, use_y2: bool = False) → str

class glyphx.violin_plot.ViolinPlotSeries(data, positions=None, color='#1f77b4', width=50, show_median=True, show_box=True, label=None)

Bases: object

Violin plot: a KDE-smoothed distribution mirrored on both sides of a centre line.

Requires no external dependencies beyond NumPy.

Parameters:

• data (list of array-like) – One array per category.

• positions (list | None) – X-axis positions for each violin.

• color (str) – Fill/stroke color.

• width (int) – Maximum pixel half-width of the violin body.

• show_median (bool) – Draw a horizontal median marker.

• show_box (bool) – Overlay a thin IQR box inside the violin.

• label (str | None) – Legend label.

to_svg(ax, use_y2=False)

class glyphx.kde.KDESeries(data, n_points: int = 200, filled: bool = False, alpha: float = 0.2, color: str = '#1f77b4', width: int = 2, label: str | None = None, bw_method: str | float = 'silverman')

Bases: BaseSeries

Smooth kernel density estimate curve (no scipy required).

Parameters:

• data – 1-D array of raw observations.

• n_points – Number of evaluation points along the curve (default 200).

• filled – If True, shade the area under the curve.

• alpha – Fill opacity when filled=True (default 0.20).

• color – Line (and fill) color.

• width – Line stroke width in pixels.

• label – Legend label.

• bw_method – Bandwidth: "silverman" (default) or a positive float multiplier applied to the Silverman estimate.

to_svg(ax: object, use_y2: bool = False) → str

class glyphx.fill_between.FillBetweenSeries(x, y1, y2, color: str = '#1f77b4', alpha: float = 0.25, line_width: int = 1, label: str | None = None, line_color: str | None = None)

Bases: BaseSeries

Shaded area between two Y arrays (or between a line and a baseline).

Parameters:

• x – X values (shared by both bounds).

• y1 – Lower bound Y values, or the line when y2 is a scalar.

• y2 – Upper bound Y values. Pass a scalar (e.g. 0) to shade between y1 and a horizontal baseline.

• color – Fill and line color (default: "#1f77b4").

• alpha – Fill opacity 0–1 (default: 0.25).

• line_width – Width of the boundary lines in pixels. 0 hides them.

• label – Legend label.

• line_color – Color for boundary lines. Defaults to color.

to_svg(ax: object, use_y2: bool = False) → str

class glyphx.stat_annotation.StatAnnotation(x1: Any, x2: Any, p_value: float = 0.05, label: str | None = None, style: str = 'stars', color: str = '#222', line_width: float = 1.5, tip_len: float = 8.0, y_offset: float = 0.0)

Bases: object

Significance bracket drawn between two groups on a chart.

x1

First group label or numeric X value.

x2

Second group label or numeric X value.

p_value

The p-value for the test between the two groups.

label

Override text (defaults to significance stars).

style

"stars" or "numeric".

color

Line and text color.

line_width

Bracket stroke width.

tip_len

Vertical tick length at each bracket end.

y_offset

Extra upward pixel shift (stacks multiple brackets).

to_svg(ax: Any) → str

Render the bracket into SVG.

Parameters:

ax – A finalised Axes instance.

Returns:

SVG markup string, or empty string if the axes have no scale.

glyphx.stat_annotation.pvalue_to_label(p: float, style: str = 'stars') → str

Convert a p-value to a display label.

Parameters:

• p – The p-value (0–1).

• style – "stars" (default) or "numeric".

Returns:

"***", "**", "*", "ns" — or the formatted number.

Financial Series

class glyphx.candlestick.CandlestickSeries(dates: list, open: list[float], high: list[float], low: list[float], close: list[float], up_color: str = '#26a641', down_color: str = '#d73027', candle_width: float = 0.6, label: str | None = None)

Bases: BaseSeries

OHLC candlestick chart.

Parameters:

• dates – X-axis labels (e.g. date strings or numbers).

• open – Opening prices.

• high – High prices.

• low – Low prices.

• close – Closing prices.

• up_color – Fill color when close ≥ open (bullish).

• down_color – Fill color when close < open (bearish).

• candle_width – Fraction of the available slot width (0–1).

• label – Legend label.

to_svg(ax: object, use_y2: bool = False) → str

class glyphx.waterfall.WaterfallSeries(labels: list[str], values: list[float | None], up_color: str = '#2ca02c', down_color: str = '#d62728', total_color: str = '#1f77b4', bar_width: float = 0.6, connector: bool = True, show_values: bool = True, label: str | None = None)

Bases: BaseSeries

Waterfall (bridge) chart.

Parameters:

• labels – Category labels.

• values – Deltas to add at each step. Pass None for the last bar to auto-compute the running total.

• up_color – Fill for positive bars.

• down_color – Fill for negative bars.

• total_color – Fill for the auto-total bar.

• bar_width – Fraction of slot width used by each bar (0–1).

• connector – Draw dashed connector lines between bars.

• show_values – Print the delta value above each bar.

• label – Legend label.

to_svg(ax: object, use_y2: bool = False) → str

Hierarchical Series

class glyphx.treemap.TreemapSeries(labels: list[str], values: list[float], colors: list[str] | None = None, cmap: str = 'viridis', padding: float = 2.0, show_values: bool = True, min_font: int = 9, label: str | None = None)

Bases: object

Squarified treemap.

Parameters:

• labels – Category labels.

• values – Numeric values (determines rectangle area).

• colors – Per-label colors; if None, uses cmap.

• cmap – Colormap name used when colors is not supplied.

• padding – Gap between rectangles in pixels.

• show_values – Overlay the numeric value in each rectangle.

• min_font – Minimum font size; hides label if rect too small.

• label – Legend label (unused but kept for API consistency).

to_svg(ax: object = None) → str

Render the treemap into SVG rectangles.

class glyphx.sunburst.SunburstSeries(labels: list[str], parents: list[str], values: list[float], colors: list[str] | None = None, cmap: str = 'viridis', inner_radius: float = 40.0, ring_width: float = 60.0, padding_angle: float = 1.0, show_labels: bool = True, min_label_arc: float = 14.0, label: str | None = None)

Bases: object

Multi-ring sunburst chart.

The root node (parent == "") is drawn as the centre circle. Each subsequent ring represents one level of the hierarchy.

Parameters:

• labels – Node labels (unique identifiers).

• parents – Parent label for each node. Root node has "".

• values – Numeric value for each leaf node. Internal nodes can be 0 — their size is auto-summed from children.

• colors – Per-label hex colors. If None, cmap is used.

• cmap – Colormap for auto-coloring (default "viridis").

• inner_radius – Inner radius of the first ring (default 40 px).

• ring_width – Width of each ring in pixels (default 60).

• padding_angle – Gap between segments in degrees (default 1.0).

• show_labels – Render text inside each segment.

• min_label_arc – Minimum arc length in px to show a label.

• label – Legend label (unused but kept for API consistency).

to_svg(ax: object = None) → str

Streaming

class glyphx.streaming.StreamingSeries(max_points: int = 100, color: str | None = None, label: str | None = None, line_width: float = 2.0, show_points: bool = False)

Bases: BaseSeries

Sliding-window line series for real-time / streaming data.

Parameters:

• max_points – Maximum number of data points kept in the window.

• color – Line color.

• label – Legend label.

• line_width – Stroke width.

• show_points – Draw a dot at each data point.

live(fig: object, fps: float = 10.0) → _LiveContext

Context manager for live display in Jupyter.

Usage:

with stream.live(fig, fps=10) as s:
    for value in sensor_generator():
        s.push(value)

Parameters:

• fig – The Figure containing this series.

• fps – Target frames per second (throttles re-renders).

Returns:

Context manager that yields self.

push(value: float) → StreamingSeries

Append a new value to the stream.

Updates self.x and self.y so the parent Figure re-renders correctly on the next fig.render_svg() call.

Returns self for chaining:

stream.push(42.0).push(43.5)

Parameters:

value – New data value.

push_many(values: list[float] | ndarray) → StreamingSeries

Push multiple values at once. Returns self.

reset() → StreamingSeries

Clear the buffer and reset the tick counter. Returns self.

to_svg(ax: object, use_y2: bool = False) → str

Advanced 2-D Series

class glyphx.bubble.BubbleSeries(x, y, size, color: str | None = None, c=None, cmap: str = 'viridis', alpha: float = 0.65, min_radius: float = 4.0, max_radius: float = 40.0, labels: list | None = None, label: str | None = None, stroke: str = '#ffffff', stroke_width: float = 0.8, title: str | None = None)

Bases: BaseSeries

Scatter plot with circle area encoding a fourth variable.

Unlike ScatterSeries(size=fixed_int), this accepts a per-point size array and scales radii so the smallest bubble is always min_radius pixels and the largest is max_radius pixels.

Parameters:

• x – X-axis values.

• y – Y-axis values.

• size – Per-point numeric values mapped to bubble area. Can also be a fixed scalar to get uniform-sized bubbles without the colormap overhead.

• color – Flat fill color, or None when c= is used.

• c – Per-point values for color encoding (colormap).

• cmap – Colormap name (default "viridis").

• alpha – Fill opacity 0–1 (default 0.65).

• min_radius – Pixel radius of the smallest bubble (default 4).

• max_radius – Pixel radius of the largest bubble (default 40).

• labels – Per-point tooltip labels (list of str).

• label – Legend label for the series.

• stroke – Bubble outline color (default "#fff").

• stroke_width – Bubble outline width in pixels (default 0.8).

to_svg(ax: object, use_y2: bool = False) → str

class glyphx.parallel_coords.ParallelCoordinatesSeries(data, axes: list[str], hue: list | None = None, cmap: str = 'viridis', colors: dict | list | None = None, alpha: float = 0.45, line_width: float = 1.2, show_axes: bool = True, label: str | None = None)

Bases: object

Parallel coordinates plot for high-dimensional data.

Parameters:

• data – 2-D array-like (rows × variables).

• axes – Column / variable names (length must match data columns).

• hue – Per-row group labels for color coding. When provided, each unique value gets a distinct color from the theme or cmap. Pass a numeric array to use a continuous colormap instead.

• cmap – Colormap name used when hue holds numeric values, or when colors is not supplied (default "viridis").

• colors – Explicit hex color per unique hue group (dict or list).

• alpha – Line opacity 0–1 (default 0.45). Lower values help with overplotting.

• line_width – Stroke width (default 1.2).

• show_axes – Draw vertical axis lines and tick labels (default True).

• label – Legend label (unused but kept for API consistency).

to_svg(ax: object = None) → str

class glyphx.diverging_bar.DivergingBarSeries(categories: list[str], values: list[float], pos_color: str = '#2563eb', neg_color: str = '#dc2626', bar_height: float = 0.65, show_values: bool = True, zero_line: bool = True, label: str | None = None)

Bases: object

Horizontal diverging bar chart.

Parameters:

• categories – Category labels (one per bar, rendered on Y axis).

• values – Numeric values. Positive → right; negative → left.

• pos_color – Fill color for positive bars (default blue).

• neg_color – Fill color for negative bars (default red).

• bar_height – Fraction of available row height used by each bar (0–1).

• show_values – Render the numeric value at the end of each bar.

• zero_line – Draw a vertical reference line at zero.

• label – Legend label.

to_svg(ax: object = None) → str

class glyphx.grouped_bar.GroupedBarSeries(groups: list, categories: list, values: list[list[float]], group_colors: list[str] | None = None, bar_width: float = 0.8, label: str | None = None)

Bases: BaseSeries

Grouped bar chart: for each category on the X-axis, draws one bar per group side-by-side, each with a distinct color.

Parameters:

• groups – Category labels shown on the X-axis (outer grouping).

• categories – Series / group names (inner grouping — one bar per name).

• values – 2-D list values[group_i][cat_j].

• group_colors – Color per category (inner group). Auto-assigned if None.

• bar_width – Fraction of the available slot used by all bars together (0–1).

• label – Legend label (unused; individual category labels shown instead).

to_svg(ax: object, use_y2: bool = False) → str

class glyphx.swarm_plot.SwarmPlotSeries(data, categories=None, color='#1f77b4', size=4, jitter=6)

Bases: object

to_svg(ax, use_y2=False)

class glyphx.count_plot.CountPlotSeries(data, order=None, color='#1f77b4', bar_width=0.8)

Bases: object

to_svg(ax, use_y2=False)

3-D Series

class glyphx.scatter3d.Scatter3DSeries(x, y, z, color: str = '#2563eb', c: list | None = None, cmap: str = 'viridis', size: float = 5.0, label: str | None = None, alpha: float = 0.85, threshold: int | None = None)

Bases: object

3D scatter plot.

Parameters:

• x – Data coordinates (same length).

• y – Data coordinates (same length).

• z – Data coordinates (same length).

• color – Flat hex fill color when c is not used.

• c – Per-point numeric values for colormap encoding.

• cmap – Colormap name (default "viridis").

• size – Marker size in pixels / Three.js units.

• label – Legend / tooltip label.

• alpha – Point opacity 0–1.

to_svg(cam: Camera3D, x_range: tuple, y_range: tuple, z_range: tuple) → str

Render as SVG circles using the given camera projection.

to_threejs_data() → dict

Serialise series data for the Three.js HTML renderer.

class glyphx.surface3d.Surface3DSeries(x, y, z, cmap: str = 'viridis', alpha: float = 0.9, wireframe: bool = True, wire_color: str = '#ffffff44', label: str | None = None, threshold: int | None = None)

Bases: object

3D surface plot — z = f(x, y) over a regular grid.

Parameters:

• x – 1-D X grid values (length N).

• y – 1-D Y grid values (length M).

• z – 2-D Z matrix, shape (M, N). z[j][i] is the height at (x[i], y[j]).

• cmap – Colormap name (default "viridis").

• alpha – Surface opacity 0–1.

• wireframe – If True, draw grid lines over the surface.

• wire_color – Color of wireframe lines.

• label – Legend / tooltip label.

to_svg(cam: Camera3D, x_range, y_range, z_range) → str

Render each grid quad as a coloured SVG polygon.

Quads are sorted back-to-front by their average projected depth.

to_threejs_data() → dict

class glyphx.line3d.Line3DSeries(x, y, z, color: str = '#dc2626', width: float = 2.0, linestyle: str = 'solid', label: str | None = None, threshold: int | None = None)

Bases: object

3D line chart — a connected polyline through 3D coordinates.

Parameters:

• x – Path coordinates (same length, connected in order).

• y – Path coordinates (same length, connected in order).

• z – Path coordinates (same length, connected in order).

• color – Line color.

• width – Stroke width in pixels.

• linestyle – "solid", "dashed", "dotted".

• label – Legend label.

to_svg(cam: Camera3D, x_range, y_range, z_range) → str

to_threejs_data() → dict

class glyphx.bar3d.Bar3DSeries(x, y, z, dx: float | None = None, dy: float | None = None, cmap: str = 'viridis', alpha: float = 0.85, label: str | None = None)

Bases: object

3D bar chart — one rectangular bar per (x, y) grid cell, height = z.

Parameters:

• x – 1-D X positions (bar centres).

• y – 1-D Y positions (bar centres).

• z – 2-D Z matrix (heights), shape (len(y), len(x)), or 1-D if x and y are already paired point arrays.

• dx – Bar width along X (default: auto from grid spacing).

• dy – Bar depth along Y (default: auto from grid spacing).

• cmap – Colormap name for bar colours (mapped by height).

• alpha – Bar opacity.

• label – Legend label.

to_svg(cam: Camera3D, x_range, y_range, z_range) → str

to_threejs_data() → dict

class glyphx.contour.ContourSeries(x, y, z, levels: int | list[float] = 10, cmap: str = 'viridis', filled: bool = True, lines: bool = True, line_color: str = '#ffffff88', line_width: float = 0.8, alpha: float = 0.85, label: str | None = None)

Bases: BaseSeries

2D filled contour plot — iso-lines and/or filled bands.

Parameters:

• x – 1-D X grid values (length N).

• y – 1-D Y grid values (length M).

• z – 2-D Z matrix, shape (M, N).

• levels – Number of contour levels, or an explicit list of Z values.

• cmap – Colormap for fill bands.

• filled – Draw filled colour bands between levels.

• lines – Draw contour lines at each level.

• line_color – Color for contour lines when not filled.

• line_width – Contour line stroke width.

• alpha – Fill opacity.

• label – Legend label.

to_svg(ax: object, use_y2: bool = False) → str

Render filled contour bands using linear interpolation.

Downsampling

GlyphX data downsampling utilities.

SVG performance degrades visibly above ~5 000 points. GlyphX automatically downsamples before SVG generation using a suite of algorithms chosen per series type.

Algorithm summary

2-D line series : Two-stage M4 -> LTTB pipeline. 2-D scatter series: 2-D voxel grid thinning. 3-D line series : LTTB on vectorised camera-projected screen coords,

result cached in a WeakKeyDictionary keyed on camera state + data fingerprint.

3-D scatter series: 3-D voxel grid thinning. 3-D surface series: Per-axis grid decimation + sub-pixel face culling.

Performance notes

All hot paths are fully vectorised with NumPy: - LTTB : triangle-area computation uses slice broadcasting per bucket;

no Python loop inside the bucket scan.

• M4column assignment via np.digitize; min/max/first/last per

  column via np.minimum.reduceat / np.maximum.reduceat after a single argsort by column — no per-column Python list.

• Voxelnearest-centroid selection via np.minimum.reduceat after

  sorting by cell_id — avoids a full argsort on distance.

Global kill-switch

Call glyphx.downsample.disable() to turn off all downsampling. The flag lives in a threading.local so threads are independent.

Per-series control

Pass threshold=N to any series constructor to override AUTO_THRESHOLD.

Downsampling metadata

After rendering each series exposes series.last_downsample_info — a dict with keys algorithm, original_n, thinned_n.

glyphx.downsample.cull_faces(faces: list[tuple], min_area: float = 0.5) → list[tuple]

Remove projected quad faces whose screen area is below min_area px^2.

Fully vectorised NumPy shoelace computation.

glyphx.downsample.decimate_grid(x_1d: list | ndarray, y_1d: list | ndarray, z_mat: list[list[float]] | ndarray, max_faces: int = 5000) → tuple[ndarray, ndarray, ndarray]

Reduce a regular Surface3D grid by subsampling rows and columns.

Uses independent per-axis step sizes proportional to grid aspect ratio.

Raises:

ValueError – If z_mat shape does not match (len(y_1d), len(x_1d)).

glyphx.downsample.disable() → None

Disable all automatic downsampling on the current thread.

glyphx.downsample.enable() → None

Re-enable automatic downsampling on the current thread.

glyphx.downsample.is_enabled() → bool

Return True if downsampling is active on this thread.

glyphx.downsample.lttb(x: list | ndarray, y: list | ndarray, threshold: int) → tuple[ndarray, ndarray]

Largest-Triangle-Three-Buckets downsampling (Steinarsson 2013).

The per-bucket triangle-area scan is vectorised: for each bucket the areas of all candidate points are computed as a NumPy slice expression and np.argmax selects the winner — no Python loop inside the bucket.

Parameters:

• x – X values (1-D, numeric).

• y – Y values (1-D, numeric, same length as x).

• threshold – Maximum number of output points (>= 3).

Returns:

(x_down, y_down) – NumPy arrays of length <= threshold.

Raises:

ValueError – If lengths differ or threshold < 3.

glyphx.downsample.lttb_3d(x: list | np.ndarray, y: list | np.ndarray, z: list | np.ndarray, cam: Camera3D, threshold: int = 5000) → tuple[np.ndarray, np.ndarray, np.ndarray]

LTTB for a 3-D polyline in screen space.

Projects via vectorised NumPy transform, then runs the vectorised LTTB inner loop on screen coordinates. Result cached in a WeakKeyDictionary keyed on (camera-state, data-fingerprint).

Respects the thread-local kill-switch.

Raises:

ValueError – If x, y, z have different lengths.

glyphx.downsample.m4(x: list | ndarray, y: list | ndarray, pixel_width: int) → tuple[ndarray, ndarray]

M4 downsampling (Jugel et al. 2014).

Fully vectorised: column assignment uses np.digitize; per-column first/last/min/max are found with np.minimum.reduceat and np.maximum.reduceat after a single argsort by column — no per-column Python list or loop.

Requires monotone X values. Non-monotone input is auto-sorted with a UserWarning.

Parameters:

• x – X values (1-D, numeric, monotone).

• y – Y values (1-D, numeric, same length as x).

• pixel_width – Canvas width in pixels.

Returns:

(x_down, y_down) – NumPy arrays.

glyphx.downsample.maybe_downsample(x: list | ndarray, y: list | ndarray, threshold: int = 5000) → tuple[list | ndarray, list | ndarray]

Backward-compatible wrapper: LTTB only, no pixel width, no M4.

Deprecated since version Use: maybe_downsample_line instead.

glyphx.downsample.maybe_downsample_line(x: list | ndarray, y: list | ndarray, pixel_width: int = 800, threshold: int = 5000, m4_threshold: int = 50000) → tuple[ndarray | list, ndarray | list]

Two-stage downsampling pipeline for ordered 2-D line data.

Stage 1 – M4 : if n > m4_threshold, reduce via M4. Stage 2 – LTTB: if still > threshold, apply LTTB.

Respects the thread-local kill-switch.

glyphx.downsample.voxel_thin_2d(x: list | ndarray, y: list | ndarray, c: list | ndarray | None = None, max_points: int = 5000) → tuple[ndarray, ndarray, ndarray | None]

2-D voxel grid thinning for unordered scatter data.

For each occupied grid cell keeps the point nearest to the cell centroid. Uses np.minimum.reduceat after sorting by cell_id to find the nearest point per cell without a full distance argsort, reducing the dominant cost from O(n log n) to O(n log n) sort by cell + O(n) scan.

The dtype of c is preserved in the output.

Respects the thread-local kill-switch.

Parameters:

• x – Coordinates (1-D, same length).

• y – Coordinates (1-D, same length).

• c – Optional per-point values (threaded through).

• max_points – Target maximum output points.

Returns:

(x_thin, y_thin, c_thin)

Raises:

ValueError – If x and y have different lengths.

glyphx.downsample.voxel_thin_3d(x: list | ndarray, y: list | ndarray, z: list | ndarray, colors: list | None = None, max_points: int = 5000) → tuple[ndarray, ndarray, ndarray, list | None]

3-D voxel grid thinning for unordered scatter data.

Uses np.minimum.reduceat after sorting by cell_id to find the nearest-centroid point per voxel without a full distance argsort.

Respects the thread-local kill-switch.

Raises:

ValueError – If x, y, z have different lengths.

Note

maybe_downsample() is deprecated; use maybe_downsample_line() instead.

DataFrame Accessor

class glyphx.accessor.GlyphXAccessor(df: DataFrame)

Bases: object

Pandas DataFrame accessor that exposes the full GlyphX plotting API.

Registered automatically when glyphx is imported. Access via df.glyphx.<method>(...).

All methods return a Figure so results can be further customised via method chaining.

bar(x: str | None = None, y: str | None = None, color: str | None = None, label: str | None = None, yerr: str | None = None, groupby: str | None = None, hue: str | None = None, agg: str = 'sum', title: str | None = None, theme: str | dict | None = None, legend: str | bool | None = 'top-right', width: int = 640, height: int = 480, xlabel: str | None = None, ylabel: str | None = None, auto_display: bool = True, **kwargs: Any)

Create a bar chart from DataFrame columns.

Pass groupby or hue to create one series per unique group, each colored automatically from the theme palette. hue splits by a column while keeping x/y semantics; groupby aggregates.

Returns:

Figure

box(col: str | None = None, groupby: str | None = None, color: str | None = None, title: str | None = None, theme: str | dict | None = None, width: int = 640, height: int = 480, auto_display: bool = True, **kwargs: Any)

Create a box plot. Pass groupby for multi-box comparison. Returns Figure.

donut(labels: str | None = None, values: str | None = None, title: str | None = None, theme: str | dict | None = None, width: int = 480, height: int = 480, auto_display: bool = True, **kwargs: Any)

Create a donut chart. Returns Figure.

heatmap(title: str | None = None, theme: str | dict | None = None, width: int = 640, height: int = 480, auto_display: bool = True, **kwargs: Any)

Create a heatmap from the DataFrame’s numeric values.

The entire numeric portion of the DataFrame is treated as a 2-D matrix. Column names become column labels; index values become row labels.

Returns:

Figure

hist(col: str | None = None, bins: int = 10, color: str | None = None, label: str | None = None, title: str | None = None, theme: str | dict | None = None, width: int = 640, height: int = 480, xlabel: str | None = None, ylabel: str | None = None, auto_display: bool = True, **kwargs: Any)

Create a histogram of a numeric column. Returns Figure.

line(x: str | None = None, y: str | None = None, color: str | None = None, label: str | None = None, linestyle: str = 'solid', yerr: str | None = None, title: str | None = None, theme: str | dict | None = None, legend: str | bool | None = 'top-right', width: int = 640, height: int = 480, xlabel: str | None = None, ylabel: str | None = None, auto_display: bool = True, **kwargs: Any)

Create a line chart from DataFrame columns.

Parameters:

• x – Column name for X axis.

• y – Column name for Y axis.

• yerr – Column name for Y error bars (optional).

• label – Legend label; defaults to the y column name.

Returns:

Figure — fully chainable.

pie(labels: str | None = None, values: str | None = None, title: str | None = None, theme: str | dict | None = None, width: int = 480, height: int = 480, auto_display: bool = True, **kwargs: Any)

Create a pie chart. Returns Figure.

plot(kind: str = 'line', x: str | None = None, y: str | None = None, **kwargs: Any)

Unified entry point — mirrors glyphx.plot() but operates on the DataFrame’s columns.

Parameters:

• kind – Chart type (same values as glyphx.plot()).

• x – Column name for X axis (used for line/bar/scatter).

• y – Column name for Y axis (used for line/bar/scatter).

Returns:

Figure

scatter(x: str | None = None, y: str | None = None, color: str | None = None, label: str | None = None, size: int = 5, marker: str = 'circle', title: str | None = None, theme: str | dict | None = None, legend: str | bool | None = 'top-right', width: int = 640, height: int = 480, xlabel: str | None = None, ylabel: str | None = None, auto_display: bool = True, **kwargs: Any)

Create a scatter plot from DataFrame columns. Returns Figure.

Colormaps

glyphx.colormaps.apply_colormap(value: float, cmap: str | list[str] = 'viridis') → str

Map a scalar in [0, 1] to a hex color string.

Parameters:

• value – Normalised value between 0 and 1.

• cmap – Colormap name or a custom list of hex stops.

Returns:

Hex color string (e.g. "#3b528b").

glyphx.colormaps.colormap_colors(cmap: str, n: int) → list[str]

Sample n evenly-spaced colors from a colormap.

Parameters:

• cmap – Colormap name.

• n – Number of colors to return.

Returns:

List of hex color strings.

glyphx.colormaps.list_colormaps() → list[str]

Return names of all built-in colormaps.

glyphx.colormaps.get_colormap(name: str) → list[str]

Return the hex color stops for a named colormap.

Parameters:

name – Colormap name (case-insensitive).

Raises:

ValueError – If the name is not recognised.

glyphx.colormaps.render_colorbar_svg(cmap: str | list[str], vmin: float, vmax: float, x: float, y: float, width: float, height: float, font: str = 'sans-serif', text_color: str = '#000', steps: int = 24) → str

Generate an SVG colorbar strip with min/max labels.

Parameters:

• cmap – Colormap name or stops list.

• vmin – Data range.

• vmax – Data range.

• x – Top-left corner of the bar in SVG units.

• y – Top-left corner of the bar in SVG units.

• width – Width of the color strip.

• height – Height of the color strip.

• font – Font family for labels.

• text_color – Label fill color.

• steps – Number of gradient rectangles.

Returns:

SVG markup string.

Accessibility

glyphx.a11y.generate_alt_text(fig: Figure) → str

Generate a plain-English description of a Figure for screen readers.

The description covers chart type, title, axis labels, series count, data ranges, and notable values (min / max).

Parameters:

fig – A GlyphX Figure instance.

Returns:

A human-readable string suitable for aria-label or <desc>.

glyphx.a11y.inject_aria(svg: str, title: str, desc: str, chart_id: str) → str

Inject ARIA attributes and landmark elements into a rendered SVG string.

Changes made: - Adds role="img" and aria-labelledby to the root <svg>

(only if not already present)

• Injects <title> and <desc> as the first children of the SVG

• Adds tabindex="0" and role="graphics-symbol" to every .glyphx-point element for keyboard navigation

Parameters:

• svg – Raw SVG string from Figure.render_svg().

• title – Short label (goes in <title>).

• desc – Longer description (goes in <desc>).

• chart_id – Unique chart ID already present on the <svg> element.

Returns:

The accessibility-enhanced SVG string.

Themes

glyphx.themes.themes = {'colorblind': {'axis_color': '#000000', 'background': '#ffffff', 'colors': ['#E69F00', '#56B4E9', '#009E73', '#F0E442', '#0072B2', '#D55E00', '#CC79A7', '#000000'], 'font': 'sans-serif', 'grid_color': '#bbbbbb', 'text_color': '#000000'}, 'dark': {'axis_color': '#cccccc', 'background': '#1e1e1e', 'colors': ['#8ecae6', '#ffb703', '#219ebc', '#fb8500', '#d62828', '#a8dadc', '#f4a261', '#e9c46a'], 'font': 'sans-serif', 'grid_color': '#444444', 'text_color': '#ffffff'}, 'default': {'axis_color': '#333', 'background': '#ffffff', 'colors': ['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f'], 'font': 'sans-serif', 'grid_color': '#ddd', 'text_color': '#000000'}, 'monochrome': {'axis_color': '#111111', 'background': '#ffffff', 'colors': ['#111111', '#333333', '#555555', '#777777', '#999999', '#bbbbbb', '#dddddd'], 'font': 'sans-serif', 'grid_color': '#cccccc', 'text_color': '#000000'}, 'ocean': {'axis_color': '#023e8a', 'background': '#f0f8ff', 'colors': ['#03045e', '#0077b6', '#00b4d8', '#90e0ef', '#caf0f8', '#48cae4', '#023e8a', '#0096c7'], 'font': 'sans-serif', 'grid_color': '#caf0f8', 'text_color': '#03045e'}, 'pastel': {'axis_color': '#444444', 'background': '#f9f9f9', 'colors': ['#aec7e8', '#ffbb78', '#98df8a', '#ff9896', '#c5b0d5', '#c49c94', '#f7b6d2', '#c7c7c7'], 'font': 'sans-serif', 'grid_color': '#cccccc', 'text_color': '#222222'}, 'warm': {'axis_color': '#5c3317', 'background': '#fff8f0', 'colors': ['#e63946', '#f4a261', '#e9c46a', '#2a9d8f', '#264653', '#a8dadc', '#457b9d', '#1d3557'], 'font': 'Georgia, serif', 'grid_color': '#f0d9c8', 'text_color': '#3e1f00'}}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:

d = {} for k, v in iterable:

d[k] = v

dict(**kwargs) -> new dictionary initialized with the name=value pairs

in the keyword argument list. For example: dict(one=1, two=2)

Available theme names: "default", "dark", "colorblind", "pastel", "warm", "ocean", "monochrome"

Utilities

glyphx.utils.normalize(data)

Normalize a numeric array to the [0, 1] range.

Parameters:

data (array-like) – List or NumPy array of values.

Returns:

Values scaled to [0, 1].

Return type:

np.ndarray

Raises:

ValueError – If all values are equal (zero-width range).

glyphx.utils.svg_escape(text)

Escape a string for safe embedding inside SVG text or attribute values.

Parameters:

text (str) – Raw user-provided string.

Returns:

HTML-escaped string safe for SVG.

Return type:

str

glyphx.utils.wrap_svg_canvas(svg_content: str, width: int = 640, height: int = 480, has_math: bool = False) → str

Wrap raw SVG elements in a full <svg> root element.

Each SVG gets a collision-resistant UUID id (no module-level counter that grows unboundedly in long-running Jupyter sessions).

Parameters:

• svg_content (str) – Inner SVG markup.

• width (int) – Canvas width in pixels.

• height (int) – Canvas height in pixels.

• has_math (bool) – When True, embeds a MathJax data attribute so wrap_svg_with_template injects the CDN script.

Returns:

Complete SVG document string.

Return type:

str

glyphx.utils.make_shareable_html(svg_string: str, title: str = 'GlyphX Chart') → str

Build a fully self-contained HTML document with all JavaScript inlined.

The output has zero external dependencies and renders correctly in: - Email clients (tested in Gmail, Outlook web) - Confluence / Notion embeds - GitHub Pages / static hosts - Air-gapped / offline environments

Parameters:

• svg_string (str) – Raw SVG markup.

• title (str) – <title> tag value.

Returns:

Complete, standalone HTML document string.

Return type:

str

glyphx.utils.write_svg_file(svg_string: str, filename: str, **kwargs)

Save a chart to file. Supports .svg, .html, .png, and .jpg.

PNG/JPG export requires the optional cairosvg package:

pip install cairosvg

Parameters:

• svg_string (str) – Raw SVG content.

• filename (str) – Output path. Extension determines format.

Raises:

• ValueError – For unsupported extensions.

• RuntimeError – If cairosvg is not installed when exporting raster images.

Projection (3-D)

class glyphx.projection3d.Camera3D(azimuth: float = 45.0, elevation: float = 30.0, cx: float = 0.0, cy: float = 0.0, scale: float = 1.0)

Bases: object

Orthographic camera for projecting 3D data to 2D SVG.

Angles follow the geographic convention:

azimuth — rotation around the vertical (Z) axis, degrees.

0° = looking from +Y; 90° = looking from +X.

elevation — tilt above the horizontal plane, degrees.

0° = side view; 90° = top-down.

The right-hand coordinate system uses:

X → right, Y → into screen (depth), Z → up.

project(x: float, y: float, z: float) → Projected

Project a normalised 3D point to 2D screen coordinates.

project_all(xs: list[float], ys: list[float], zs: list[float]) → list[Projected]

Project a batch of points.

glyphx.projection3d.normalize(values: list[float]) → tuple[list[float], float, float]

Return (normalised_to_minus1_plus1, min_val, max_val).