API Overview

Top Level Functions

The main function here is the subplots() function, but there is also a style function available (see the styles page).

subplots(*args, **kwargs)

A wrapper to the plt.subplots() function, and is the main way to access the betterplotlib functionality.

set_style([style, font, fontweight])

Set style settings that will apply to all plots after this function call.

Axes

The Axes_bpl objects are where the main functionality lies. The easiest way to create them is by using the subplots() function, which creates both a matplotlib Figure and Axes_bpl object (typically used as fig, ax = bpl.subplots()). The Axes_bpl inherits from the matplotlib Axes object, so it has all the same methods. It additionally has some new ones, and some of the old ones are redefined to make plotting nicer and easier. The functionality of the Axes_bpl is broken down into some common themes below. Each of these has at least one example of the function in use.

Plotting

These methods replace or supplement the default matplotlib commands for the main plotting functionality.

Axes_bpl.plot(*args, **kwargs)

A slightly improved plot function.

Axes_bpl.scatter(*args, **kwargs)

Makes a scatter plot that looks nicer than the matplotlib default.

Axes_bpl.errorbar(*args, **kwargs)

Wrapper for the plt.errorbar() function.

Axes_bpl.hist(*args, **kwargs)

A better histogram function.

Axes_bpl.kde(xs, smoothing[, norm, log])

Visualize a distribution in 1D with kernel density estimation

Axes_bpl.density_contour(xs, ys[, bin_size, ...])

Creates contours over a 2D histogram of data density.

Axes_bpl.density_contourf(xs, ys[, ...])

Creates filled contours over a 2D histogram of data density.

Axes_bpl.contour_scatter(xs, ys[, bin_size, ...])

Create a contour plot with scatter points in the sparse regions.

Axes_bpl.shaded_density(xs, ys[, bin_size, ...])

Creates shaded regions showing the density.

Plot Annotations and Format

These methods control various annotations, like the legend, tick marks, and axes labels.

Axes_bpl.legend([linewidth])

Create a nicer looking legend.

Axes_bpl.axhline([y])

Place a horizontal line at some point on the axes.

Axes_bpl.axvline([x])

Place a vertical line at some point on the axes.

Axes_bpl.add_text(x, y, text[, coords, ...])

Adds text to the specified location.

Axes_bpl.easy_add_text(text, location, **kwargs)

Adds text in common spots easily.

Axes_bpl.set_limits([x_min, x_max, y_min, y_max])

Set axes limits for both x and y axis at once.

Axes_bpl.set_ticks(axis, ticks[, labels, minor])

Set tick marks on an axis, with optional label names

Axes_bpl.log(axes[, nice_format])

Set the x and/or y axis to be log-scaled

Axes_bpl.add_labels([x_label, y_label, title])

Adds labels to the x and y axis, plus a title.

Axes_bpl.remove_labels(labels_to_remove)

Removes the labels and tick marks from an axis border.

Axes_bpl.remove_ticks(*ticks_to_remove)

Removes ticks from the given locations.

Axes_bpl.remove_spines(*spines_to_remove)

Remove spines from the axis.

Axes_bpl.equal_scale()

Makes the x and y axes have the same scale.

Axes_bpl.twin_axis_simple(axis, lower_lim, ...)

Creates a differently scaled axis on either the top or the left.

Axes_bpl.twin_axis(axis, new_ticks, label[, ...])

Create a twin axis, where the new axis values are an arbitrary function of the old values.

Axes_bpl.make_ax_dark([grid, minor_ticks])

Turns an axis into one with a dark background with white gridlines.

Axes_bpl.data_ticks(x_data, y_data[, extent])

Puts tiny ticks on the axis borders making the location of each point.

Non Object-Oriented Interface

In addition to the interface described above, all the Axes objects are accessible without directly creating them. This works just like the plt.whatever() syntax in default matplotlib, just with bpl.whatever().

Colors

The bpl.color_cycle attribute is a list of colors that I set as the default color cycle for plots. There are also a few other colors mentioned in the styles page. There are also few functions that can be used to handle colors and colormaps.

create_mappable(vmin, vmax, cmap[, log])

Create a ScalarMappable, which is used to get colors from a colorbar

fade_color(color)

Create a faded version of a different color

unfade_color(color)

Undo the fading applied by fade_color