pyplot¶

Control the output of standard plotting functions such as plot() and hist() using sliders and other widgets. When using the ipympl backend these functions will leverage ipywidgets for the controls, otherwise they will use the built-in Matplotlib widgets.

interactive_axhline(y=0, xmin=0, xmax=1, ax=None, slider_formats=None, force_ipywidgets=False, play_buttons=False, controls=None, display_controls=True, **kwargs)[source]¶

Control an horizontal line using widgets.

Parameters

yfloat or function

y position in data coordinates of the horizontal line.

xminfloat or function

Should be between 0 and 1, 0 being the far left of the plot, 1 the far right of the plot.

xmaxfloat or function

Should be between 0 and 1, 0 being the far left of the plot, 1 the far right of the plot.

axmatplotlib axis, optional

If None a new figure and axis will be created

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses the new {} style formatting

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

**kwargs

Kwargs will be used to create control widgets. Except kwargs that are valid for Line2D are extracted and passed through to the creation of the line.

Returns

controls

interactive_axvline(x=0, ymin=0, ymax=1, ax=None, slider_formats=None, force_ipywidgets=False, play_buttons=False, controls=None, display_controls=True, **kwargs)[source]¶

Control a vertical line using widgets.

Parameters

xfloat or function

x position in data coordinates of the horizontal line.

yminfloat or function

Should be between 0 and 1, 0 being the bottom of the plot, 1 the far top of the plot

ymaxfloat or function

Should be between 0 and 1, 0 being the top of the plot, 1 the top of the plot.

axmatplotlib axis, optional

If None a new figure and axis will be created

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses the new {} style formatting

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

**kwargs

Kwargs will be used to create control widgets. Except kwargs that are valid for Line2D are extracted and passed through to the creation of the line.

Returns

controls

interactive_hist(arr, density=False, bins='auto', weights=None, ax=None, slider_formats=None, force_ipywidgets=False, play_buttons=False, controls=None, display_controls=True, **kwargs)[source]¶

Control the contents of a histogram using widgets.

See https://github.com/ianhi/mpl-interactions/pull/73#issue-470638134 for a discussion of the limitations of this function. These limitations will be improved once https://github.com/matplotlib/matplotlib/pull/18275 has been merged.

Parameters

arrarraylike or function

The array or the function that returns an array that is to be histogrammed

densitybool, optional

whether to plot as a probability density. Passed to numpy.histogram

binsint or sequence of scalars or str, optional

bins argument to numpy.histogram

weightsarray_like, optional

passed to numpy.histogram

axmatplotlib axis, optional

The axis on which to plot. If none the current axis will be used.

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses the new {} style formatting

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

Returns

controls

Examples

With numpy arrays:

loc = np.linspace(-5, 5, 500)
scale = np.linspace(1, 10, 100)
def f(loc, scale):
    return np.random.randn(1000)*scale + loc
interactive_hist(f, loc=loc, scale=scale)

with tuples:

def f(loc, scale):
    return np.random.randn(1000)*scale + loc
interactive_hist(f, loc=(-5, 5, 500), scale=(1, 10, 100))

interactive_imshow(X, cmap=None, norm=None, aspect=None, interpolation=None, alpha=None, vmin=None, vmax=None, vmin_vmax=None, origin=None, extent=None, autoscale_cmap=True, filternorm=True, filterrad=4.0, resample=None, url=None, ax=None, slider_formats=None, force_ipywidgets=False, play_buttons=False, controls=None, display_controls=True, **kwargs)[source]¶

Control an image using widgets.

Parameters

Xfunction or image like

If a function it must return an image-like object. See matplotlib.pyplot.imshow for the full set of valid options.

cmapstr or Colormap

The Colormap instance or registered colormap name used to map scalar data to colors. This parameter is ignored for RGB(A) data. forwarded to matplotlib

normNormalize, optional

