plotlive.pyplot

State-machine API — mirrors matplotlib.pyplot. Every function operates on the current figure and axes, created automatically on first use.

Figure management

`figure(num=None, figsize=(6.4, 4.8), dpi=100, facecolor='white', edgecolor='white', **kwargs)`

Create a new figure and make it current.

Parameters:

Name	Type	Description	Default
`figsize`		Width and height in inches. Default is `(6.4, 4.8)`.	`(6.4, 4.8)`
`facecolor`		Background colour. Default is `'white'`.	`'white'`

Returns:

Type	Description
`Figure`	The new `Figure` instance.

`subplots(nrows=1, ncols=1, squeeze=True, figsize=(6.4, 4.8), sharex=False, sharey=False, **kwargs)`

Create a figure with a grid of subplots.

Parameters:

Name	Description	Default
`nrows`	Number of rows. Default is `1`.	`1`
`ncols`	Number of columns. Default is `1`.	`1`
`squeeze`	If `True`, a single subplot is returned as a bare `Axes` rather than a 1-element array. Default is `True`.	`True`
`figsize`	Width and height in inches.	`(6.4, 4.8)`

Returns:

Type	Description
	Tuple of `(Figure, axes)` where axes is a bare `Axes` for
	a 1×1 grid, a 1-D ndarray for a single row/column, or a 2-D ndarray
	otherwise — matching matplotlib's squeeze behaviour.

Example

fig, axs = plt.subplots(2, 3, figsize=(12, 6))
axs[0, 0].plot(x, y)

`gcf()`

Return the current figure, creating one if none exists.

`gca(**kwargs)`

Return the current axes, creating one if none exists.

`clf()`

Clear the current figure — removes all axes and the suptitle.

`cla()`

Clear the current axes — removes all artists and resets axis state.

`close(fig=None)`

Remove fig (or the current figure) from the figure list.

Parameters:

Name	Type	Description	Default
`fig`		Figure to close. Defaults to the current figure.	`None`

`show(block=True)`

Open pygame window (non-Jupyter) or display inline (Jupyter notebook).

`savefig(fname, **kwargs)`

Save the current figure to fname (PNG, based on extension).

Parameters:

Name	Type	Description	Default
`fname`	`str`	Output file path, e.g. `'output.png'`.	required

`tight_layout(**kwargs)`

Adjust subplot spacing to prevent label overlap.

`suptitle(t, **kwargs)`

Set a centred title for the whole figure (above all subplots).

Plots

`plot(*args, **kwargs)`

Plot lines and/or markers on the current axes.

Accepts the same arguments as matplotlib.pyplot.plot, including format strings ('r--', 'bo-') and keyword arguments (color, linewidth, label, …).

Returns:

Type	Description
	List of `Line2D` artists.

Example

plt.plot(x, y, 'b--', label='train', linewidth=2)

`scatter(x, y, **kwargs)`

Plot a scatter of points on the current axes.

Parameters:

Name	Description	Default
`x`	X coordinates.	required
`y`	Y coordinates.	required
`c`	Colour(s) or array of values mapped through cmap.	required
`s`	Marker size(s) in points².	required
`cmap`	Colormap name. Default is `'viridis'`.	required
`alpha`	Opacity, 0–1.	required

Returns:

Type	Description
	`PathCollection` artist.

`hist(x, **kwargs)`

Plot a histogram on the current axes.

Parameters:

Name	Description	Default
`x`	Data array.	required
`bins`	Number of bins or bin edges. Default is `10`.	required
`color`	Bar fill colour.	required
`edgecolor`	Bar edge colour.	required

Returns:

Type	Description
	Tuple of `(counts, bin_edges, patches)`.

`bar(x, height, **kwargs)`

Plot vertical bars on the current axes.

Parameters:

Name	Type	Description	Default
`x`		Bar positions.	required
`height`		Bar heights.	required

Returns:

