gum-jsx 0.5

Python wrapper for gum.jsx, a language for creating vector graphics

A Python wrapper for gum.jsx, a language for creating visualizations using a React-like JSX dialect that evaluates to SVG. Designed for general graphics, plots, graphs, and network diagrams. Automatically renders in IPython console and Jupyter notebooks.

Head to compendiumlabs.ai/gum for a live demo and documentation on the underlying gum.jsx library.

Installation

pip install gum-jsx

Requires node to be installed for the gum.jsx backend. Set the GUM_JSX_RUNTIME environment variable to use a different runtime (e.g. bun). You also need chafa installed for terminal display.

Usage

Create visualizations using Python syntax that generates JSX:

import gum
from gum import C
from gum.gen import Plot, SymLine

# create a simple sine wave plot
plot = Plot(
    SymLine(fy=C.sin, xlim=(0, 2*C.pi), stroke=C.blue, stroke_width=2),
    ylim=(-1.5, 1.5), grid=True, margin=(0.2, 0.1), aspect=2
)

# display in terminal (requires chafa)
gum.display(plot) # or just `plot` if you're in IPython or Jupyter

# or get the SVG string
svg = gum.evaluate(plot)

# or get the JSX code
jsx = str(plot)

If you're in IPython or Jupyter, you don't even need to call display. Just type plot and it will automatically display the visualization inline.

Pandas Integration

Plot DataFrames directly with high-level functions:

import pandas as pd
import numpy as np
from gum import lines, points, bars

# line plot from DataFrame
th = np.linspace(0, 2*np.pi, 100)
df = pd.DataFrame({ 'sin': np.sin(th), 'cos': np.cos(th) })
lines(df, margin=0.15)

# bar chart from Series
bars(pd.Series({'A': 3, 'B': 8, 'C': 5}))

Symbolic Expressions

Use C for constants and V for variables:

from gum import C, V

# C references gum.jsx constants and functions
C.sin, C.cos, C.pi, C.blue, C.red

# build symbolic expressions
decay = lambda x: C.exp(-x/2) * C.sin(3*x)

# V creates named variables bound to data
theta = V.theta(np.linspace(0, 2*np.pi, 100))

CLI

Display gum visualizations directly in the terminal using chafa. Requires a terminal with image support, such as ghostty.

# pipe JSX code
cat input.jsx | python -m gum

# run a built-in demo
python -m gum -d plot

CLI options:

Option	Description	Default
-s, --size <size>	Terminal display size	50
-t, --theme <theme>	Theme: light or dark	dark
-d, --demo <name>	Run a named demo	-

Available demos (see gum/dem.py for code): gum, element, group, box, stack, grid, points, rect, ellipse, line, shape, spline, text, latex, titleframe, slide, sympoints, symline, symshape, symspline, symfill, graph, plot, axis, barplot, node, edge, network, math, arrays, colors

Components

Wraps all gum.jsx components. Key ones include:

Core: Element, Group, Svg

Layout: Box, Frame, Stack, HStack, VStack, Grid, Points

Shapes: Rect, Ellipse, Circle, Line, Shape, Spline

Text: Text, TextFrame, Latex, Equation, TitleFrame, TextStack, Slide

Plotting: Plot, Graph, Axis, HAxis, VAxis, Bars, BarPlot

Symbolic: SymLine, SymPoints, SymShape, SymSpline, SymFill, SymField

Network: Node, Edge, Network, Arrow, ArrowHead, ArrowSpline

See the gum.jsx documentation for detailed component reference.