Usage Guide

Basic Plotting

Use plot() for the fastest path to any chart type:

from glyphx import plot

# Line chart
plot([1, 2, 3, 4], [5, 7, 3, 9], kind="line",
     color="#2563eb", label="Series A",
     xlabel="X Axis", ylabel="Y Axis", title="Line Chart")

# Bar chart with categorical X axis
plot(["Mon","Tue","Wed","Thu","Fri"], [42, 61, 38, 75, 53],
     kind="bar", color="#7c3aed", title="Daily Active Users")

# Scatter plot with colormap encoding
plot(x_data, y_data, kind="scatter",
     c=color_values, cmap="viridis", size=7)

# Histogram from raw data
import numpy as np
plot(data=np.random.normal(50, 10, 500), kind="hist", bins=25)

# Pie chart
plot(data=[35, 28, 22, 15], kind="pie",
     labels=["Product A","Product B","Product C","Other"])

Method Chaining

Every mutating Figure method returns self, enabling full fluent chains:

from glyphx import Figure
from glyphx.series import LineSeries, BarSeries

fig = (
    Figure(width=800, height=500)
    .set_title("Revenue Dashboard")
    .set_theme("dark")
    .set_size(900, 520)
    .set_xlabel("Month")
    .set_ylabel("USD ($M)")
    .set_legend("top-left")
    .add(LineSeries(months, revenue, color="#60a5fa", label="Revenue", width=2.5))
    .add(LineSeries(months, costs, color="#f87171", label="Costs", linestyle="dashed"))
    .annotate("Record High", x=11, y=2.9, arrow=True, color="#fbbf24")
    .tight_layout()
    .share("dashboard.html")
)

Chainable Figure methods:

Method	Description
.add(series, use_y2=False)	Add a series; bind to right Y-axis with use_y2=True
.set_title(text)	Set chart title
.set_theme(name_or_dict)	Apply a named or custom theme
.set_size(width, height)	Resize canvas
.set_xlabel(text)	X-axis label
.set_ylabel(text)	Y-axis label
.set_legend(position)	Legend position or False to hide
.annotate(text, x, y, ...)	Add a text annotation with optional arrow
.add_stat_annotation(x1, x2, p_value)	Add a significance bracket
.tight_layout()	Auto-adjust padding and rotate crowded labels
.enable_crosshair()	Synchronized crosshair across all charts on the page
.show()	Display (Jupyter or browser)
.save(filename)	Save to .svg, .html, .png, .jpg, or .pptx
.share(filename, title)	Self-contained, zero-CDN HTML

DataFrame Accessor

Import glyphx once and every pd.DataFrame gains a .glyphx namespace. All methods return a Figure for further chaining:

import pandas as pd
import glyphx          # registers the .glyphx accessor

df = pd.read_csv("sales.csv")

# Basic charts
df.glyphx.line(x="date",    y="revenue", title="Daily Revenue")
df.glyphx.bar( x="product", y="units",   title="Units by Product")
df.glyphx.scatter(x="spend", y="conversions")
df.glyphx.hist(col="response_time", bins=20)
df.glyphx.box(col="score", groupby="treatment_group")
df.glyphx.pie(labels="category", values="share")
df.glyphx.heatmap()        # uses all numeric columns

# Groupby aggregation in one call
df.glyphx.bar(
    groupby="region",
    y="revenue",
    agg="sum",             # sum | mean | count | max | min
    title="Revenue by Region",
)

# Hue splitting — one BarSeries per unique hue value, auto-colored
# Each group gets its own label (appears in the legend) and a distinct
# color from the active theme palette.
df.glyphx.bar(
    x="month",
    y="revenue",
    hue="region",          # splits into North / South series
    title="Revenue by Month and Region",
)

# Full chain from the accessor
(df.glyphx
   .bar(x="month", y="revenue", label="Revenue", auto_display=False)
   .set_theme("colorblind")
   .add_stat_annotation("Jan", "Jun", p_value=0.001)
   .set_xlabel("Month")
   .set_ylabel("Revenue ($M)")
   .share("monthly_report.html"))

Note

When both x= and hue= are provided, bar() produces one BarSeries per unique hue value filtered to its own rows. When only hue= is given (without x=), it aggregates using agg= and creates one bar per group.

3-D Charts

Use Figure3D for interactive Three.js output with an SVG fallback:

from glyphx import Figure3D, plot3d
from glyphx.scatter3d import Scatter3DSeries
from glyphx.surface3d  import Surface3DSeries
from glyphx.line3d     import Line3DSeries
from glyphx.bar3d      import Bar3DSeries
from glyphx.contour    import ContourSeries
import numpy as np

