hyperspy.drawing.utils module¶

class hyperspy.drawing.utils.ColorCycle¶: Bases: object

hyperspy.drawing.utils.animate_legend(fig=None, ax=None)¶

Animate the legend of a figure.

A spectrum can be toggle on and off by clicking on the legended line.

Parameters

fig (None | matplotlib.figure) – If None pick the current figure using “plt.gcf”
ax (None | matplotlib.axes) – If None pick the current axes using “plt.gca”.

Note

Code inspired from legend_picking.py in the matplotlib gallery

hyperspy.drawing.utils.centre_colormap_values(vmin, vmax)¶

Calculate vmin and vmax to set the colormap midpoint to zero.

Parameters: vmax (vmin,) – The range of data to display.
Returns: cvmin, cvmax – The values to obtain a centre colormap.
Return type: scalar

hyperspy.drawing.utils.contrast_stretching(data, saturated_pixels)¶

Calculate bounds that leaves out a given percentage of the data.

Parameters

data (numpy array) –
saturated_pixels (scalar, None) – The percentage of pixels that are left out of the bounds. For example, the low and high bounds of a value of 1 are the 0.5% and 99.5% percentiles. It must be in the [0, 100] range. If None, set the value to 0.

Returns

vmin, vmax – The low and high bounds

Return type

scalar

Raises

ValueError if the value of saturated_pixels is out of the valid range. –

hyperspy.drawing.utils.create_figure(window_title=None, _on_figure_window_close=None, disable_xyscale_keys=False, **kwargs)¶

Create a matplotlib figure.

This function adds the possibility to execute another function when the figure is closed and to easily set the window title. Any keyword argument is passed to the plt.figure function

Parameters

window_title (string) –
_on_figure_window_close (function) –
disable_xyscale_keys (bool, disable the k, l and L shortcuts which) –
the x or y axis between linear and log scale. (toggle) –

Returns

fig

Return type

plt.figure

hyperspy.drawing.utils.key_press_handler_custom(event, canvas)¶

hyperspy.drawing.utils.make_cmap(colors, name='my_colormap', position=None, bit=False, register=True)¶

Create a matplotlib colormap with customized colors, optionally registering it with matplotlib for simplified use.

Adapted from Chris Slocum’s code at: https://github.com/CSlocumWX/custom_colormap/blob/master/custom_colormaps.py and used under the terms of that code’s BSD-3 license

Parameters

colors (iterable) – list of either tuples containing rgb values, or html strings Colors should be arranged so that the first color is the lowest value for the colorbar and the last is the highest.
name (str) – name of colormap to use when registering with matplotlib
position (None or iterable) – list containing the values (from [0,1]) that dictate the position of each color within the colormap. If None (default), the colors will be equally-spaced within the colorbar.
bit (boolean) – True if RGB colors are given in 8-bit [0 to 255] or False if given in arithmetic basis [0 to 1] (default)
register (boolean) – switch to control whether or not to register the custom colormap with matplotlib in order to enable use by just the name string

hyperspy.drawing.utils.on_figure_window_close(figure, function)¶

Connects a close figure signal to a given function.

Parameters

figure (mpl figure instance) –
function (function) –

hyperspy.drawing.utils.plot_RGB_map(im_list, normalization='single', dont_plot=False)¶

Plot 2 or 3 maps in RGB.

Parameters

im_list (list of Signal2D instances) –
normalization ({'single', 'global'}) –
dont_plot (bool) –

Returns

array

Return type

RGB matrix

hyperspy.drawing.utils.plot_histograms(signal_list, bins='freedman', range_bins=None, color=None, line_style=None, legend='auto', fig=None, **kwargs)¶

Plot the histogram of every signal in the list in the same figure.

This function creates a histogram for each signal and plot the list with the utils.plot.plot_spectra function.

Parameters