The Normalize instance used to scale scalar data to the [0, 1] range before mapping to colors using cmap. By default, a linear scaling mapping the lowest value to 0 and the highest to 1 is used. This parameter is ignored for RGB(A) data. forwarded to matplotlib

autoscale_cmapbool

If True rescale the colormap for every function update. Will not update if vmin and vmax are provided or if the returned image is RGB(A) like. forwarded to matplotlib

aspect{‘equal’, ‘auto’} or float

forwarded to matplotlib

interpolationstr

forwarded to matplotlib

alphafloat, callable, shorthand for slider or indexed controls

The alpha value of the image. Can accept a float for a fixed value, or any slider shorthand to control with a slider, or an indexed controls object to use an existing slider, or an arbitrary function of the other parameters.

axmatplotlib axis, optional

The axis on which to plot. If none the current axis will be used.

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses the new {} style formatting

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

Returns

controls

interactive_plot(*args, parametric=False, ax=None, slider_formats=None, xlim='stretch', ylim='stretch', force_ipywidgets=False, play_buttons=None, controls=None, display_controls=True, **kwargs)[source]¶

Control a plot using widgets

interactive_plot([x], y, [fmt])

where x/y is are either arraylike or a function that returns arrays. Any kwargs accepted by matplotlib.pyplot.plot will be passed through, other kwargs will be intrepreted as controls

Parameters

x, yarray-like or scalar or function

The horizontal / vertical coordinates of the data points. x values are optional and default to range(len(y)). If both x and y are provided and y is a function then it will be called as y(x, **params). If x is a function it will be called as x(**params)

fmtstr, optional

A format string, e.g. ‘ro’ for red circles. See matplotlib.pyplot.plot for full documentation. as xlim

parametricboolean

If True then the function expects to have only received a value for y and that that function will return an array for both x and y, or will return an array with shape (N, 2)

axmatplotlib axis, optional

The axis on which to plot. If none the current axis will be used.

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses the new {} style formatting

xlimstring or tuple of floats, optional

If a tuple it will be passed to ax.set_xlim. Other options are: ‘auto’: rescale the x axis for every redraw ‘stretch’: only ever expand the xlims.

ylimstring or tuple of floats, optional

If a tuple it will be passed to ax.set_ylim. Other options are same as xlim

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

Returns

controls

Examples

With numpy arrays:

x = np.linspace(0,2*np.pi)
tau = np.linspace(0, np.pi)
def f(tau):
    return np.sin(x*tau)
interactive_plot(f, tau=tau)

with tuples:

x = np.linspace(0,2*np.pi)
def f(x, tau):
    return np.sin(x+tau)
interactive_plot(x, f, tau=(0, np.pi, 1000))

interactive_scatter(x, y=None, s=None, c=None, cmap=None, vmin=None, vmax=None, alpha=None, marker=None, edgecolors=None, facecolors=None, label=None, parametric=False, ax=None, slider_formats=None, xlim='stretch', ylim='stretch', force_ipywidgets=False, play_buttons=False, controls=None, display_controls=True, **kwargs)[source]¶

Control a scatter plot using widgets.

Parameters

x, yfunction or float or array-like

shape (n, ) for array-like. Functions must return the correct shape as well. If y is None then parametric must be True and the function for x must return x, y

carray-like or list of colors or color or Callable

Valid input to plt.scatter or a function

sfloat, array-like, function, or index controls object

valid input to plt.scatter, or a function

alphafloat, None, or function(s), broadcastable

Affects all scatter points. This will compound with any alpha introduced by the c argument

markerMarkerStyle, or Callable, optional

The marker style or a function returning marker styles.

edgecolor[s]callable or valid argument to scatter

passed through to scatter.

facecolor[s]callable or valid argument to scatter

Valid input to plt.scatter, or a function

labelstring

Passed through to Matplotlib

parametricboolean

If True then the function expects to have only received a value for y and that that function will return an array for both x and y, or will return an array with shape (N, 2)

axmatplotlib axis, optional

