Chart

The Chart class is the central object in gufo. Users create instances via gufo.chart(), never by instantiating Chart directly.

Entry point

gufo.core.chart.chart(data=None)

Create a new Chart. The entry point for all gufo charts.

Chart class

class gufo.core.chart.Chart(data=None)

Bases: object

The main interface for building a gufo chart.

Methods register layers and options; nothing is drawn until .show() or .save() is called. This deferred rendering allows the theme and figure size to be finalized before any matplotlib calls are made.

Users create Chart instances via gufo.chart(), never directly.

__init__(data=None)

scatter(x, y, *, color=None, size=None, alpha=None, label=None, cmap=None, vmin=None, vmax=None, colorbar=True, fit=None, y_error=None, x_error=None, color_order=None, **kwargs)

Add a scatter plot layer.

y may be a list of column names for wide-form DataFrames — each column becomes its own series without requiring pd.melt().

When color is a numeric column, cmap/vmin/vmax control the colormap and range. A colorbar is shown by default (set colorbar=False to hide).

fit accepts a gufo.regression() config object to overlay a fit line. y_error / x_error accept a column name or array for error bars.

line(x, y, *, color=None, stroke_dash=None, label=None, cmap=None, vmin=None, vmax=None, colorbar=True, y_error=None, x_error=None, color_order=None, **kwargs)

Add a line plot layer.

y may be a list of column names for wide-form DataFrames — each column becomes its own series without requiring pd.melt().

When color is a numeric column, the line is drawn as a gradient segment-by-segment using cmap/vmin/vmax. A colorbar is shown by default (set colorbar=False to hide).

y_error / x_error accept a column name or array for error bars.

bar(x, y, *, color=None, horizontal=False, stacked=False, label=None, y_error=None, x_error=None, order=None, color_order=None, **kwargs)

Add a bar chart layer.

y may be a list of column names for wide-form DataFrames — each column becomes a grouped bar without requiring pd.melt().

When color is a categorical column, bars are grouped (dodged) by default. Set stacked=True to stack bars instead.

y_error / x_error accept a column name or array for error bars.

histogram(x, *, bins='auto', color=None, horizontal=False, density=False, multiple='layer', fill=True, label=None, kde=None, color_order=None, **kwargs)

Add a histogram layer.

Set horizontal=True to orient the histogram sideways. Set density=True to normalize the histogram so the area under it sums to 1. multiple controls grouped histogram layout: “layer” (overlay with transparency), “stack”, or “dodge”. Set fill=False for step (outline-only) histograms. kde accepts a gufo.kde() config object to overlay a density curve.

kdeplot(x, *, color=None, bw_method=None, linestyle='-', linewidth=2.0, alpha=1.0, fill=False, n_points=200, label=None, color_order=None, **kwargs)

Add a KDE (kernel density estimation) density layer.

Set fill=True to shade under the curve. bw_method controls scipy’s gaussian_kde bandwidth. n_points sets the resolution of the curve. Extra keyword arguments are passed through to matplotlib.

strip(x, y, *, color=None, size=None, alpha=None, jitter=0.2, horizontal=False, label=None, order=None, color_order=None, **kwargs)

Add a strip plot layer (jittered points along a categorical axis).

x is the grouping column (categorical). y is the values column (numeric).

y may be a list of column names for wide-form DataFrames — each column becomes its own strip without requiring pd.melt().

swarm(x, y, *, color=None, size=None, alpha=None, horizontal=False, label=None, order=None, color_order=None, **kwargs)

Add a swarm plot layer (non-overlapping points along a categorical axis).

x is the grouping column (categorical). y is the values column (numeric).

y may be a list of column names for wide-form DataFrames — each column becomes its own swarm without requiring pd.melt().

boxplot(x, y, *, color=None, horizontal=False, label=None, order=None, color_order=None, **kwargs)

Add a box plot layer.

x is the grouping column (categorical). y is the values column (numeric). Each unique x value produces one box.

y may be a list of column names for wide-form DataFrames — each column becomes its own box without requiring pd.melt().

violin(x, y, *, color=None, horizontal=False, label=None, order=None, color_order=None, **kwargs)

Add a violin plot layer.

x is the grouping column (categorical). y is the values column (numeric). Each unique x value produces one violin.

y may be a list of column names for wide-form DataFrames — each column becomes its own violin without requiring pd.melt().

heatmap(x=None, y=None, *, color=None, cmap=None, annotate=False, **kwargs)

Add a heatmap layer.

Two usage modes:

• Matrix form: gufo.chart(pivot_df).heatmap() — DataFrame is the matrix.

• Long-form: gufo.chart(df).heatmap(“x”, “y”, color=”value”) — pivoted internally.

area(x, y, *, color=None, alpha=None, label=None, y_error=None, color_order=None, **kwargs)

Add an area chart layer.

y may be a list of column names for wide-form DataFrames — each column becomes a stacked area without requiring pd.melt().

y_error accepts a column name or array and draws a lighter error band around the top edge of the area (long-form only).

countplot(x, *, color=None, horizontal=False, label=None, order=None, color_order=None, **kwargs)

Add a count plot layer — bars showing frequency of each x category.