signal_list (iterable) – Ordered spectra list to plot. If style is “cascade” or “mosaic” the spectra can have different size and axes.
bins (int or list or str, optional) – If bins is a string, then it must be one of: ‘knuth’ : use Knuth’s rule to determine bins ‘scotts’ : use Scott’s rule to determine bins ‘freedman’ : use the Freedman-diaconis rule to determine bins ‘blocks’ : use bayesian blocks for dynamic bin widths
range_bins (tuple or None, optional.) – the minimum and maximum range for the histogram. If not specified, it will be (x.min(), x.max())
color (valid matplotlib color or a list of them or None, optional.) – Sets the color of the lines of the plots. If a list, if its length is less than the number of spectra to plot, the colors will be cycled. If If None, use default matplotlib color cycle.
line_style (valid matplotlib line style or a list of them or None,) –
optional. – The main line style are ‘-‘,’–’,’steps’,’-.’,’:’. If a list, if its length is less than the number of spectra to plot, line_style will be cycled. If If None, use continuous lines, eg: (‘-‘,’–’,’steps’,’-.’,’:’)
legend (None or list of str or 'auto', optional.) – Display a legend. If ‘auto’, the title of each spectra (metadata.General.title) is used.
legend_picking (bool, optional.) – If true, a spectrum can be toggle on and off by clicking on the legended line.
fig (matplotlib figure or None, optional.) – If None, a default figure will be created.
**kwargs – other keyword arguments (weight and density) are described in np.histogram().

Example

Histograms of two random chi-square distributions

>>> img = hs.signals.Signal2D(np.random.chisquare(1,[10,10,100]))
>>> img2 = hs.signals.Signal2D(np.random.chisquare(2,[10,10,100]))
>>> hs.plot.plot_histograms([img,img2],legend=['hist1','hist2'])

Returns: ax – An array is returned when style is “mosaic”.
Return type: matplotlib axes or list of matplotlib axes

hyperspy.drawing.utils.plot_images(images, cmap=None, no_nans=False, per_row=3, label='auto', labelwrap=30, suptitle=None, suptitle_fontsize=18, colorbar='multi', centre_colormap='auto', saturated_pixels=None, scalebar=None, scalebar_color='white', axes_decor='all', padding=None, tight_layout=False, aspect='auto', min_asp=0.1, namefrac_thresh=0.4, fig=None, vmin=None, vmax=None, *args, **kwargs)¶

Plot multiple images as sub-images in one figure.

Extra keyword arguments are passed to matplotlib.figure.

Parameters