The axis on which to plot. If none the current axis will be used.

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses the new {} style formatting

xlimstring or tuple of floats, optional

If a tuple it will be passed to ax.set_xlim. Other options are: ‘auto’: rescale the x axis for every redraw ‘stretch’: only ever expand the xlims.

ylimstring or tuple of floats, optional

If a tuple it will be passed to ax.set_ylim. Other options are same as xlim

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

Returns

controls

interactive_title(title, controls=None, ax=None, *, fontdict=None, loc=None, y=None, pad=None, slider_formats=None, display_controls=True, play_buttons=False, force_ipywidgets=False, **kwargs)[source]¶

Set an title that will update interactively. kwargs for matplotlib.text.Text will be passed through, other kwargs will be used to create interactive controls.

Parameters

titlestr or function

The title text. Can include {} style formatting. e.g. ‘The voltage is {volts:.2f} mV’

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

axmatplotlib.axes.Axes, optional

The axis on which to plot. If none the current axis will be used.

loc{‘center’, ‘left’, ‘right’}, default: axes.titlelocation

Which title to set.

yfloat, default: axes.titley

Vertical axes loation for the title (1.0 is the top). If None (the default), y is determined automatically to avoid decorators on the axes.

padfloat, default: axes.titlepad

The offset of the title from the top of the axes, in points.

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses {} style formatting

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

Returns

controls

interactive_xlabel(xlabel, controls=None, ax=None, *, fontdict=None, labelpad=None, loc=None, slider_formats=None, display_controls=True, play_buttons=False, force_ipywidgets=False, **kwargs)[source]¶

Set an xlabel that will update interactively. kwargs for matplotlib.text.Text will be passed through, other kwargs will be used to create interactive controls.

Parameters

xlabelstr or function

The label text. Can include {} style formatting. e.g. ‘The voltage is {volts:.2f} mV’

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

axmatplotlib axis, optional

The axis on which to plot. If none the current axis will be used.

labelpadfloat, default: None

Spacing in points from the axes bounding box including ticks and tick labels.

loc{‘bottom’, ‘center’, ‘top’}, default: yaxis.labellocation

The label position. This is a high-level alternative for passing parameters y and horizontalalignment.

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses {} style formatting

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

Returns

controls

interactive_ylabel(ylabel, controls=None, ax=None, *, fontdict=None, labelpad=None, loc=None, slider_formats=None, display_controls=True, play_buttons=False, force_ipywidgets=False, **kwargs)[source]¶

Set a ylabel that will update interactively. kwargs for matplotlib.text.Text will be passed through, other kwargs will be used to create interactive controls.

Parameters

ylabelstr or function

The label text. Can include {} style formatting. e.g. ‘The voltage is {volts:.2f}’

controlsmpl_interactions.controller.Controls

An existing controls object if you want to tie multiple plot elements to the same set of controls

axmatplotlib axis, optional

The axis on which to plot. If none the current axis will be used.

labelpadfloat, default: None

Spacing in points from the axes bounding box including ticks and tick labels.

loc{‘bottom’, ‘center’, ‘top’}, default: yaxis.labellocation

The label position. This is a high-level alternative for passing parameters y and horizontalalignment.

slider_formatsNone, string, or dict

If None a default value of decimal points will be used. Uses {} style formatting

display_controlsboolean

Whether the controls should display on creation. Ignored if controls is specified.

play_buttonsbool or str or dict, optional

Whether to attach an ipywidgets.Play widget to any sliders that get created. If a boolean it will apply to all kwargs, if a dictionary you choose which sliders you want to attach play buttons too.

None: no sliders
True: sliders on the lft
False: no sliders
‘left’: sliders on the left
‘right’: sliders on the right

force_ipywidgetsboolean

If True ipywidgets will always be used, even if not using the ipympl backend. If False the function will try to detect if it is ok to use ipywidgets If ipywidgets are not used the function will fall back on matplotlib widgets

Returns

controls