ecdf(x, *, color=None, label=None, color_order=None, **kwargs)

Add an ECDF (empirical cumulative distribution function) layer.

rug(x, *, color=None, height=0.05, alpha=0.5, label=None, color_order=None, **kwargs)

Add a rug plot layer — tick marks along the x axis.

pointplot(x, y, *, color=None, horizontal=False, label=None, order=None, color_order=None, **kwargs)

Add a point plot layer — connected category means with 95% CI.

Shows the mean of y for each unique x value, connected by lines, with error bars representing the 95% confidence interval (via standard error). When color is set, groups are dodged.

x is the grouping column (categorical). y is the values column (numeric).

title(text)

Set the chart title.

subtitle(text)

Set a subtitle displayed below the title in smaller gray text.

xlabel(text)

Set the x-axis label.

ylabel(text)

Set the y-axis label.

caption(text)

Set a caption displayed below the chart in small gray text.

annotate(text, xy)

Add a text annotation with an arrow pointing to xy.

Parameters

textstr

The annotation text.

xytuple of float

The (x, y) data coordinates the arrow points to.

label(column=None, *, fmt=None, fontsize=None, offset=None)

Add data labels to bars or scatter points.

For bar charts, labels are placed at the end of each bar using axes.bar_label(). For scatter plots, pass a column name to label each point with that column’s value.

Parameters

columnstr or None

Column name whose values label each point (scatter only). For bar charts, omit or pass None to label with bar heights.

fmtstr or None

Format string (e.g. ".1f", ".0%"). For bars, passed directly to bar_label(fmt=...).

fontsizeint or str or None

Font size for the labels.

offsetfloat or None

Padding in points between the bar end and the label.

xlim(low, high)

Set the x-axis limits.

ylim(low, high)

Set the y-axis limits.

xscale(scale)

Set the x-axis scale (e.g. "log", "symlog").

yscale(scale)

Set the y-axis scale (e.g. "log", "symlog").

xticks(ticks=None, labels=None, rotation=None)

Configure x-axis tick positions, labels, and rotation.

Parameters

tickslist or None

Explicit tick positions.

labelslist or None

Labels corresponding to ticks.

rotationfloat or None

Rotation angle in degrees for tick labels.

yticks(ticks=None, labels=None, rotation=None)

Configure y-axis tick positions, labels, and rotation.

Parameters

tickslist or None

Explicit tick positions.

labelslist or None

Labels corresponding to ticks.

rotationfloat or None

Rotation angle in degrees for tick labels.

legend(*, position='best', title=None, hide=False)

Configure the legend.

Parameters

positionstr

Legend location. Any matplotlib loc string (e.g. "best", "upper right") or one of "outside right", "outside left", "outside top", "outside bottom" to place the legend outside the axes.

titlestr or None

Optional legend title.

hidebool

If True, suppress the legend entirely.

theme(name_or_theme)

Set the theme for this chart.

Accepts a theme name ("gufo_modern", "gufo_dark", etc.) or a Theme instance.

facet(column=None, *, row=None, cols=3, sharex=True, sharey=True)

Split the chart into subplots by one or two categorical columns.

With column only, panels wrap after cols columns. With row, panels form a grid where row categories go down and column categories go across. With row only, each row category gets one panel in a single column.

Parameters

columnstr or None

Column for horizontal faceting.

rowstr or None

Column for vertical faceting.

colsint

Max columns before wrapping (single-variable faceting only).

sharexbool

Share x-axis range across panels. Default True.

shareybool

Share y-axis range across panels. Default True.

apply(func)

Call func(figure, axes) after all layers are rendered.

func receives the underlying matplotlib Figure and Axes and may call any matplotlib method on them. Its return value is ignored. The Chart is returned so the chain continues.

Use this for operations gufo does not yet support natively.

palette(colors)

Set the color palette for this chart.

Accepts a list of color strings or a named palette (‘gufo’, ‘pastel’, ‘bold’, ‘colorblind’).

hline(y, *, color='black', linestyle='--', linewidth=1, alpha=0.8, label=None, **kwargs)

Add a horizontal reference line.

vline(x, *, color='black', linestyle='--', linewidth=1, alpha=0.8, label=None, **kwargs)

Add a vertical reference line.

hband(y1, y2, *, color='gray', alpha=0.2, label=None, **kwargs)

Add a horizontal reference band.

vband(x1, x2, *, color='gray', alpha=0.2, label=None, **kwargs)

Add a vertical reference band.

size(width, height)

Set the figure size in inches as (width, height).

clear()

Remove all registered layers and decorators, keeping data and theme.

Gufo builds charts lazily: every mark or decorator call registers a layer on the Chart, and nothing is drawn until .show() or .save(). Calling .show() does not clear those layers, so reusing a Chart variable accumulates them. Use .clear() to reset the chart between plots while keeping the bound data, theme, palette, figure size, and facet configuration.

Returns self so it stays in the chain.

show()

Render and display the chart.

The figure is closed afterwards so repeated calls do not accumulate open figures. In interactive mode the figure is left open, since the window or widget is still live and the user is expected to keep interacting with it.

save(path, *, dpi=150)

Render and save the chart to a file.