images (list of Signal2D or BaseSignal) – images should be a list of Signals to plot. For BaseSignal with navigation dimensions 2 and signal dimension 0, the signal will be tranposed to form a Signal2D. Multi-dimensional images will have each plane plotted as a separate image. If any signal shape is not suitable, a ValueError will be raised.
cmap (matplotlib colormap, list, or 'mpl_colors', optional) – The colormap used for the images, by default read from pyplot. A list of colormaps can also be provided, and the images will cycle through them. Optionally, the value 'mpl_colors' will cause the cmap to loop through the default matplotlib colors (to match with the default output of the plot_spectra() method. Note: if using more than one colormap, using the 'single' option for colorbar is disallowed.
no_nans (bool, optional) – If True, set nans to zero for plotting.
per_row (int, optional) – The number of plots in each row
label (None, str, or list of str, optional) – Control the title labeling of the plotted images. If None, no titles will be shown. If ‘auto’ (default), function will try to determine suitable titles using Signal2D titles, falling back to the ‘titles’ option if no good short titles are detected. Works best if all images to be plotted have the same beginning to their titles. If ‘titles’, the title from each image’s metadata.General.title will be used. If any other single str, images will be labeled in sequence using that str as a prefix. If a list of str, the list elements will be used to determine the labels (repeated, if necessary).
labelwrap (int, optional) – integer specifying the number of characters that will be used on one line If the function returns an unexpected blank figure, lower this value to reduce overlap of the labels between each figure
suptitle (str, optional) – Title to use at the top of the figure. If called with label=’auto’, this parameter will override the automatically determined title.
suptitle_fontsize (int, optional) – Font size to use for super title at top of figure
colorbar ({'multi', None, 'single'}) – Controls the type of colorbars that are plotted. If None, no colorbar is plotted. If ‘multi’ (default), individual colorbars are plotted for each (non-RGB) image If ‘single’, all (non-RGB) images are plotted on the same scale, and one colorbar is shown for all
centre_colormap ({"auto", True, False}) – If True the centre of the color scheme is set to zero. This is specially useful when using diverging color schemes. If “auto” (default), diverging color schemes are automatically centred.
saturated_pixels (None, scalar or list of scalar, optional, default: 0) – If list of scalar, the length should match the number of images to show. If provide in the list, set the value to 0. The percentage of pixels that are left out of the bounds. For example, the low and high bounds of a value of 1 are the 0.5% and 99.5% percentiles. It must be in the [0, 100] range.
scalebar ({None, 'all', list of ints}, optional) – If None (or False), no scalebars will be added to the images. If ‘all’, scalebars will be added to all images. If list of ints, scalebars will be added to each image specified.
scalebar_color (str, optional) – A valid MPL color string; will be used as the scalebar color
axes_decor ({'all', 'ticks', 'off', None}, optional) – Controls how the axes are displayed on each image; default is ‘all’ If ‘all’, both ticks and axis labels will be shown If ‘ticks’, no axis labels will be shown, but ticks/labels will If ‘off’, all decorations and frame will be disabled If None, no axis decorations will be shown, but ticks/frame will
padding (None or dict, optional) –
This parameter controls the spacing between images. If None, default options will be used Otherwise, supply a dictionary with the spacing options as keywords and desired values as values Values should be supplied as used in pyplot.subplots_adjust(), and can be:

’left’, ‘bottom’, ‘right’, ‘top’, ‘wspace’ (width), and ‘hspace’ (height)
tight_layout (bool, optional) – If true, hyperspy will attempt to improve image placement in figure using matplotlib’s tight_layout If false, repositioning images inside the figure will be left as an exercise for the user.
aspect (str or numeric, optional) – If ‘auto’, aspect ratio is auto determined, subject to min_asp. If ‘square’, image will be forced onto square display. If ‘equal’, aspect ratio of 1 will be enforced. If float (or int/long), given value will be used.
min_asp (float, optional) – Minimum aspect ratio to be used when plotting images
namefrac_thresh (float, optional) – Threshold to use for auto-labeling. This parameter controls how much of the titles must be the same for the auto-shortening of labels to activate. Can vary from 0 to 1. Smaller values encourage shortening of titles by auto-labeling, while larger values will require more overlap in titles before activing the auto-label code.
fig (mpl figure, optional) – If set, the images will be plotted to an existing MPL figure
vmax (vmin,) – If list of scalar, the length should match the number of images to show. A list of scalar is not compatible with a single colorbar. See vmin, vmax of matplotlib.imshow() for more details.
**kwargs, optional (*args,) –
Additional arguments passed to matplotlib.imshow()

Returns

axes_list – a list of subplot axes that hold the images

Return type

list

See also

plot_spectra(): Plotting of multiple spectra
plot_signals(): Plotting of multiple signals
plot_histograms(): Compare signal histograms

Notes

interpolation is a useful parameter to provide as a keyword argument to control how the space between pixels is interpolated. A value of 'nearest' will cause no interpolation between pixels.

tight_layout is known to be quite brittle, so an option is provided to disable it. Turn this option off if output is not as expected, or try adjusting label, labelwrap, or per_row

hyperspy.drawing.utils.plot_signals(signal_list, sync=True, navigator='auto', navigator_list=None, **kwargs)¶

Plot several signals at the same time.

Parameters

signal_list (list of BaseSignal instances) – If sync is set to True, the signals must have the same navigation shape, but not necessarily the same signal shape.
sync (True or False, default "True") – If True: the signals will share navigation, all the signals must have the same navigation shape for this to work, but not necessarily the same signal shape.
navigator ({"auto", None, "spectrum", "slider", BaseSignal}, default "auto") – See signal.plot docstring for full description
navigator_list ({List of navigator arguments, None}, default None) – Set different navigator options for the signals. Must use valid navigator arguments: “auto”, None, “spectrum”, “slider”, or a hyperspy Signal. The list must have the same size as signal_list. If None, the argument specified in navigator will be used.
**kwargs – Any extra keyword arguments are passed to each signal plot method.

Example

>>> s_cl = hs.load("coreloss.dm3")
>>> s_ll = hs.load("lowloss.dm3")
>>> hs.plot.plot_signals([s_cl, s_ll])

Specifying the navigator:

>>> s_cl = hs.load("coreloss.dm3")
>>> s_ll = hs.load("lowloss.dm3")
>>> hs.plot.plot_signals([s_cl, s_ll], navigator="slider")

Specifying the navigator for each signal:

>>> s_cl = hs.load("coreloss.dm3")
>>> s_ll = hs.load("lowloss.dm3")
>>> s_edx = hs.load("edx.dm3")
>>> s_adf = hs.load("adf.dm3")
>>> hs.plot.plot_signals(
        [s_cl, s_ll, s_edx], navigator_list=["slider",None,s_adf])

hyperspy.drawing.utils.plot_spectra(spectra, style='overlap', color=None, line_style=None, padding=1.0, legend=None, legend_picking=True, legend_loc='upper right', fig=None, ax=None, **kwargs)¶

Plot several spectra in the same figure.

Extra keyword arguments are passed to matplotlib.figure.

Parameters

spectra (list of Signal1D or BaseSignal) – Ordered spectra list of signal to plot. If style is “cascade” or “mosaic” the spectra can have different size and axes. For BaseSignal with navigation dimensions 1 and signal dimension 0, the signal will be tranposed to form a Signal1D.
style ({'overlap', 'cascade', 'mosaic', 'heatmap'}) – The style of the plot.
color (matplotlib color or a list of them or None) – Sets the color of the lines of the plots (no action on ‘heatmap’). If a list, if its length is less than the number of spectra to plot, the colors will be cycled. If None, use default matplotlib color cycle.
line_style (matplotlib line style or a list of them or None) – Sets the line style of the plots (no action on ‘heatmap’). The main line style are ‘-‘,’–’,’steps’,’-.’,’:’. If a list, if its length is less than the number of spectra to plot, line_style will be cycled. If If None, use continuous lines, eg: (‘-‘,’–’,’steps’,’-.’,’:’)
padding (float, optional, default 0.1) – Option for “cascade”. 1 guarantees that there is not overlapping. However, in many cases a value between 0 and 1 can produce a tighter plot without overlapping. Negative values have the same effect but reverse the order of the spectra without reversing the order of the colors.
legend (None or list of str or 'auto') – If list of string, legend for “cascade” or title for “mosaic” is displayed. If ‘auto’, the title of each spectra (metadata.General.title) is used.
legend_picking (bool) – If true, a spectrum can be toggle on and off by clicking on the legended line.
legend_loc (str or int) – This parameter controls where the legend is placed on the figure; see the pyplot.legend docstring for valid values
fig (matplotlib figure or None) – If None, a default figure will be created. Specifying fig will not work for the ‘heatmap’ style.
ax (matplotlib ax (subplot) or None) – If None, a default ax will be created. Will not work for ‘mosaic’ or ‘heatmap’ style.
**kwargs – remaining keyword arguments are passed to matplotlib.figure() or matplotlib.subplots(). Has no effect on ‘heatmap’ style.

Example

>>> s = hs.load("some_spectra")
>>> hs.plot.plot_spectra(s, style='cascade', color='red', padding=0.5)

To save the plot as a png-file

>>> hs.plot.plot_spectra(s).figure.savefig("test.png")

Returns: ax – An array is returned when style is “mosaic”.
Return type: matplotlib axes or list of matplotlib axes

hyperspy.drawing.utils.set_axes_decor(ax, axes_decor)¶

hyperspy.drawing.utils.set_xaxis_lims(mpl_ax, hs_axis)¶

Set the matplotlib axis limits to match that of a HyperSpy axis

Parameters

mpl_ax (matplotlib.axis.Axis) – The matplotlib axis to change
hs_axis (DataAxis) – The data axis that contains the values that control the scaling

hyperspy.drawing.utils.subplot_parameters(fig)¶

Returns a list of the subplot parameters of a mpl figure.

Parameters: fig (mpl figure) –
Returns: tuple
Return type: (left, bottom, right, top, wspace, hspace)