mpl_interactions.pyplot module

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)

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)

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)

Control the contents of a histogram using widgets.

See mpl-extensions/mpl-interactions#73 for a discussion of the limitations of this function. These limitations will can improved once matplotlib/matplotlib#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.

**kwargs

Converted to widgets to control the parameters. Note, unlike other functions the remaining will NOT be passed through to hist.

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, alpha=None, vmin=None, vmax=None, vmin_vmax=None, autoscale_cmap=True, ax=None, slider_formats=None, force_ipywidgets=False, play_buttons=False, controls=None, display_controls=True, **kwargs)

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.

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.

vmin, vmaxfloat, callable, shorthand for slider or indexed controls

The vmin, vmax values for the colormap. 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.

vmin_vmaxtuple of float

Used to generate a range slider for vmin and vmax. Should be given in range slider notation: ("r", 0, 1).

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

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.

**kwargs:

Interpreted as widgets and remainder are passed through to ax.imshow.

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)

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.

**kwargs:

Interpreted as widgets and remainder are passed through to ax.plot.

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, vmin=None, vmax=None, vmin_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)

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

vmin, vmaxfloat, callable, shorthand for slider or indexed controls

The vmin, vmax values for the colormap. 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.

vmin_vmaxtuple of float

Used to generate a range slider for vmin and vmax. Should be given in range slider notation: ("r", 0, 1).

alphafloat or Callable, optional

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.

edgecolorscallable or valid argument to scatter

passed through to scatter.

facecolorscallable 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.

**kwargs:

Interpreted as widgets and remainder are passed through to ax.scatter.

Returns:

controls

interactive_text(x, y, s, fontdict=None, controls=None, ax=None, *, slider_formats=None, display_controls=True, play_buttons=False, force_ipywidgets=False, **kwargs)

Create a text object that will update interactively.

kwargs for matplotlib.text.Text will be passed through, other kwargs will be used to create interactive controls.

Note

fontdict properties are currently static see mpl-extensions/mpl-interactions#247

Parameters:

x, yfloat or function

The text position.

sstr or function

The text. Can either be static text, a function returning a string or can include {} style formatting. e.g. ‘The voltage is {volts:.2f}’

fontdictdict[str]

Passed through to the Text object. Currently not dynamically updateable. See mpl-extensions/mpl-interactions#247

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.

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

**kwargs

Used to create widgets to control parameters. Kwargs for Text objects will passed through.

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)

Set the title to 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.

fontdictdict[str]

Passed through to the Text object. Currently not dynamically updateable. See mpl-extensions/mpl-interactions#247

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

**kwargs:

Passed through to ax.set_title

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)

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.

fontdictdict[str]

Passed through to the Text object. Currently not dynamically updateable. See mpl-extensions/mpl-interactions#247

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

**kwargs

Used to create widgets to control parameters. Kwargs for Text objects will passed through.

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)

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.

fontdictdict[str]

Passed through to the Text object. Currently not dynamically updateable. See mpl-extensions/mpl-interactions#247

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

**kwargs

Used to create widgets to control parameters. Kwargs for Text objects will passed through.

Returns:

controls