hyperspy.api.plot#

hyperspy.api.plot.markers

Markers that can be added to BaseSignal plots.

hyperspy.api.plot.plot_histograms(signal_list)

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

hyperspy.api.plot.plot_images(images[, ...])

Plot multiple images either as sub-images or overlayed in one figure.

hyperspy.api.plot.plot_roi_map(signal[, ...])

Plot one or multiple ROI maps of a signal.

hyperspy.api.plot.plot_signals(signal_list)

Plot several signals at the same time.

hyperspy.api.plot.plot_spectra(spectra[, ...])

Plot several spectra in the same figure.

Plotting funtions.

Functions:

plot_images

Plot multiple images in the same figure.

plot_spectra

Plot multiple spectra in the same figure.

plot_signals

Plot multiple signals at the same time.

plot_histograms

Compute and plot the histograms of multiple signals in the same figure.

plot_roi_map

Plot a the spatial variation of a signal sliced by a ROI in the signal space.

The hyperspy.api.plot module contains the following submodules:

hyperspy.api.plot.markers

Markers that can be added to BaseSignal figure.

hyperspy.api.plot.plot_histograms(signal_list, bins='fd', range_bins=None, color=None, linestyle=None, legend='auto', fig=None, **kwargs)#

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

This function creates a histogram for each signal and plots the list with the plot_spectra() function.

Parameters:
signal_listiterable

Ordered list of spectra to plot. If style is "cascade" or "mosaic", the spectra can have different size and axes.

binsint, list or str, optional

If bins is a string, then it must be one of:

  • 'knuth' : use Knuth’s rule to determine bins,

  • 'scott' : use Scott’s rule to determine bins,

  • 'fd' : use the Freedman-diaconis rule to determine bins,

  • 'blocks' : use bayesian blocks for dynamic bin widths.

range_binsNone or tuple, optional

The minimum and maximum range for the histogram. If not specified, it will be (x.min(), x.max()).

colorNone, (list of) matplotlib color, optional

Sets the color of the lines of the plots. For 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.

linestyleNone, (list of) matplotlib line style, optional

The main line styles are '-', '--', '-.', ':'. For a list, if its length is less than the number of spectra to plot, linestyle will be cycled. If None, use continuous lines (same as '-').

legendNone, list of str, 'auto', default 'auto'

Display a legend. If ‘auto’, the title of each spectra (metadata.General.title) is used.

legend_pickingbool, default True

If True, a spectrum can be toggled on and off by clicking on the line in the legend.

figNone, matplotlib.figure.Figure, default None

If None (default), a default figure will be created.

**kwargs

other keyword arguments (weight and density) are described in numpy.histogram().

Returns:
matplotlib.axes.Axes or list of matplotlib.axes.Axes

An array is returned when style='mosaic'.

Examples

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'])
<Axes: xlabel='value (<undefined>)', ylabel='Intensity'>
hyperspy.api.plot.plot_images(images, cmap=None, no_nans=False, per_row=3, label='auto', labelwrap=30, suptitle=None, suptitle_fontsize=18, colorbar='default', centre_colormap='auto', 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, overlay=False, colors='auto', alphas=1.0, legend_picking=True, legend_loc='upper right', pixel_size_factor=None, **kwargs)#

Plot multiple images either as sub-images or overlayed in one figure.

Parameters:
imageslist 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 transposed to form a Signal2D. Multi-dimensional images will have each plane plotted as a separate image. If any of the signal shapes is not suitable, a ValueError will be raised.

cmapNone, (list of) matplotlib.colors.Colormap or str, default None

The colormap used for the images, by default uses the setting color map signal from the plot preferences. 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_nansbool, optional

If True, set nans to zero for plotting.

per_rowint, optional

The number of plots in each row.

labelNone, str, 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).

labelwrapint, 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 figures.

suptitlestr, optional

Title to use at the top of the figure. If called with label=’auto’, this parameter will override the automatically determined title.

suptitle_fontsizeint, optional

Font size to use for super title at top of figure.

colorbar‘default’, ‘multi’, ‘single’, None, optional

Controls the type of colorbars that are plotted, incompatible with overlay=True. If ‘default’, same as ‘multi’ when overlay=False, otherwise same as None. If ‘multi’, 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. If None, no colorbar is plotted.

centre_colormap‘auto’, True, False, optional

If True, the centre of the color scheme is set to zero. This is particularly useful when using diverging color schemes. If ‘auto’ (default), diverging color schemes are automatically centred.