Type	Description
	`BarContainer` (list of `Rectangle` patches).

`barh(y, width, **kwargs)`

Plot horizontal bars on the current axes.

Parameters:

Name	Type	Description	Default
`y`		Bar positions.	required
`width`		Bar widths.	required

Returns:

Type	Description
	`BarContainer` (list of `Rectangle` patches).

`imshow(X, **kwargs)`

Display an image or 2-D array on the current axes.

Parameters:

Name	Description	Default
`X`	2-D array `(H, W)` or RGB array `(H, W, 3)`.	required
`cmap`	Colormap name for scalar arrays. Default is `'viridis'`.	required
`vmin`	Lower clamp value for colormap scaling.	required
`vmax`	Upper clamp value for colormap scaling.	required
`origin`	`'upper'` puts row 0 at the top (default, suits confusion matrices). `'lower'` puts row 0 at the bottom.	required

Returns:

Type	Description
	`AxesImage` artist.

`colorbar(mappable=None, ax=None, **kwargs)`

Draw a colour scale bar next to an image plot.

Parameters:

Name	Type	Description	Default
`mappable`		The `AxesImage` to attach the colourbar to. Defaults to the most recent image on the target axes.	`None`
`ax`		Target axes. Defaults to the current axes.	`None`

`fill_between(x, y1, y2=0, **kwargs)`

Fill the area between two horizontal curves.

Parameters:

Name	Description	Default
`x`	X coordinates.	required
`y1`	Upper (or first) curve values.	required
`y2`	Lower (or second) curve values. Default is `0`.	`0`
`alpha`	Opacity. Default is `1.0`.	required

`errorbar(x, y, **kwargs)`

Plot points with error bars.

Parameters:

Name	Description	Default
`x`	X positions.	required
`y`	Y positions.	required
`yerr`	Y error values (symmetric scalar, array, or `(lower, upper)`).	required
`xerr`	X error values.	required
`fmt`	Format string for the data points. Default is `''`.	required
`capsize`	Length of error bar caps in points.	required

`boxplot(data, **kwargs)`

Draw a box-and-whisker plot for one or more datasets.

Parameters:

Name	Type	Description	Default
`data`		Array or list of arrays. Each array is one box.	required
`labels`		Tick labels for each box.	required

`violinplot(data, **kwargs)`

Draw a violin plot for one or more datasets.

Parameters:

Name	Description	Default
`data`	Array or list of arrays.	required
`positions`	X positions for each violin. Default is `[1, 2, …]`.	required
`widths`	Width of each violin. Default is `0.5`.	required

`pie(x, **kwargs)`

Draw a pie chart.

Parameters:

Name	Description	Default
`x`	Wedge sizes (need not sum to 1; normalised automatically).	required
`labels`	Sequence of wedge labels.	required
`startangle`	Starting angle in degrees, counter-clockwise from x-axis.	required

`stackplot(x, *ys, **kwargs)`

Draw a stacked area chart.

Parameters:

Name	Description	Default
`x`	X coordinates shared by all series.	required
`*ys`	One array per series.	`()`
`labels`	Legend labels for each series.	required
`alpha`	Opacity. Default is `1.0`.	required

Axis decoration

`xlabel(s, **kwargs)`

Set the x-axis label on the current axes.

`ylabel(s, **kwargs)`

Set the y-axis label on the current axes.

`title(s, **kwargs)`

Set the title on the current axes.

`legend(*args, **kwargs)`

Add a legend to the current axes using labelled artists.

`grid(visible=True, **kwargs)`

Show or hide the grid on the current axes.

Parameters:

Name	Type	Description	Default
`visible`		`True` to show, `False` to hide. Default is `True`.	`True`

`xlim(*args, **kwargs)`

Get or set the x-axis limits of the current axes.

Call with no arguments to get the current limits, or pass (left, right) to set them.

Returns:

