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

  • y (float or function) – y position in data coordinates of the horizontal line.

  • xmin (float or function) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right of the plot.

  • xmax (float or function) – Should be between 0 and 1, 0 being the far left of the plot, 1 the far right of the plot.

  • ax (matplotlib axis, optional) – If None a new figure and axis will be created

  • slider_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses the new {} style formatting

  • force_ipywidgets (boolean) – 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_buttons (bool 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

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • display_controls (boolean) – 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

  • x (float or function) – x position in data coordinates of the horizontal line.

  • ymin (float or function) – Should be between 0 and 1, 0 being the bottom of the plot, 1 the far top of the plot

  • ymax (float or function) – Should be between 0 and 1, 0 being the top of the plot, 1 the top of the plot.

  • ax (matplotlib axis, optional) – If None a new figure and axis will be created

  • slider_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses the new {} style formatting

  • force_ipywidgets (boolean) – 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_buttons (bool 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

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • display_controls (boolean) – 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

  • arr (arraylike or function) – The array or the function that returns an array that is to be histogrammed

  • density (bool, optional) – whether to plot as a probability density. Passed to numpy.histogram

  • bins (int or sequence of scalars or str, optional) – bins argument to numpy.histogram

  • weights (array_like, optional) – passed to numpy.histogram

  • ax (matplotlib axis, optional) – The axis on which to plot. If none the current axis will be used.

  • slider_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses the new {} style formatting

  • force_ipywidgets (boolean) – 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_buttons (bool 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

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • display_controls (boolean) – 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

  • X (function or image like) – If a function it must return an image-like object. See matplotlib.pyplot.imshow for the full set of valid options.

  • cmap (str 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

  • norm (Normalize, 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_cmap (bool) – 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

  • interpolation (str) – forwarded to matplotlib

  • alpha (float, 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.

  • ax (matplotlib axis, optional) – The axis on which to plot. If none the current axis will be used.

  • slider_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses the new {} style formatting

  • force_ipywidgets (boolean) – 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_buttons (bool 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

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • display_controls (boolean) – 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, y (array-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)

  • fmt (str, optional) – A format string, e.g. ‘ro’ for red circles. See matplotlib.pyplot.plot for full documentation. as xlim

  • parametric (boolean) – 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)

  • ax (matplotlib axis, optional) – The axis on which to plot. If none the current axis will be used.

  • slider_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses the new {} style formatting

  • xlim (string 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.

  • ylim (string or tuple of floats, optional) – If a tuple it will be passed to ax.set_ylim. Other options are same as xlim

  • force_ipywidgets (boolean) – 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_buttons (bool 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

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • display_controls (boolean) – 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, y (function 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

  • c (array-like or list of colors or color or Callable) – Valid input to plt.scatter or a function

  • s (float, array-like, function, or index controls object) – valid input to plt.scatter, or a function

  • alpha (float, None, or function(s), broadcastable) – Affects all scatter points. This will compound with any alpha introduced by the c argument

  • marker (MarkerStyle, 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

  • label (string) – Passed through to Matplotlib

  • parametric (boolean) – 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)

  • ax (matplotlib axis, optional) – The axis on which to plot. If none the current axis will be used.

  • slider_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses the new {} style formatting

  • xlim (string 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.

  • ylim (string or tuple of floats, optional) – If a tuple it will be passed to ax.set_ylim. Other options are same as xlim

  • force_ipywidgets (boolean) – 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_buttons (bool 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

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • display_controls (boolean) – 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

  • title (str or function) – The title text. Can include {} style formatting. e.g. ‘The voltage is {volts:.2f} mV’

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • ax (matplotlib.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.

  • y (float, 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.

  • pad (float, default: axes.titlepad) – The offset of the title from the top of the axes, in points.

  • slider_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses {} style formatting

  • display_controls (boolean) – Whether the controls should display on creation. Ignored if controls is specified.

  • play_buttons (bool 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_ipywidgets (boolean) – 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

  • xlabel (str or function) – The label text. Can include {} style formatting. e.g. ‘The voltage is {volts:.2f} mV’

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • ax (matplotlib axis, optional) – The axis on which to plot. If none the current axis will be used.

  • labelpad (float, 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_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses {} style formatting

  • display_controls (boolean) – Whether the controls should display on creation. Ignored if controls is specified.

  • play_buttons (bool 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_ipywidgets (boolean) – 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

  • ylabel (str or function) – The label text. Can include {} style formatting. e.g. ‘The voltage is {volts:.2f}’

  • controls (mpl_interactions.controller.Controls) – An existing controls object if you want to tie multiple plot elements to the same set of controls

  • ax (matplotlib axis, optional) – The axis on which to plot. If none the current axis will be used.

  • labelpad (float, 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_formats (None, string, or dict) – If None a default value of decimal points will be used. Uses {} style formatting

  • display_controls (boolean) – Whether the controls should display on creation. Ignored if controls is specified.

  • play_buttons (bool 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_ipywidgets (boolean) – 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