scalebarNone, ‘all’, list of int, 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_colorstr, 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.

paddingNone, 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 matplotlib.pyplot.subplots_adjust(), and can be ‘left’, ‘bottom’, ‘right’, ‘top’, ‘wspace’ (width) and ‘hspace’ (height).

tight_layoutbool, 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.

aspectstr, float, int, 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_aspfloat, optional

Minimum aspect ratio to be used when plotting images.

namefrac_threshfloat, 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.

figmatplotlib.figure.Figure, default None

If set, the images will be plotted to an existing matplotlib figure.

vmin, vmax: scalar, str, None

If str, formatted as ‘xth’, use this value to calculate the percentage of pixels that are left out of the lower and upper bounds. For example, for a vmin of ‘1th’, 1% of the lowest will be ignored to estimate the minimum value. Similarly, for a vmax value of ‘1th’, 1% of the highest value will be ignored in the estimation of the maximum value. It must be in the range [0, 100]. See numpy.percentile() for more explanation. If None, use the percentiles value set in the preferences. If float or integer, keep this value as bounds. Note: vmin is ignored when overlaying images.

overlaybool, optional

If True, overlays the images with different colors rather than plotting each image as a subplot.

colors‘auto’, list of str, optional

If list, it must contains colors acceptable to matplotlib [1]. If 'auto', colors will be taken from matplotlib.colors.BASE_COLORS.

alphasfloat or list of float, optional

Float value or a list of floats corresponding to the alpha value of each color.

legend_picking: bool, optional

If True (default), an image can be toggled on and off by clicking on the legended line. For overlay=True only.

legend_locstr, int, optional

This parameter controls where the legend is placed on the figure see the matplotlib.pyplot.legend() docstring for valid values

pixel_size_factorNone, int or float, optional

If None (default), the size of the figure is taken from the matplotlib rcParams. Otherwise sets the size of the figure when plotting an overlay image. The higher the number the larger the figure and therefore a greater number of pixels are used. This value will be ignored if a Figure is provided.

**kwargs, optional

Additional keyword arguments passed to matplotlib.pyplot.imshow().

Returns:
axes_listlist

A list of subplot axes that hold the images.

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.

References

hyperspy.api.plot.plot_roi_map(signal, rois=1, color=None, cmap=None, single_figure=False, single_figure_kwargs=None, **kwargs)#

Plot one or multiple ROI maps of a signal.

Uses regions of interest (ROIs) to select ranges along the signal axis.

For each ROI, a plot is generated of the summed data values within this signal ROI at each point in the signal’s navigation space.

The ROIs can be moved interactively and the corresponding map plots will update automatically.

Parameters:
signalBaseSignal

The signal to inspect.

roisint, subclass of hyperspy.roi.BaseROI or list of hyperspy.roi.BaseROI

ROIs to slice the signal in signal space. If int, define the number of ROIs to use.

colorlist of str or None

Color of the ROIs. Any string supported by matplotlib to define a color can be used. The length of the list must be equal to the number ROIs. If None (default), the default matplotlib colors are used.

cmapstr of list of str or None

Only for signals with navigation dimension of 2. Define the colormap of the map(s). If string, any string supported by matplotlib to define a colormap can be used and a colored frame matching the ROI color will be added to the map. If list of str, it must be the same length as the ROIs. If None (default), the colors from the color argument are used and no colored frame is added.

single_figurebool

Whether to plot on a single figure or several figures. If True, plot_images() or plot_spectra() will be used, depending on the navigation dimension of the signal.

single_figure_kwargsdict

Only when single_figure=True. Keywords arguments are passed to plot_images() or plot_spectra() depending on the navigation dimension of the signal. If None, default kwargs are used with the following changes scalebar=[0], axes_decor="off" and suptitle="".

**kwargsdict

The keyword argument are passed to plot().

Returns:
roislist of hyperspy.roi.BaseROI

The ROI objects that slice signal.

roi_sumsBaseSignal

The sums of the signals defined by the ROIs.

Notes

Performance consideration:

Examples

3D hyperspectral data

For 3D hyperspectral data, the ROIs used will be instances of SpanROI. Therefore, these ROIs can be used to select particular spectral ranges, e.g. a particular peak.

The map generated for a given ROI is therefore the sum of this spectral region at each point in the hyperspectral map. Therefore, regions of the sample where this peak is bright will be bright in this map.

4D STEM