Type	Description
	`(left, right)` when called with no arguments.

`ylim(*args, **kwargs)`

Get or set the y-axis limits of the current axes.

Call with no arguments to get the current limits, or pass (bottom, top) to set them.

Returns:

Type	Description
	`(bottom, top)` when called with no arguments.

`xscale(value, **kwargs)`

Set the x-axis scale. Use 'log' for logarithmic scale.

`yscale(value, **kwargs)`

Set the y-axis scale. Use 'log' for logarithmic scale.

`xticks(ticks=None, labels=None, **kwargs)`

Get or set x-axis tick positions and labels.

Parameters:

Name	Type	Description	Default
`ticks`		Tick positions. If `None`, returns current ticks.	`None`
`labels`		Tick labels. Defaults to string representation of ticks.	`None`

`yticks(ticks=None, labels=None, **kwargs)`

Get or set y-axis tick positions and labels.

Parameters:

Name	Type	Description	Default
`ticks`		Tick positions. If `None`, returns current ticks.	`None`
`labels`		Tick labels. Defaults to string representation of ticks.	`None`

`axhline(y=0, xmin=0, xmax=1, **kwargs)`

Draw a horizontal line across the current axes at y.

Parameters:

Name	Description	Default
`y`	Data-space y position. Default is `0`.	`0`
`xmin`	Left extent in axes fraction (0–1). Default is `0`.	`0`
`xmax`	Right extent in axes fraction (0–1). Default is `1`.	`1`

`axvline(x=0, ymin=0, ymax=1, **kwargs)`

Draw a vertical line across the current axes at x.

Parameters:

Name	Description	Default
`x`	Data-space x position. Default is `0`.	`0`
`ymin`	Bottom extent in axes fraction (0–1). Default is `0`.	`0`
`ymax`	Top extent in axes fraction (0–1). Default is `1`.	`1`

Animation

`animate(update_fn, frames=None, interval=200, repeat=True, fig=None, fargs=None, save_count=None)`

Create and register an animation on the current figure.

Shorthand for constructing a ~plotlive.animation.FuncAnimation and attaching it to the figure. For the full parameter set, construct ~plotlive.animation.FuncAnimation directly.

Parameters:

Name	Type	Description	Default
`update_fn`		Called as `update_fn(frame)` each step.	required
`frames`		Number of frames (int), explicit frame values (list), a generator, or `None` (defaults to 100).	`None`
`interval`	`int`	Milliseconds between frames. Default is `200`.	`200`
`repeat`	`bool`	Loop when finished. Default is `True`.	`True`
`fig`	`Figure \| None`	Figure to attach to. Defaults to the current figure.	`None`
`fargs`		Extra positional arguments forwarded to update_fn.	`None`
`save_count`	`int \| None`	Frame count when frames is `None` or a generator.	`None`

Returns:

Type	Description
`FuncAnimation`	The registered `~plotlive.animation.FuncAnimation` instance.

Example

def update(frame):
    plt.cla()
    plt.plot(x[:frame], y[:frame])

plt.animate(update, frames=100, interval=50)
plt.show()

`save_animation(filename, fps=None, fig=None)`

Export the current figure's animation to a file.

Renders all frames off-screen — no window opens. Resets to frame 0 afterwards so a subsequent show() starts from the beginning.

Parameters:

Name	Type	Description	Default
`filename`	`str`	Output path. Extension determines format: `.gif` (requires Pillow), `.mp4` / `.mov` / `.avi` (requires imageio + ffmpeg).	required
`fps`	`int \| None`	Frames per second. Defaults to `1000 / interval`.	`None`
`fig`	`Figure \| None`	Figure to export. Defaults to the current figure.	`None`

Raises:

Type	Description
`RuntimeError`	If no animation has been registered on the figure.

Example

plt.animate(update, frames=60, interval=100)
plt.save_animation('output.gif')
plt.show()  # opens interactive window at frame 0