# Scatter — continuous color via colormap
fig = Figure3D(title="Gaussian Clusters", theme="dark",
               azimuth=45, elevation=30,
               xlabel="X", ylabel="Y", zlabel="Z")
fig.add(Scatter3DSeries(xs, ys, zs, c=zs, cmap="plasma",
                        size=4, label="Points"))
fig.show()      # WebGL interactive viewer
fig.save("scatter3d.html")

# Surface — z = f(x, y) over a regular grid
x = np.linspace(-3, 3, 60)
y = np.linspace(-3, 3, 60)
Z = np.sin(np.sqrt(x[None,:]**2 + y[:,None]**2))
fig = Figure3D(title="Sinc Surface")
fig.add(Surface3DSeries(x, y, Z, cmap="viridis",
                        wireframe=True, alpha=0.9))
fig.show()

# Polyline through 3-D space
t = np.linspace(0, 4*np.pi, 500)
fig = Figure3D(title="Helix")
fig.add(Line3DSeries(np.cos(t), np.sin(t), t / (4*np.pi),
                     color="#dc2626", width=2))
fig.show()

# Bar3D
fig = Figure3D(title="3D Bars")
fig.add(Bar3DSeries(x_cats, y_cats, heights,
                    color="#2563eb", label="Sales"))
fig.show()

# Contour lines / filled contours
fig = Figure3D(title="Contour")
fig.add(ContourSeries(x, y, Z, levels=10, filled=True, cmap="coolwarm"))
fig.show()

# One-liner 3-D
plot3d(xs, ys, zs, kind="scatter", title="Quick 3D Scatter")
plot3d(x, y, Z, kind="surface", title="Quick Surface")

Figure3D constructor parameters:

Parameter	Default	Description
width	900	Canvas width in pixels
height	650	Canvas height in pixels
title	""	Chart title
theme	"default"	Theme name (same 7 options as 2-D Figure)
azimuth	45.0	Initial camera azimuth in degrees
elevation	30.0	Initial camera elevation in degrees
xlabel	"X"	X-axis label
ylabel	"Y"	Y-axis label
zlabel	"Z"	Z-axis label

Dual Y-Axis

Bind any series to the secondary (right-hand) Y-axis with use_y2=True:

from glyphx import Figure
from glyphx.series import LineSeries, BarSeries

fig = Figure(width=800, height=480)
fig.set_title("Price & Volume")
fig.add(LineSeries(dates, prices, color="#2563eb", label="Price (left)"))
fig.add(BarSeries(dates, volume, color="#d97706", label="Volume (right)"),
        use_y2=True)
fig.show()

Auto Display

GlyphX detects its runtime environment automatically:

• Jupyter notebook — renders inline as an SVG cell output

• CLI / script — writes a temporary HTML file and opens it in the default browser

• IDE — falls back to the browser viewer

To suppress auto-display (e.g. when building charts to export only):

fig = Figure(auto_display=False)
fig.save("chart.html")   # explicit save, no auto-open

Export and Sharing

fig.save("chart.svg")        # vector SVG
fig.save("chart.html")       # interactive HTML (zoom, pan, tooltips, export buttons)
fig.save("chart.png")        # raster PNG  — requires: pip install "glyphx[export]"
fig.save("chart.jpg")        # raster JPG  — requires: pip install "glyphx[export]"
fig.save("chart.pptx")       # PowerPoint  — requires: pip install "glyphx[pptx]"

# Self-contained HTML — zero external dependencies
html = fig.share()                    # returns HTML string
fig.share("report.html")             # also writes to disk
fig.share("report.html", title="Q3") # custom <title> tag

fig.share() inlines all JavaScript into a single file that works in email clients, Confluence, Notion, GitHub Pages, and offline environments.

Log Scale

Pass xscale or yscale to the Figure constructor:

fig = Figure(yscale="log")
fig.add(LineSeries(x, y))
fig.show()

Natural Language Chart Generation

Requires pip install "glyphx[nlp]" and an ANTHROPIC_API_KEY environment variable.

from glyphx import from_prompt
import pandas as pd

df = pd.read_csv("sales.csv")

fig = from_prompt("bar chart of total revenue by region, dark theme", df=df)
fig = from_prompt("scatter plot showing a strong positive correlation")
fig = from_prompt("top 10 products by revenue, sorted descending", df=df)

CLI Tool

Plot any CSV, JSON, or Excel file directly from the terminal:

glyphx plot sales.csv --x month --y revenue --kind bar -o chart.html
glyphx plot data.csv --x date --y revenue --kind line --theme dark --open
glyphx suggest data.csv
glyphx version

Supported input formats: .csv .tsv .json .jsonl .xlsx .xls

Supported output formats: .svg .html .png .jpg .pptx