For 4D STEM data, by default, the ROIs used will be instances of RectangularROI. Other hyperspy ROIs, such as CircleROI can be used. These ROIs can be used to select particular regions in reciprocal space, e.g. a particular diffraction spot.

The map generated for a given ROI is the intensity of this region at each point in the scan. Therefore, regions of the scan where a particular spot is intense will appear bright.

hyperspy.api.plot.plot_signals(signal_list, sync=True, navigator='auto', navigator_list=None, **kwargs)#

Plot several signals at the same time.

Parameters:
signal_listlist of BaseSignal

If sync is set to True, the signals must have the same navigation shape, but not necessarily the same signal shape.

syncbool, optional

If True (default), 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.

navigatorNone, BaseSignal or str
{``’auto’`` | ``’spectrum’`` | ``’slider’`` }, default ``”auto”``

See signal.plot docstring for full description.

navigator_listNone, list of BaseSignal or list of str, 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.

**kwargsdict

Any extra keyword arguments are passed to each signal plot method.

Examples

>>> s1 = hs.signals.Signal1D(np.arange(100).reshape((10, 10)))
>>> s2 = hs.signals.Signal1D(np.arange(100).reshape((10, 10)) * -1)
>>> hs.plot.plot_signals([s1, s2])

Specifying the navigator:

>>> hs.plot.plot_signals([s1, s2], navigator="slider") 

Specifying the navigator for each signal:

>>> s3 = hs.signals.Signal1D(np.ones((10, 10)))
>>> s_nav = hs.signals.Signal1D(np.ones((10)))
>>> hs.plot.plot_signals(
...    [s1, s2, s3], navigator_list=["slider", None, s_nav]
...    ) 
hyperspy.api.plot.plot_spectra(spectra, style='overlap', color=None, linestyle=None, drawstyle='default', padding=1.0, legend=None, legend_picking=True, legend_loc='upper right', fig=None, ax=None, auto_update=None, **kwargs)#

Plot several spectra in the same figure.

Parameters:
spectralist 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 transposed to form a Signal1D.

style{'overlap' | 'cascade' | 'mosaic' | 'heatmap'}, default ‘overlap’

The style of the plot: ‘overlap’ (default), ‘cascade’, ‘mosaic’, or ‘heatmap’.

colorNone or (list of) matplotlib color, default None

Sets the color of the lines of the plots (no action on ‘heatmap’). For a list, if its length is less than the number of spectra to plot, the colors will be cycled. If None (default), use default matplotlib color cycle.

linestyleNone or (list of) matplotlib line style, default None

Sets the line style of the plots (no action on ‘heatmap’). The main line style are '-', '--', '-.', ':'. For a list, if its length is less than the number of spectra to plot, linestyle will be cycled. If None, use continuous lines (same as '-').

drawstyle{'default' | 'steps' | 'steps-pre' | 'steps-mid' | 'steps-post'},

default ‘default’ The drawstyle determines how the points are connected, no action with style='heatmap'. See matplotlib.lines.Line2D.set_drawstyle() for more information. The 'default' value is defined by matplotlib.

paddingfloat, default 1.0

Option for “cascade”. 1 guarantees that there is no 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.

legendNone, list of str, 'auto', default None

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. Default None.

legend_pickingbool, default True

If True (default), a spectrum can be toggled on and off by clicking on the legended line.

legend_locstr or int, optional

This parameter controls where the legend is placed on the figure; see the pyplot.legend docstring for valid values. Default 'upper right'.

figNone, matplotlib.figure.Figure, default None

If None (default), a default figure will be created. Specifying fig will not work for the ‘heatmap’ style.

axNone, matplotlib.axes.Axes, default None

If None (default), a default ax will be created. Will not work for 'mosaic' or 'heatmap' style.

auto_updatebool or None, default None

If True, the plot will update when the data are changed. Only supported with style=’overlap’ and a list of signal with navigation dimension 0. If None (default), update the plot only for style=’overlap’.

**kwargsdict

Depending on the style used, the keyword arguments are passed to different functions

Returns:
matplotlib.axes.Axes or list of matplotlib.axes.Axes

An array is returned when style is ‘mosaic’.

Examples

>>> s = hs.signals.Signal1D(np.arange(100).reshape((10, 10)))
>>> hs.plot.plot_spectra(s, style='cascade', color='red', padding=0.5)
<Axes: xlabel='<undefined> (<undefined>)'>

To save the plot as a png-file

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