API Reference¶
Top-level functions¶
botplotlib.scatter(data, x, y, *, color=None, title=None, subtitle=None, x_label=None, y_label=None, footnote=None, theme='default', width=800, height=500, legend_position='right', color_map=None)
¶
Create a scatter plot.
Parameters¶
data: Input data (dict, list[dict], DataFrame, etc.). x: Column name for the x axis. y: Column name for the y axis. color: Column name for color grouping (optional). title: Plot title (optional). subtitle: Subtitle below the title (optional). footnote: Footer text below the plot (optional). theme: Theme name (default, bluesky, print, magazine). legend_position: Legend position ("top", "bottom", "left", "right"). color_map: Custom color overrides per category, e.g. {"A": "#FF0000"}.
botplotlib.line(data, x, y, *, color=None, title=None, subtitle=None, x_label=None, y_label=None, footnote=None, theme='default', width=800, height=500, legend_position='right', color_map=None)
¶
Create a line plot.
Parameters¶
data: Input data (dict, list[dict], DataFrame, etc.). x: Column name for the x axis. y: Column name for the y axis. color: Column name for color grouping (optional). title: Plot title (optional). subtitle: Subtitle below the title (optional). footnote: Footer text below the plot (optional). theme: Theme name (default, bluesky, print, magazine). legend_position: Legend position ("top", "bottom", "left", "right"). color_map: Custom color overrides per category, e.g. {"A": "#FF0000"}.
botplotlib.bar(data, x, y, *, color=None, title=None, subtitle=None, x_label=None, y_label=None, footnote=None, theme='default', width=800, height=500, labels=False, label_format=None, legend_position='right', color_map=None)
¶
Create a bar chart.
Parameters¶
data: Input data (dict, list[dict], DataFrame, etc.). x: Column name for the x (category) axis. y: Column name for the y (value) axis. color: Column name for color grouping (optional). title: Plot title (optional). subtitle: Subtitle below the title (optional). footnote: Footer text below the plot (optional). theme: Theme name (default, bluesky, print, magazine). labels: Show value labels on bars (default False). label_format: Python format string for labels, e.g. "${:,.0f}". legend_position: Legend position ("top", "bottom", "left", "right"). color_map: Custom color overrides per category, e.g. {"A": "#FF0000"}.
botplotlib.waterfall(data, x, y, *, title=None, subtitle=None, x_label=None, y_label=None, footnote=None, theme='default', width=800, height=500, labels=False, label_format=None, legend_position='right')
¶
Create a waterfall chart.
Parameters¶
data: Input data (dict, list[dict], DataFrame, etc.). x: Column name for category labels (e.g., "Revenue", "COGS"). y: Column name for step values (positive = increase, negative = decrease). title: Plot title (optional). subtitle: Subtitle below the title (optional). footnote: Footer text below the plot (optional). theme: Theme name (default, bluesky, print, magazine). labels: Show value labels on bars (default False). label_format: Python format string for labels, e.g. "${:,.0f}". legend_position: Legend position ("top", "bottom", "left", "right").
botplotlib.plot(data, *, theme='default', **kwargs)
¶
Create an empty figure for layered composition.
Use fig.add_scatter(), fig.add_line(), fig.add_bar()
to add layers.
Parameters¶
data: Input data (dict, list[dict], DataFrame, etc.). theme: Theme name.
botplotlib.render
¶
Figure¶
botplotlib.figure.Figure
¶
A rendered plot that can be saved, displayed, or inspected.
Typically created via the convenience functions in botplotlib._api
(e.g., blt.scatter(), blt.line(), blt.bar()).
Agent / JSON path:
Figure.from_json(json_string) — parse a PlotSpec JSON string.
Figure.from_dict(d) — construct from a plain dict (typical LLM
function-call output format).
spec
property
¶
Return the underlying PlotSpec.
compiled
property
¶
title
property
writable
¶
subtitle
property
writable
¶
footnote
property
writable
¶
from_json(json_string)
classmethod
¶
Construct a Figure from a PlotSpec JSON string.
Validates the JSON with Pydantic and raises ValidationError on
invalid input. This is the primary entry point for the agent / JSON
path — LLMs can generate a PlotSpec JSON string directly and hand it
off to this method.
Parameters¶
json_string: A JSON string that conforms to the PlotSpec schema.
Raises¶
pydantic.ValidationError
If the JSON does not match the PlotSpec schema.
json.JSONDecodeError
If json_string is not valid JSON.
from_dict(d)
classmethod
¶
Construct a Figure from a plain dict.
Validates the dict with Pydantic and raises ValidationError on
invalid input. This is the typical entry point when an LLM returns a
PlotSpec as structured output (e.g., a function-call response dict).
Parameters¶
d: A dict that conforms to the PlotSpec schema.
Raises¶
pydantic.ValidationError If the dict does not match the PlotSpec schema.
to_svg()
¶
Return the plot as an SVG string.
save_svg(path)
¶
Save the plot as an SVG file.
save_png(path)
¶
Save the plot as a PNG file. Requires botplotlib[png].
add_scatter(x, y, color=None)
¶
Add a scatter layer.
add_line(x, y, color=None)
¶
Add a line layer.
add_bar(x, y, color=None, labels=False, label_format=None)
¶
Add a bar layer.
Spec models¶
PlotSpec¶
botplotlib.spec.models.PlotSpec
¶
Bases: BaseModel
Complete specification for a plot.
JSON-serializable, round-trips through
.model_dump_json() / .model_validate_json().
PlotSpec fields:
| Field | Type | Default | Description |
|---|---|---|---|
data |
DataSpec |
empty | Columnar data |
layers |
list[LayerSpec] |
[] |
Plot layers |
labels |
LabelsSpec |
empty | Title and axis labels |
legend |
LegendSpec |
show, right | Legend config |
size |
SizeSpec |
800x500 | Canvas dimensions |
theme |
str |
"default" |
Theme name |
DataSpec¶
botplotlib.spec.models.DataSpec
¶
Bases: BaseModel
Columnar data attached to a plot spec.
| Field | Type | Default | Description |
|---|---|---|---|
columns |
dict[str, list] |
{} |
Column name to values mapping |
LayerSpec¶
botplotlib.spec.models.LayerSpec
¶
Bases: BaseModel
A single plot layer (scatter, line, or bar).
| Field | Type | Default | Description |
|---|---|---|---|
geom |
str |
required | Geometry type (validated against registry) |
x |
str |
required | Column name for x-axis |
y |
str |
required | Column name for y-axis |
color |
str \| None |
None |
Column name for color grouping |
color_map |
dict[str, str] \| None |
None |
Custom per-category color overrides |
labels |
bool |
False |
Show value labels on bars |
label_format |
str \| None |
None |
Python format string for labels |
LabelsSpec¶
botplotlib.spec.models.LabelsSpec
¶
Bases: BaseModel
Plot labels.
| Field | Type | Default | Description |
|---|---|---|---|
title |
str \| None |
None |
Plot title |
subtitle |
str \| None |
None |
Plot subtitle |
x |
str \| None |
None |
X-axis label |
y |
str \| None |
None |
Y-axis label |
footnote |
str \| None |
None |
Footnote below the plot |
SizeSpec¶
botplotlib.spec.models.SizeSpec
¶
Bases: BaseModel
Canvas size in pixels.
| Field | Type | Default | Description |
|---|---|---|---|
width |
float |
800 |
Canvas width in pixels |
height |
float |
500 |
Canvas height in pixels |
ThemeSpec¶
botplotlib.spec.theme.ThemeSpec
¶
Bases: BaseModel
Visual theme for a plot.
See the Guide for usage examples.
Refactor module¶
botplotlib.refactor.from_matplotlib
¶
Translate matplotlib scripts to botplotlib.
Reads existing matplotlib scripts and extracts an equivalent PlotSpec using AST analysis. No matplotlib installation required — your code is parsed, never executed.
Uses AST parsing (never imports or runs your matplotlib code).
Supported patterns: - plt.plot(), plt.scatter(), plt.bar(), plt.barh() - ax.plot(), ax.scatter(), ax.bar(), ax.barh() - plt.title(), plt.xlabel(), plt.ylabel() - ax.set_title(), ax.set_xlabel(), ax.set_ylabel() - plt.figure(figsize=...), plt.subplots(figsize=...) - plt.legend() / ax.legend() - plt.savefig() / fig.savefig() - plt.grid() / ax.grid() - label= keyword on plot calls (legend entries) - color=/c= keyword on plot calls - Format strings in plt.plot() (e.g., 'ro-', 'b--', 'g^')
Also provides to_botplotlib_code() for generating the equivalent botplotlib one-liner from a matplotlib script.
from_matplotlib(source)
¶
to_botplotlib_code(source)
¶
Convert a matplotlib script to equivalent botplotlib Python code.
This produces a human-readable one-liner (or short snippet) that demonstrates the token-efficiency of botplotlib vs matplotlib.
Parameters¶
source: Path to a .py file, or a string of Python code.
Returns¶
str Python code using botplotlib that produces the equivalent plot.
botplotlib.refactor.to_botplotlib_code(source)
¶
Convert a matplotlib script to equivalent botplotlib Python code.
This produces a human-readable one-liner (or short snippet) that demonstrates the token-efficiency of botplotlib vs matplotlib.
Parameters¶
source: Path to a .py file, or a string of Python code.
Returns¶
str Python code using botplotlib that produces the equivalent plot.
Geom plugin API¶
Geom (abstract base class)¶
botplotlib.geoms.Geom
¶
Bases: ABC
Base class for plot geometries.
Subclass this and implement validate(), scale_hint(), and compile() to create a new plot type. See AGENTS.md for the step-by-step recipe.
validate(layer, data)
abstractmethod
¶
Validate that data has the columns this geom requires.
Raise ValueError with a clear, actionable message if validation fails.
scale_hint(layer, data)
abstractmethod
¶
Declare what scales this geom needs and contribute data ranges.
The compiler calls this on every layer before computing scales. Numeric geoms return their x/y values; categorical geoms return their categories.
compile(layer, data, scales, theme, plot_area)
abstractmethod
¶
Transform data into positioned geometric primitives.
Returns a list of Primitive objects (CompiledPoint, CompiledLine, CompiledBar, CompiledText, CompiledPath). The renderer draws them.
Registry functions¶
botplotlib.geoms.register_geom(geom)
¶
Register a geom instance by name.
botplotlib.geoms.get_geom(name)
¶
Look up a registered geom by name.
Raises ValueError with available geoms listed if not found.
Built-in geoms¶
| Name | Class | Description |
|---|---|---|
scatter |
ScatterGeom |
Scatter plot points |
line |
LineGeom |
Connected line series |
bar |
BarGeom |
Vertical bar chart |
waterfall |
WaterfallGeom |
Waterfall chart with running totals |
See AGENTS.md for instructions on adding custom geoms.
Data normalization¶
botplotlib.compiler.data_prep.normalize_data(data)
¶
See the Guide for supported formats.