pyplot
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
- 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_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 asy(x, **params)
. If x is a function it will be called asx(**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
- 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.
- 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