`BaseSignal`#

class hyperspy.api.signals.BaseSignal(data, **kwds)#

Bases: FancySlicing, MVA, MVATools

Attributes:

raggedbool: Whether the signal is ragged or not.
isig: Signal indexer/slicer.
inav: Navigation indexer/slicer.
metadatahyperspy.misc.utils.DictionaryTreeBrowser: The metadata of the signal.
original_metadatahyperspy.misc.utils.DictionaryTreeBrowser: The original metadata of the signal.

Examples

General signal created from a numpy or cupy array.

>>> data = np.ones((10, 10))
>>> s = hs.signals.BaseSignal(data)

Create a signal instance.

Parameters:

datanumpy.ndarray: The signal data. It can be an array of any dimensions.
axes[dict/axes], optional: List of either dictionaries or axes objects to define the axes (see the documentation of the AxesManager class for more details).
attributesdict, optional: A dictionary whose items are stored as attributes.
metadatadict, optional: A dictionary containing a set of parameters that will to stores in the metadata attribute. Some parameters might be mandatory in some cases.
original_metadatadict, optional: A dictionary containing a set of parameters that will to stores in the original_metadata attribute. It typically contains all the parameters that has been imported from the original data file.
raggedbool or None, optional: Define whether the signal is ragged or not. Overwrite the ragged value in the attributes dictionary. If None, it does nothing. Default is None.

isig#

inav#

property T#: The transpose of the signal, with signal and navigation spaces swapped. Enables calling transpose() with the default parameters as a property of a Signal.

add_gaussian_noise(std, random_state=None)#

Add Gaussian noise to the data.

The operation is performed in-place (i.e. the data of the signal is modified). This method requires the signal to have a float data type, otherwise it will raise a TypeError.

Parameters:

stdfloat: The standard deviation of the Gaussian noise.
random_stateNone, int or numpy.random.Generator, default None: Seed for the random generator.

Notes

This method uses numpy.random.normal() (or dask.array.random.normal() for lazy signals) to generate the noise.

add_marker(marker, plot_on_signal=True, plot_marker=True, permanent=False, plot_signal=True, render_figure=True)#

Add one or several markers to the signal or navigator plot and plot the signal, if not yet plotted (by default)

Parameters:

markermarkers object or iterable: The marker or iterable (list, tuple, …) of markers to add. See the Markers section in the User Guide if you want to add a large number of markers as an iterable, since this will be much faster. For signals with navigation dimensions, the markers can be made to change for different navigation indices. See the examples for info.
plot_on_signalbool, default True: If True, add the marker to the signal. If False, add the marker to the navigator
plot_markerbool, default True: If True, plot the marker.
permanentbool, default True: If False, the marker will only appear in the current plot. If True, the marker will be added to the metadata.Markers list, and be plotted with plot(plot_markers=True). If the signal is saved as a HyperSpy HDF5 file, the markers will be stored in the HDF5 signal and be restored when the file is loaded.

Examples

>>> im = hs.data.wave_image()
>>> m = hs.plot.markers.Rectangles(
...    offsets=[(1.0, 1.5)], widths=(0.5,), heights=(0.7,)
... )
>>> im.add_marker(m)

Add permanent marker:

>>> rng = np.random.default_rng(1)
>>> s = hs.signals.Signal2D(rng.random((100, 100)))
>>> marker = hs.plot.markers.Points(offsets=[(50, 60)])
>>> s.add_marker(marker, permanent=True, plot_marker=True)

Removing a permanent marker:

>>> rng = np.random.default_rng(1)
>>> s = hs.signals.Signal2D(rng.integers(10, size=(100, 100)))
>>> marker = hs.plot.markers.Points(offsets=[(10, 60)])
>>> marker.name = "point_marker"
>>> s.add_marker(marker, permanent=True)
>>> del s.metadata.Markers.point_marker

Adding many markers as a list:

>>> rng = np.random.default_rng(1)
>>> s = hs.signals.Signal2D(rng.integers(10, size=(100, 100)))
>>> marker_list = []
>>> for i in range(10):
...     marker = hs.plot.markers.Points(rng.random(2))
...     marker_list.append(marker)
>>> s.add_marker(marker_list, permanent=True)

add_poissonian_noise(keep_dtype=True, random_state=None)#

Add Poissonian noise to the data.

This method works in-place.

Parameters:

keep_dtypebool, default True: This parameter is deprecated and will be removed in HyperSpy 3.0. Currently, it does not have any effect. This method always keeps the original dtype of the signal.
random_stateNone, int or numpy.random.Generator, default None: Seed for the random generator.

Notes

This method uses numpy.random.poisson() (or dask.array.random.poisson() for lazy signals) to generate the Poissonian noise.

apply_apodization(window='hann', hann_order=None, tukey_alpha=0.5, inplace=False)#

Apply an apodization window to a Signal.

Parameters:

windowstr, optional

Select between {'hann' (default), 'hamming', or 'tukey'}

hann_orderNone or int, optional

Only used if window='hann' If integer n is provided, a Hann window of n-th order will be used. If None, a first order Hann window is used. Higher orders result in more homogeneous intensity distribution.

tukey_alphafloat, optional

Only used if window='tukey' (default is 0.5). From the documentation of scipy.signal.windows.tukey():

Shape parameter of the Tukey window, representing the fraction of the window inside the cosine tapered region. If zero, the Tukey window is equivalent to a rectangular window. If one, the Tukey window is equivalent to a Hann window.

inplacebool, optional

If True, the apodization is applied in place, i.e. the signal data will be substituted by the apodized one (default is False).

Returns:

outBaseSignal (or subclass), optional: If inplace=False, returns the apodized signal of the same type as the provided Signal.

Examples

>>> import hyperspy.api as hs
>>> wave = hs.data.wave_image()
>>> wave.apply_apodization('tukey', tukey_alpha=0.1).plot()

as_lazy(chunks=None, copy_variance=True, copy_navigator=True, copy_learning_results=True)#

Create a copy of the given Signal as a LazySignal.

Parameters:

chunksstr or tuple: Define chunking of the dask array. If "auto", automatic chunking will be used and the signal dimension will not be split. If dask_auto", dask’s automatic chunking will be used. If tuple, it defines the chunks, see dask documentation for more information on defining chunks. If str and the array is already a dask array, don’t change the chunking.
copy_variancebool: Whether or not to copy the variance from the original Signal to the new lazy version. Default is True.
copy_navigatorbool: Whether or not to copy the navigator from the original Signal to the new lazy version. Default is True.
copy_learning_resultsbool: Whether to copy the learning_results from the original signal to the new lazy version. Default is True.

Returns:

resLazySignal: The same signal, converted to be lazy

as_signal1D(spectral_axis, out=None, optimize=True)#

Return the Signal as a spectrum.

The chosen spectral axis is moved to the last index in the array and the data is made contiguous for efficient iteration over spectra. By default, the method ensures the data is stored optimally, hence often making a copy of the data. See transpose() for a more general method with more options.

Parameters:

spectral_axisint, str, or DataAxis: The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.
outBaseSignal (or subclass) or None: If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.
optimizebool: If True, the location of the data in memory is optimised for the fastest iteration over the navigation axes. This operation can cause a peak of memory usage and requires considerable processing times for large datasets and/or low specification hardware. See the Transposing (changing signal spaces) section of the HyperSpy user guide for more information. When operating on lazy signals, if True, the chunks are optimised for the new axes configuration.

See also

hyperspy.api.signals.BaseSignal.as_signal2D
hyperspy.api.signals.BaseSignal.transpose
hyperspy.api.transpose

Examples

>>> img = hs.signals.Signal2D(np.ones((3, 4, 5, 6)))
>>> img
<Signal2D, title: , dimensions: (4, 3|6, 5)>
>>> img.as_signal1D(-1+1j)
<Signal1D, title: , dimensions: (6, 5, 4|3)>
>>> img.as_signal1D(0)
<Signal1D, title: , dimensions: (6, 5, 3|4)>

as_signal2D(image_axes, out=None, optimize=True)#

Convert a signal to a Signal2D.

The chosen image axes are moved to the last indices in the array and the data is made contiguous for efficient iteration over images.

Parameters:

image_axestuple (of int, str or DataAxis): Select the image axes. Note that the order of the axes matters and it is given in the “natural” i.e. X, Y, Z… order.
outBaseSignal (or subclass) or None: If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.
optimizebool: If True, the location of the data in memory is optimised for the fastest iteration over the navigation axes. This operation can cause a peak of memory usage and requires considerable processing times for large datasets and/or low specification hardware. See the Transposing (changing signal spaces) section of the HyperSpy user guide for more information. When operating on lazy signals, if True, the chunks are optimised for the new axes configuration.

Raises:

DataDimensionError: When data.ndim < 2

See also

hyperspy.api.signals.BaseSignal.as_signal1D
hyperspy.api.signals.BaseSignal.transpose
hyperspy.api.transpose

Examples

>>> s = hs.signals.Signal1D(np.ones((2, 3, 4, 5)))
>>> s
<Signal1D, title: , dimensions: (4, 3, 2|5)>
>>> s.as_signal2D((0, 1))
<Signal2D, title: , dimensions: (5, 2|4, 3)>

>>> s.to_signal2D((1, 2))
<Signal2D, title: , dimensions: (2, 5|4, 3)>

blind_source_separation(number_of_components=None, algorithm='sklearn_fastica', diff_order=1, diff_axes=None, factors=None, comp_list=None, mask=None, on_loadings=False, reverse_component_criterion='factors', whiten_method='PCA', return_info=False, print_info=True, **kwargs)#

Apply blind source separation (BSS) to the result of a decomposition.

The results are stored in self.learning_results.

Read more in the User Guide.

Parameters:

number_of_componentsint or None

Number of principal components to pass to the BSS algorithm. If None, you must specify the comp_list argument.

algorithm{"sklearn_fastica" | "orthomax" | "FastICA" | "JADE" |

``”CuBICA”`` | ``”TDSEP”``} or object, default “sklearn_fastica”

The BSS algorithm to use. If algorithm is an object, it must implement a fit_transform() method or fit() and transform() methods, in the same manner as a scikit-learn estimator.

diff_orderint, default 1

Sometimes it is convenient to perform the BSS on the derivative of the signal. If diff_order is 0, the signal is not differentiated.

diff_axesNone, list of int, list of str

If None and on_loadings is False, when diff_order is greater than 1 and signal_dimension is greater than 1, the differences are calculated across all signal axes
If None and on_loadings is True, when diff_order is greater than 1 and navigation_dimension is greater than 1, the differences are calculated across all navigation axes
Otherwise the axes can be specified in a list.

factorsBaseSignal or numpy.ndarray

Factors to decompose. If None, the BSS is performed on the factors of a previous decomposition. If a Signal instance, the navigation dimension must be 1 and the size greater than 1.

comp_listNone or list or numpy.ndarray

Choose the components to apply BSS to. Unlike number_of_components, this argument permits non-contiguous components.

maskBaseSignal or subclass

If not None, the signal locations marked as True are masked. The mask shape must be equal to the signal shape (navigation shape) when on_loadings is False (True).

on_loadingsbool, default False

If True, perform the BSS on the loadings of a previous decomposition, otherwise, perform the BSS on the factors.

reverse_component_criterion{“factors”, “loadings”}, default “factors”

Use either the factors or the loadings to determine if the component needs to be reversed.

whiten_method{"PCA" | "ZCA"} or None, default “PCA”

How to whiten the data prior to blind source separation. If None, no whitening is applied. See whiten_data() for more details.

return_info: bool, default False

The result of the decomposition is stored internally. However, some algorithms generate some extra information that is not stored. If True, return any extra information if available. In the case of sklearn.decomposition objects, this includes the sklearn Estimator object.

print_infobool, default True

If True, print information about the decomposition being performed. In the case of sklearn.decomposition objects, this includes the values of all arguments of the chosen sklearn algorithm.

**kwargsdict

Any keyword arguments are passed to the BSS algorithm.

Returns:

None or subclass of sklearn.base.BaseEstimator

If True and ‘algorithm’ is an sklearn Estimator, returns the: Estimator object.

See also

plot_bss_factors, plot_bss_loadings, plot_bss_results

change_dtype(dtype, rechunk=False)#

Change the data type of a Signal.

Parameters:

dtypestr or numpy.dtype

Typecode string or data-type to which the Signal’s data array is cast. In addition to all the standard numpy Data type objects (dtype), HyperSpy supports four extra dtypes for RGB images: 'rgb8', 'rgba8', 'rgb16', and 'rgba16'. Changing from and to any rgb(a) dtype is more constrained than most other dtype conversions. To change to an rgb(a) dtype, the signal_dimension must be 1, and its size should be 3 (for rgb) or 4 (for rgba) dtypes. The original dtype should be uint8 or uint16 if converting to rgb(a)8 or rgb(a))16, and the navigation_dimension should be at least 2. After conversion, the signal_dimension becomes 2. The dtype of images with original dtype rgb(a)8 or rgb(a)16 can only be changed to uint8 or uint16, and the signal_dimension becomes 1.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "dask_auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Examples

>>> s = hs.signals.Signal1D([1, 2, 3, 4, 5])
>>> s.data
array([1, 2, 3, 4, 5])
>>> s.change_dtype('float')
>>> s.data
array([1., 2., 3., 4., 5.])

cluster_analysis(cluster_source, source_for_centers=None, preprocessing=None, preprocessing_kwargs=None, number_of_components=None, navigation_mask=None, signal_mask=None, algorithm=None, return_info=False, **kwargs)#

Cluster analysis of a signal or decomposition results of a signal Results are stored in learning_results.

Parameters:

cluster_sourcestr {"bss" | "decomposition" | "signal"} or BaseSignal: If “bss” the blind source separation results are used If “decomposition” the decomposition results are used if “signal” the signal data is used Note that using the signal or BaseSignal can be memory intensive and is only recommended if the Signal dimension is small BaseSignal must have the same navigation dimensions as the signal.
source_for_centersNone, str {"decomposition" | "bss" | "signal"} or BaseSignal: default : None If None the cluster_source is used If “bss” the blind source separation results are used If “decomposition” the decomposition results are used if “signal” the signal data is used BaseSignal must have the same navigation dimensions as the signal.
preprocessingstr {"standard" | "norm" | "minmax"}, None or object: default: ‘norm’ Preprocessing the data before cluster analysis requires preprocessing the data to be clustered to similar scales. Standard preprocessing adjusts each feature to have uniform variation. Norm preprocessing adjusts treats the set of features like a vector and each measurement is scaled to length 1. You can also pass one of the scikit-learn preprocessing scale_method = import sklearn.processing.StandadScaler() preprocessing = scale_method See preprocessing methods in scikit-learn preprocessing for further details. If object, must be sklearn.preprocessing-like.
preprocessing_kwargsdict or None, default None: Additional parameters passed to the supported sklearn preprocessing methods. See sklearn.preprocessing scaling methods for further details
number_of_componentsint, default None: If you are getting the cluster centers using the decomposition results (cluster_source_for_centers=”decomposition”) you can define how many components to use. If set to None the method uses the estimate of significant components found in the decomposition step using the elbow method and stored in the learning_results.number_significant_components attribute. This applies to both bss and decomposition results.
navigation_masknumpy.ndarray of bool: The navigation locations marked as True are not used.
signal_masknumpy.ndarray of bool: The signal locations marked as True are not used in the clustering for “signal” or Signals supplied as cluster source. This is not applied to decomposition results or source_for_centers (as it may be a different shape to the cluster source)
algorithm{"kmeans" | "agglomerative" | "minibatchkmeans" | "spectralclustering"}: See scikit-learn documentation. Default “kmeans”
return_infobool, default False: The result of the cluster analysis is stored internally. However, the cluster class used contain a number of attributes. If True (the default is False) return the cluster object so the attributes can be accessed.
**kwargsdict: Additional parameters passed to the clustering class for initialization. For example, in case of the “kmeans” algorithm, n_init can be used to define the number of times the algorithm is restarted to optimize results.

Returns:

None or object: If 'return_info' is True returns the Scikit-learn cluster object used for clustering. Useful if you wish to examine inertia or other outputs.

Other Parameters:

int: Number of clusters to find using the one of the pre-defined methods “kmeans”, “agglomerative”, “minibatchkmeans”, “spectralclustering” See sklearn.cluster for details

See also

estimate_number_of_clusters, get_cluster_labels, get_cluster_signals
get_cluster_distances, plot_cluster_metric, plot_cluster_results
plot_cluster_signals, plot_cluster_labels

copy()#

Return a “shallow copy” of this Signal using the standard library’s copy() function. Note: this will return a copy of the signal, but it will not duplicate the underlying data in memory, and both Signals will reference the same data.

See also

deepcopy()

crop(axis, start=None, end=None, convert_units=False)#

Crops the data in a given axis. The range is given in pixels.

Parameters:

axisint or str: Specify the data axis in which to perform the cropping operation. The axis can be specified using the index of the axis in axes_manager or the axis name.
startint, float, or None: The beginning of the cropping interval. If type is int, the value is taken as the axis index. If type is float the index is calculated using the axis calibration. If start/end is None the method crops from/to the low/high end of the axis.
endint, float, or None: The end of the cropping interval. If type is int, the value is taken as the axis index. If type is float the index is calculated using the axis calibration. If start/end is None the method crops from/to the low/high end of the axis.
convert_unitsbool: Default is False. If True, convert the units using the convert_units() method of the AxesManager. If False, does nothing.

property data#: The underlying data structure as a numpy.ndarray (or dask.array.Array, if the Signal is lazy).

decomposition(normalize_poissonian_noise=False, algorithm='SVD', output_dimension=None, centre=None, auto_transpose=True, navigation_mask=None, signal_mask=None, var_array=None, var_func=None, reproject=None, return_info=False, print_info=True, svd_solver='auto', copy=False, **kwargs)#

Apply a decomposition to a dataset with a choice of algorithms.

The results are stored in self.learning_results.

Read more in the User Guide.

Parameters:

normalize_poissonian_noisebool, default False

If True, scale the signal to normalize Poissonian noise using the approach described in [Keenan2004].

algorithmstr {"SVD", "MLPCA", "sklearn_pca", "NMF", "sparse_pca",

``”mini_batch_sparse_pca”``, ``”RPCA”``, ``”ORPCA”``, ``”ORNMF”``} or object, default ``”SVD”``

The decomposition algorithm to use. If algorithm is an object, it must implement a fit_transform() method or fit() and transform() methods, in the same manner as a scikit-learn estimator. For cupy arrays, only “SVD” is supported.

output_dimensionNone or int

Number of components to keep/calculate. Default is None, i.e. min(data.shape).

centreNone or str {"navigation", "signal"}, default None

If None, the data is not centered prior to decomposition. If "navigation", the data is centered along the navigation axis. If "signal", centered along the signal axis. Only used by the "SVD" algorithm.

auto_transposebool, default True

If True, automatically transposes the data to boost performance. Only used by the “SVD” algorithm.

navigation_masknumpy.ndarray or BaseSignal

The navigation locations marked as True are not used in the decomposition.

signal_masknumpy.ndarray or BaseSignal

The signal locations marked as True are not used in the decomposition.

var_arraynumpy.ndarray

Array of variance for the maximum likelihood PCA algorithm. Only used by the “MLPCA” algorithm.

var_funcNone, callable() or numpy.ndarray, default None

If None, ignored If callable, applies the function to the data to obtain var_array. Only used by the “MLPCA” algorithm. If numpy array, creates var_array by applying a polynomial function defined by the array of coefficients to the data. Only used by the “MLPCA” algorithm.

reprojectNone or str {“signal”, “navigation”, “both”}, default None

If not None, the results of the decomposition will be projected in the selected masked area.

return_info: bool, default False

The result of the decomposition is stored internally. However, some algorithms generate some extra information that is not stored. If True, return any extra information if available. In the case of sklearn.decomposition objects, this includes the sklearn Estimator object.

print_infobool, default True

If True, print information about the decomposition being performed. In the case of sklearn.decomposition objects, this includes the values of all arguments of the chosen sklearn algorithm.

svd_solver{“auto”, “full”, “arpack”, “randomized”}, default “auto”

If "auto": the solver is selected by a default policy based on data.shape and output_dimension: if the input data is larger than 500x500 and the number of components to extract is lower than 80% of the smallest dimension of the data, then the more efficient "randomized" method is enabled. Otherwise the exact full SVD is computed and optionally truncated afterwards.
If "full": run exact SVD, calling the standard LAPACK solver via scipy.linalg.svd(), and select the components by postprocessing
If "arpack": use truncated SVD, calling ARPACK solver via scipy.sparse.linalg.svds(). It strictly requires 0 < output_dimension < min(data.shape)
If "randomized": use truncated SVD, call sklearn.utils.extmath.randomized_svd() to estimate a limited number of components

For cupy arrays, only “full” is supported.

copybool, default False

(Deprecated — will be removed in a future release. Pre-treatment data modifications such as Poisson noise normalization and centering are now reversed mathematically after decomposition, so explicit copying is no longer needed.)

If True, stores a copy of the data before any pre-treatments in s._data_before_treatments. Passing True emits a VisibleDeprecationWarning.

**kwargsdict

Any keyword arguments are passed to the decomposition algorithm.

Returns:

tuple of numpy.ndarray or sklearn.base.BaseEstimator or None

If True and ‘algorithm’ in [‘RPCA’, ‘ORPCA’, ‘ORNMF’], returns the low-rank (X) and sparse (E) matrices from robust PCA/NMF.
If True and ‘algorithm’ is an sklearn Estimator, returns the Estimator object.
Otherwise, returns None

See also

plot_decomposition_factors, plot_decomposition_loadings
plot_decomposition_results, plot_scree_plot

References

[Keenan2004]

M. Keenan and P. Kotula, “Accounting for Poisson noise in the multivariate analysis of ToF-SIMS spectrum images”, Surf. Interface Anal 36(3) (2004): 203-212.

deepcopy()#

Return a “deep copy” of this Signal using the standard library’s deepcopy() function. Note: this means the underlying data structure will be duplicated in memory.

See also

copy()

derivative(axis, order=1, out=None, **kwargs)#

Calculate the numerical derivative along the given axis, with respect to the calibrated units of that axis.

For a function \(y = f(x)\) and two consecutive values \(x_1\) and \(x_2\):

\[\frac{df(x)}{dx} = \frac{y(x_2)-y(x_1)}{x_2-x_1}\]

Parameters:

axisint, str, or DataAxis: The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.
order: int: The order of the derivative.
outBaseSignal (or subclass) or None: If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.
**kwargsdict: All extra keyword arguments are passed to numpy.gradient()

Returns:

BaseSignal: Note that the size of the data on the given axis decreases by the given order. i.e. if axis is "x" and order is 2, if the x dimension is N, then der’s x dimension is N - 2.

See also

integrate1D, integrate_simpson

Notes

This function uses numpy.gradient to perform the derivative. See its documentation for implementation details.

diff(axis, order=1, out=None, rechunk=False)#

Returns a signal with the n-th order discrete difference along given axis. i.e. it calculates the difference between consecutive values in the given axis: out[n] = a[n+1] - a[n]. See numpy.diff() for more details.

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

orderint

The order of the discrete difference.

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

BaseSignal or None: Note that the size of the data on the given axis decreases by the given order. i.e. if axis is "x" and order is 2, the x dimension is N, der’s x dimension is N - 2.

See also

hyperspy.api.signals.BaseSignal.derivative
hyperspy.api.signals.BaseSignal.integrate1D
hyperspy.api.signals.BaseSignal.integrate_simpson

Notes

If you intend to calculate the numerical derivative, please use the proper derivative() function instead. To avoid erroneous misuse of the diff function as derivative, it raises an error when when working with a non-uniform axis.

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.diff(0)
<BaseSignal, title: , dimensions: (|1023, 64, 64)>

estimate_elbow_position(explained_variance_ratio=None, log=True, max_points=20)#

Estimate the elbow position of a scree plot curve.

Used to estimate the number of significant components in a PCA variance ratio plot or other “elbow” type curves.

Find a line between first and last point on the scree plot. With a classic elbow scree plot, this line more or less defines a triangle. The elbow should be the point which is the furthest distance from this line. For more details, see [1].

Parameters:

explained_variance_ratio{None, numpy array}: Explained variance ratio values that form the scree plot. If None, uses the explained_variance_ratio array stored in s.learning_results, so a decomposition must have been performed first.
max_pointsint: Maximum number of points to consider in the calculation.

Returns:

int: The index of the elbow position in the input array. Due to zero-based indexing, the number of significant components is elbow_position + 1.

See also

get_scree_plot_data, plot_scree_plot

References

[1]

V. Satopää, J. Albrecht, D. Irwin, and B. Raghavan. “Finding a “Kneedle” in a Haystack: Detecting Knee Points in System Behavior,. 31st International Conference on Distributed Computing Systems Workshops, pp. 166-171, June 2011.

estimate_number_of_clusters(cluster_source, max_clusters=10, preprocessing=None, preprocessing_kwargs=None, number_of_components=None, navigation_mask=None, signal_mask=None, algorithm=None, metric='gap', n_ref=4, show_progressbar=None, **kwargs)#

Performs cluster analysis of a signal for cluster sizes ranging from n_clusters =2 to max_clusters ( default 12) Note that this can be a slow process for large datasets so please consider reducing max_clusters in this case. For each cluster it evaluates the silhouette score which is a metric of how well separated the clusters are. Maximima or peaks in the scores indicate good choices for cluster sizes.

Parameters:

cluster_sourcestr {“bss”, “decomposition”, “signal”} or BaseSignal: If “bss” the blind source separation results are used If “decomposition” the decomposition results are used if “signal” the signal data is used Note that using the signal can be memory intensive and is only recommended if the Signal dimension is small. Input Signal must have the same navigation dimensions as the signal instance.
max_clustersint, default 10: Max number of clusters to use. The method will scan from 2 to max_clusters.
preprocessingstr {“standard”, “norm”, “minmax”} or object: default: ‘norm’ Preprocessing the data before cluster analysis requires preprocessing the data to be clustered to similar scales. Standard preprocessing adjusts each feature to have uniform variation. Norm preprocessing adjusts treats the set of features like a vector and each measurement is scaled to length 1. You can also pass an instance of a sklearn preprocessing module. See preprocessing methods in scikit-learn preprocessing for further details. If object, must be sklearn.preprocessing-like.
preprocessing_kwargsdict or None, default None: Additional parameters passed to the cluster preprocessing algorithm. See sklearn.preprocessing preprocessing methods for further details
number_of_componentsint, default None: If you are getting the cluster centers using the decomposition results (cluster_source_for_centers=”decomposition”) you can define how many PCA components to use. If set to None the method uses the estimate of significant components found in the decomposition step using the elbow method and stored in the learning_results.number_significant_components attribute.
navigation_maskbool numpy array, defaultNone: The navigation locations marked as True are not used in the clustering.
signal_masknumpy.ndarray of bool, default None: The signal locations marked as True are not used in the clustering. Applies to “signal” or Signal cluster sources only.
metric{'elbow' | 'silhouette' | 'gap'}, default 'gap': Use distance,silhouette analysis or gap statistics to estimate the optimal number of clusters. Gap is believed to be, overall, the best metric but it’s also the slowest. Elbow measures the distances between points in each cluster as an estimate of how well grouped they are and is the fastest metric. For elbow the optimal k is the knee or elbow point. For gap the optimal k is the first k gap(k)>= gap(k+1)-std_error For silhouette the optimal k will be one of the “maxima” found with this method
n_refint, default 4: Number of references to use in gap statistics method Gap statistics compares the results from clustering the data to clustering uniformly distributed data. As clustering has a random variation it is typically averaged n_ref times to get an statistical average.
show_progressbarNone or bool: If True, display a progress bar. If None, the default from the preferences settings is used.
**kwargsdict: Parameters passed to the clustering algorithm.

Returns:

int: Estimate of the best cluster size.

Other Parameters:

n_clustersint: Number of clusters to find using the one of the pre-defined methods “kmeans”,”agglomerative”,”minibatchkmeans”,”spectralclustering” See sklearn.cluster for details

See also

cluster_analysis, get_cluster_labels, get_cluster_signals
get_cluster_distances, plot_cluster_metric, plot_cluster_results
plot_cluster_signals, plot_cluster_labels

estimate_poissonian_noise_variance(expected_value=None, gain_factor=None, gain_offset=None, correlation_factor=None)#

Estimate the Poissonian noise variance of the signal.

The variance is stored in the metadata.Signal.Noise_properties.variance attribute.

The Poissonian noise variance is equal to the expected value. With the default arguments, this method simply sets the variance attribute to the given expected_value. However, more generally (although then the noise is not strictly Poissonian), the variance may be proportional to the expected value. Moreover, when the noise is a mixture of white (Gaussian) and Poissonian noise, the variance is described by the following linear model:

\[\mathrm{Var}[X] = (a * \mathrm{E}[X] + b) * c\]

Where a is the gain_factor, b is the gain_offset (the Gaussian noise variance) and c the correlation_factor. The correlation factor accounts for correlation of adjacent signal elements that can be modeled as a convolution with a Gaussian point spread function.

Parameters:

expected_valueNone or BaseSignal (or subclass): If None, the signal data is taken as the expected value. Note that this may be inaccurate where the value of data is small.
gain_factorNone or float: a in the above equation. Must be positive. If None, take the value from metadata.Signal.Noise_properties.Variance_linear_model if defined. Otherwise, suppose pure Poissonian noise (i.e. gain_factor=1). If not None, the value is stored in metadata.Signal.Noise_properties.Variance_linear_model.
gain_offsetNone or float: b in the above equation. Must be positive. If None, take the value from metadata.Signal.Noise_properties.Variance_linear_model if defined. Otherwise, suppose pure Poissonian noise (i.e. gain_offset=0). If not None, the value is stored in metadata.Signal.Noise_properties.Variance_linear_model.
correlation_factorNone or float: c in the above equation. Must be positive. If None, take the value from metadata.Signal.Noise_properties.Variance_linear_model if defined. Otherwise, suppose pure Poissonian noise (i.e. correlation_factor=1). If not None, the value is stored in metadata.Signal.Noise_properties.Variance_linear_model.

export_bss_results(comp_ids=None, folder=None, calibrate=True, multiple_files=True, save_figures=False, factor_prefix='bss_factor', factor_format='hspy', loading_prefix='bss_loading', loading_format='hspy', comp_label=None, cmap='gray', same_window=False, no_nans=True, per_row=3, save_figures_format='png')#

Export results from ICA to any of the supported formats.

Parameters:

comp_idsNone, int or list of int

If None, returns all components/loadings. If an int, returns components/loadings with ids from 0 to the given value. If a list of ints, returns components/loadings with ids provided in the given list.

folderstr or None

The path to the folder where the file will be saved. If None the current folder is used by default.

factor_prefixstr

The prefix that any exported filenames for factors/components begin with

factor_formatstr

The extension of the format that you wish to save the factors to. Default is 'hspy'. See loading_format for more details.

loading_prefixstr

The prefix that any exported filenames for factors/components begin with

loading_formatstr

The extension of the format that you wish to save to. default is 'hspy'. The format determines the kind of output:

For image formats ('tif', 'png', 'jpg', etc.), plots are created using the plotting flags as below, and saved at 600 dpi. One plot is saved per loading.
For multidimensional formats ('rpl', 'hspy'), arrays are saved in single files. All loadings are contained in the one file.
For spectral formats ('msa'), each loading is saved to a separate file.

multiple_filesbool

If True, one file will be created for each factor and loading. Otherwise, only two files will be created, one for the factors and another for the loadings. The default value can be chosen in the preferences.

save_figuresbool

If True, the same figures that are obtained when using the plot methods will be saved with 600 dpi resolution

Other Parameters:

calibratebool: If True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: If True, plots each factor to the same window.
comp_labelstr: the label that is either the plot title (if plotting in separate windows) or the label in the legend (if plotting in the same window)
cmapColormap: The colormap used for images, such as factors, loadings, or for peak characteristics. Default is the matplotlib gray colormap ("gray").
per_rowint: The number of plots in each row, when the same_window parameter is True.
save_figures_formatstr: The image format extension.

See also

get_bss_factors, get_bss_loadings

Notes

The following parameters are only used when save_figures = True

export_cluster_results(cluster_ids=None, folder=None, calibrate=True, center_prefix='cluster_center', center_format='hspy', membership_prefix='cluster_label', membership_format='hspy', comp_label=None, cmap='gray', same_window=False, multiple_files=True, no_nans=True, per_row=3, save_figures=False, save_figures_format='png')#

Export results from a cluster analysis to any of the supported formats.

Parameters:

cluster_idsNone, int or list of int

if None, returns all clusters/centers. if int, returns clusters/centers with ids from 0 to given int. if list of ints, returnsclusters/centers with ids in given list.

folderstr or None

The path to the folder where the file will be saved. If None the current folder is used by default.

center_prefixstr

The prefix that any exported filenames for cluster centers begin with

center_formatstr

The extension of the format that you wish to save to. Default is “hspy”. See loading format for more details.

label_prefixstr

The prefix that any exported filenames for cluster labels begin with

label_formatstr

The extension of the format that you wish to save to. default is “hspy”. The format determines the kind of output.

For image formats ('tif', 'png', 'jpg', etc.),
plots are created using the plotting flags as below, and saved at 600 dpi. One plot is saved per loading.
For multidimensional formats ('rpl', 'hspy'), arrays
are saved in single files. All loadings are contained in the one file.
For spectral formats ('msa'), each loading is saved to a
separate file.

multiple_filesbool, default False

If True, on exporting a file per center will be created. Otherwise only two files will be created, one for the centers and another for the membership. The default value can be chosen in the preferences.

save_figuresbool, default False

If True the same figures that are obtained when using the plot methods will be saved with 600 dpi resolution

Other Parameters:

These parameters are plotting options and only used when
``save_figures=True``.
calibratebool: if True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: if True, plots each factor to the same window.
comp_labelstr: The label that is either the plot title (if plotting in separate windows) or the label in the legend (if plotting in the same window)
cmapmatplotlib.colors.Colormap: The colormap used for the factor image, or for peak characteristics, the colormap used for the scatter plot of some peak characteristic.
per_rowint: the number of plots in each row, when the same_window=True.
save_figures_formatstr: The image format extension.

See also

get_cluster_signals
get_cluster_labels

export_decomposition_results(comp_ids=None, folder=None, calibrate=True, factor_prefix='factor', factor_format='hspy', loading_prefix='loading', loading_format='hspy', comp_label=None, cmap='gray', same_window=False, multiple_files=True, no_nans=True, per_row=3, save_figures=False, save_figures_format='png')#

Export results from a decomposition to any of the supported formats.

Parameters:

comp_idsNone, int or list of int

If None, returns all components/loadings. If an int, returns components/loadings with ids from 0 to the given value. If a list of ints, returns components/loadings with ids provided in the given list.

folderstr or None

The path to the folder where the file will be saved. If None, the current folder is used by default.

factor_prefixstr

The prefix that any exported filenames for factors/components begin with

factor_formatstr

The extension of the format that you wish to save the factors to. Default is 'hspy'. See loading_format for more details.

loading_prefixstr

The prefix that any exported filenames for factors/components begin with

loading_formatstr

The extension of the format that you wish to save to. default is 'hspy'. The format determines the kind of output:

For image formats ('tif', 'png', 'jpg', etc.), plots are created using the plotting flags as below, and saved at 600 dpi. One plot is saved per loading.
For multidimensional formats ('rpl', 'hspy'), arrays are saved in single files. All loadings are contained in the one file.
For spectral formats ('msa'), each loading is saved to a separate file.

multiple_filesbool

If True, one file will be created for each factor and loading. Otherwise, only two files will be created, one for the factors and another for the loadings. The default value can be chosen in the preferences.

save_figuresbool

If True the same figures that are obtained when using the plot methods will be saved with 600 dpi resolution

Other Parameters:

calibratebool: If True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: If True, plots each factor to the same window.
comp_labelstr: the label that is either the plot title (if plotting in separate windows) or the label in the legend (if plotting in the same window)
cmapColormap: The colormap used for images, such as factors, loadings, or for peak characteristics. Default is the matplotlib gray colormap ("gray").
per_rowint: The number of plots in each row, when the same_window parameter is True.
save_figures_formatstr: The image format extension.

See also

get_decomposition_factors, get_decomposition_loadings

Notes

The following parameters are only used when save_figures = True

fft(shift=False, apodization=False, real_fft_only=False, **kwargs)#

Compute the discrete Fourier Transform.

This function computes the discrete Fourier Transform over the signal axes by means of the Fast Fourier Transform (FFT) as implemented in numpy.

Parameters:

shiftbool, optional: If True, the origin of FFT will be shifted to the centre (default is False).
apodizationbool or str: Apply an apodization window before calculating the FFT in order to suppress streaks. Valid string values are {'hann' or 'hamming' or 'tukey'} If True or 'hann', applies a Hann window. If 'hamming' or 'tukey', applies Hamming or Tukey windows, respectively (default is False).
real_fft_onlybool, default False: If True and data is real-valued, uses numpy.fft.rfftn() instead of numpy.fft.fftn()
**kwargsdict: other keyword arguments are described in numpy.fft.fftn()

Returns:

sComplexSignal: A Signal containing the result of the FFT algorithm

Raises:

NotImplementedError: If performing FFT along a non-uniform axis.

Notes

Requires a uniform axis. For further information see the documentation of numpy.fft.fftn()

Examples

>>> import scipy
>>> im = hs.signals.Signal2D(scipy.datasets.face())
>>> im.fft()
<ComplexSignal2D, title: FFT of , dimensions: (|512, 512)>

>>> # Use following to plot power spectrum of `im`:
>>> im.fft(shift=True, apodization=True).plot(power_spectrum=True)

fold()#: If the signal was previously unfolded, fold it back

get_bss_factors()#

Return the blind source separation factors.

Returns:

BaseSignal (or subclass)

See also

get_bss_loadings, export_bss_results

get_bss_loadings()#

Return the blind source separation loadings.

Returns:

BaseSignal (or subclass)

See also

get_bss_factors, export_bss_results

get_bss_model(components=None, chunks='auto', lazy_output=None)#

Generate model with the selected number of independent components.

Parameters:

componentsNone, int or list of int, default None: If None, rebuilds signal instance from all components If int, rebuilds signal instance from components in range 0-given int If list of ints, rebuilds signal instance from only components in given list
chunksstr, int, or tuple, default “auto”: Controls chunking of the reconstructed signal when lazy_output is active. If "auto" or "dask_auto", dask determines the chunk size. If an int, the signal dimension is split into chunks of that size and navigation uses "auto". If a tuple of length 2, the first element controls signal dimension chunking and the second controls navigation chunking (passed as nav_chunks to rechunk()).
lazy_outputNone or bool: If True, the output will be returned as a lazy signal. This means the calculation itself will be delayed until either compute() is used, or the signal is stored as a file. If False, the output will be returned as a non-lazy signal, this means the outputs will be calculated directly, and loaded into memory. If None the output will be lazy if the input signal is lazy, and non-lazy if the input signal is non-lazy.

Returns:

BaseSignal or subclass: A model built from the given components.

get_cluster_distances()#

Euclidian distances to the centroid of each cluster

Returns:

signal: Hyperspy signal of cluster distances

See also

get_cluster_signals

get_cluster_labels(merged=False)#

Return cluster labels as a Signal.

Parameters:

mergedbool, default False: If False the cluster label signal has a navigation axes of length number_of_clusters and the signal along the the navigation direction is binary - 0 the point is not in the cluster, 1 it is included. If True, the cluster labels are merged (no navigation axes). The value of the signal at any point will be between -1 and the number of clusters. -1 represents the points that were masked for cluster analysis if any.

Returns:

BaseSignal: The cluster labels

See also

get_cluster_signals

get_cluster_signals(signal='mean')#

Return the cluster centers as a Signal.

Parameters:

signal{“mean”, “sum”, “centroid”}, optional: If “mean” or “sum” return the mean signal or sum respectively over each cluster. If “centroid”, returns the signals closest to the centroid.

See also

get_cluster_labels

get_current_signal(auto_title=True, auto_filename=True, as_numpy=False)#

Returns the data at the current coordinates as a BaseSignal subclass.

The signal subclass is the same as that of the current object. All the axes navigation attributes are set to False.

Parameters:

auto_titlebool: If True, the current indices (in parentheses) are appended to the title, separated by a space, otherwise the title of the signal is used unchanged.
auto_filenamebool: If True and tmp_parameters.filename is defined (which is always the case when the Signal has been read from a file), the filename stored in the metadata is modified by appending an underscore and the current indices in parentheses.
as_numpybool or None: Only with cupy array. If True, return the current signal as numpy array, otherwise return as cupy array.

Returns:

csBaseSignal (or subclass): The data at the current coordinates as a Signal

Examples

>>> im = hs.signals.Signal2D(np.zeros((2, 3, 32, 32)))
>>> im
<Signal2D, title: , dimensions: (3, 2|32, 32)>
>>> im.axes_manager.indices = (2, 1)
>>> im.get_current_signal()
<Signal2D, title:  (2, 1), dimensions: (|32, 32)>

get_decomposition_factors()#

Return the decomposition factors.

Returns:

signalBaseSignal (or subclass)

See also

get_decomposition_loadings, export_decomposition_results

get_decomposition_loadings()#

Return the decomposition loadings.

Returns:

signalBaseSignal (or subclass)

See also

get_decomposition_factors, export_decomposition_results

get_decomposition_model(components=None, chunks='auto', lazy_output=None)#

Generate model with the selected number of principal components.

Parameters:

componentsNone, int or list of int, default None

If None, rebuilds signal instance from all components
If int, rebuilds signal instance from components in range 0-given int
If list of ints, rebuilds signal instance from only components in given list

chunksstr, int, or tuple, default “auto”

Controls chunking of the reconstructed signal when lazy_output is active. If "auto" or "dask_auto", dask determines the chunk size. If an int, the signal dimension is split into chunks of that size and navigation uses "auto". If a tuple of length 2, the first element controls signal dimension chunking and the second controls navigation chunking (passed as nav_chunks to rechunk()).

lazy_outputNone or bool

If True, the output will be returned as a lazy signal. This means the calculation itself will be delayed until either compute() is used, or the signal is stored as a file. If False, the output will be returned as a non-lazy signal, this means the outputs will be calculated directly, and loaded into memory. If None the output will be lazy if the input signal is lazy, and non-lazy if the input signal is non-lazy.

Returns:

BaseSignal or subclass: A model built from the given components.

get_dimensions_from_data()#: Get the dimension parameters from the Signal’s underlying data. Useful when the data structure was externally modified, or when the spectrum image was not loaded from a file

get_explained_variance_ratio(*args, **kwargs)#

[Deprecated] Deprecated: use get_scree_plot_data() instead.

Notes

Deprecated since version 2.5: Function get_explained_variance_ratio() is deprecated and will be removed in version 3.0. Use get_scree_plot_data() instead.

get_histogram(bins='fd', range_bins=None, max_num_bins=250, out=None, **kwargs)#

Return a histogram of the signal data.

More sophisticated algorithms for determining the bins can be used by passing a string as the bins argument. Other than the 'blocks' and 'knuth' methods, the available algorithms are the same as numpy.histogram().

Note: The lazy version of the algorithm only supports "scott" and "fd" as a string argument for bins.

Parameters:

binsint or sequence of float or str, default “fd”

If bins is an int, it defines the number of equal-width bins in the given range. If bins is a sequence, it defines the bin edges, including the rightmost edge, allowing for non-uniform bin widths.

If bins is a string from the list below, will use the method chosen to calculate the optimal bin width and consequently the number of bins (see Notes for more detail on the estimators) from the data that falls within the requested range. While the bin width will be optimal for the actual data in the range, the number of bins will be computed to fill the entire range, including the empty portions. For visualisation, using the 'auto' option is suggested. Weighted data is not supported for automated bin size selection.

Possible strings are:

'auto' : Maximum of the ‘sturges’ and ‘fd’ estimators. Provides good all around performance.
'fd' : Freedman Diaconis Estimator, robust (resilient to outliers) estimator that takes into account data variability and data size.
'doane' : An improved version of Sturges’ estimator that works better with non-normal datasets.
'scott' : Less robust estimator that that takes into account data variability and data size.
'stone' : Estimator based on leave-one-out cross-validation estimate of the integrated squared error. Can be regarded as a generalization of Scott’s rule.
'rice' : Estimator does not take variability into account, only data size. Commonly overestimates number of bins required.
'sturges' : R’s default method, only accounts for data size. Only optimal for gaussian data and underestimates number of bins for large non-gaussian datasets.
'sqrt' : Square root (of data size) estimator, used by Excel and other programs for its speed and simplicity.
'knuth' : Knuth’s rule is a fixed-width, Bayesian approach to determining the optimal bin width of a histogram.
'blocks' : Determination of optimal adaptive-width histogram bins using the Bayesian Blocks algorithm.

range_bins(float, float), optional

The lower and upper limit of the range of bins. If not provided, range is simply (a.min(), a.max()). Values outside the range are ignored. The first element of the range must be less than or equal to the second. range affects the automatic bin computation as well. While bin width is computed to be optimal based on the actual data within range, the bin count will fill the entire range including portions containing no data.

max_num_binsint, default 250

When estimating the bins using one of the str methods, the number of bins is capped by this number to avoid a MemoryError being raised by numpy.histogram().

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

**kwargs

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

Returns:

hist_specSignal1D: A 1D spectrum instance containing the histogram.

See also

hyperspy.api.signals.BaseSignal.print_summary_statistics
numpy.histogram, dask.array.histogram

Notes

See numpy.histogram() for more details on the meaning of the returned values.

Examples

>>> s = hs.signals.Signal1D(np.random.normal(size=(10, 100)))
>>> # Plot the data histogram
>>> s.get_histogram().plot()
>>> # Plot the histogram of the signal at the current coordinates
>>> s.get_current_signal().get_histogram().plot()

get_noise_variance()#

Get the noise variance of the signal, if set.

Equivalent to s.metadata.Signal.Noise_properties.variance.

Parameters:

None

Returns:

varianceNone or float or BaseSignal (or subclass): Noise variance of the signal, if set. Otherwise returns None.

get_scree_plot_data()#

Return the scree plot data as a Signal1D.

Returns the explained variance ratio (when the decomposition was performed with mean-centring, a.k.a. PCA) or the proportion of total variation (ratio of squared singular values, for uncentred SVD and other algorithms) as a function of component index.

Read more in the User Guide.

Returns:

sSignal1D: Explained variance ratio (centred decomposition) or proportion of total variation (uncentred decomposition).

See also

decomposition, plot_scree_plot
get_decomposition_loadings, get_decomposition_factors

ifft(shift=None, return_real=True, **kwargs)#

Compute the inverse discrete Fourier Transform.

This function computes the real part of the inverse of the discrete Fourier Transform over the signal axes by means of the Fast Fourier Transform (FFT) as implemented in numpy.

Parameters:

shiftbool or None, optional: If None, the shift option will be set to the original status of the FFT using the value in metadata. If no FFT entry is present in metadata, the parameter will be set to False. If True, the origin of the FFT will be shifted to the centre. If False, the origin will be kept at (0, 0) (default is None).
return_realbool, default True: If True, returns only the real part of the inverse FFT. If False, returns all parts.
**kwargsdict: other keyword arguments are described in numpy.fft.ifftn()

Returns:

sBaseSignal (or subclass): A Signal containing the result of the inverse FFT algorithm

Raises:

NotImplementedError: If performing IFFT along a non-uniform axis.

Notes

Requires a uniform axis. For further information see the documentation of numpy.fft.ifftn()

Examples

>>> import scipy
>>> im = hs.signals.Signal2D(scipy.datasets.face())
>>> imfft = im.fft()
>>> imfft.ifft()
<Signal2D, title: real(iFFT of FFT of ), dimensions: (|512, 512)>

indexmax(axis, out=None, rechunk=False)#

Returns a signal with the index of the maximum along an axis.

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the indices of the maximum along the specified axis. Note: the data dtype is always int.

See also

max, min, sum, mean, std, var, indexmin, valuemax, valuemin

Examples

>>> s = BaseSignal(np.random.random((64,64,1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.indexmax(0)
<Signal2D, title: , dimensions: (|64, 64)>

indexmin(axis, out=None, rechunk=False)#

Returns a signal with the index of the minimum along an axis.

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the indices of the minimum along the specified axis. Note: the data dtype is always int.

See also

max, min, sum, mean, std, var, indexmax, valuemax, valuemin

Examples

>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.indexmin(0)
<Signal2D, title: , dimensions: (|64, 64)>

integrate1D(axis, out=None, rechunk=False)#

Integrate the signal over the given axis.

The integration is performed using Simpson’s rule if axis.is_binned is False and simple summation over the given axis if True (along binned axes, the detector already provides integrated counts per bin).

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the integral of the provided Signal along the specified axis.

See also

integrate_simpson, derivative

Examples

>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.integrate1D(0)
<Signal2D, title: , dimensions: (|64, 64)>

integrate_simpson(axis, out=None, rechunk=False)#

Calculate the integral of a Signal along an axis using Simpson’s rule.

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the integral of the provided Signal along the specified axis.

See also

hyperspy.api.signals.BaseSignal.derivative
hyperspy.api.signals.BaseSignal.integrate1D

Examples

>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.integrate_simpson(0)
<Signal2D, title: , dimensions: (|64, 64)>

interpolate_on_axis(new_axis, axis=0, inplace=False, degree=1)#

Replaces the given axis with the provided new_axis and interpolates data accordingly using scipy.interpolate.make_interp_spline().

Parameters:

new_axishyperspy.axes.UniformDataAxis,
:class:`hyperspy.axes.DataAxis`, :class:`hyperspy.axes.FunctionalDataAxis`
or str: Axis which replaces the one specified by the axis argument. If this new axis exceeds the range of the old axis, a warning is raised that the data will be extrapolated. If "uniform", convert the axis specified by the axis parameter to a uniform axis with the same number of data points.
axisint or str, default 0: Specifies the axis which will be replaced using the index of the axis in the axes_manager. The axis can be specified using the index of the axis in axes_manager or the axis name.
inplacebool, default False: If True the data of self is replaced by the result and the axis is changed inplace. Otherwise self is not changed and a new signal with the changes incorporated is returned.
degree: int, default 1: Specifies the B-Spline degree of the used interpolator.

Returns:

BaseSignal (or subclass): A copy of the object with the axis exchanged and the data interpolated. This only occurs when inplace is set to False, otherwise nothing is returned.

Examples

>>> s = hs.data.luminescence_signal(uniform=False)
>>> s2 = s.interpolate_on_axis("uniform", -1, inplace=False)
>>> hs.plot.plot_spectra(
...     [s, s2],
...     legend=["FunctionalAxis", "Interpolated"],
...     drawstyle='steps-mid',
... )
<Axes: xlabel='Energy (eV)', ylabel='Intensity'>

Specifying a uniform axis:

>>> s = hs.data.luminescence_signal(uniform=False)
>>> new_axis = s.axes_manager[-1].copy()
>>> new_axis.convert_to_uniform_axis()
>>> s3 = s.interpolate_on_axis(new_axis, -1, inplace=False)
>>> hs.plot.plot_spectra(
...     [s, s3],
...     legend=["FunctionalAxis", "Interpolated"],
...     drawstyle='steps-mid',
... )
<Axes: xlabel='Energy (eV)', ylabel='Intensity'>

property is_rgb#: Whether or not this signal is an RGB dtype.

property is_rgba#: Whether or not this signal is an RGB + alpha channel dtype.

property is_rgbx#: Whether or not this signal is either an RGB or RGB + alpha channel dtype.

map(function, show_progressbar=None, num_workers=None, inplace=True, ragged=None, navigation_chunks='auto', output_signal_size=None, output_dtype=None, lazy_output=None, silence_warnings=False, **kwargs)#

Apply a function to the signal data at all the navigation coordinates.

The function must operate on numpy arrays. It is applied to the data at each navigation coordinate pixel-py-pixel. Any extra keyword arguments are passed to the function. The keywords can take different values at different coordinates. If the function takes an axis or axes argument, the function is assumed to be vectorized and the signal axes are assigned to axis or axes. Otherwise, the signal is iterated over the navigation axes and a progress bar is displayed to monitor the progress.

In general, only navigation axes (order, calibration, and number) are guaranteed to be preserved.

Parameters:

functionfunction: Any function that can be applied to the signal. This function should not alter any mutable input arguments or input data. So do not do operations which alter the input, without copying it first. For example, instead of doing image *= mask, rather do image = image * mask. Likewise, do not do image[5, 5] = 10 directly on the input data or arguments, but make a copy of it first. For example via image = copy.deepcopy(image).
show_progressbarNone or bool: If True, display a progress bar. If None, the default from the preferences settings is used.
num_workersNone or int: Number of worker used by dask. If None, default to dask default value.
inplacebool, default True: If True, the data is replaced by the result. Otherwise a new Signal with the results is returned.
raggedNone or bool, default None: Indicates if the results for each navigation pixel are of identical shape (and/or numpy arrays to begin with). If None, the output signal will be ragged only if the original signal is ragged.
navigation_chunksstr, or tuple of int, default "auto": Set the navigation_chunks argument to a tuple of integers to split the navigation axes into chunks, without chunking the signal dimension. If "auto" and when the data size is less than 100MB * number of cores, the chunking will be optimised to be distributed over the number of cores. This is useful to enable using multiple cores with signals which are less that 100 MB.
output_signal_sizeNone, tuple: Since the size and dtype of the signal dimension of the output signal can be different from the input signal, this output signal size must be calculated somehow. If both output_signal_size and output_dtype is None, this is automatically determined. However, if for some reason this is not working correctly, this can be specified via output_signal_size and output_dtype. The most common reason for this failing is due to the signal size being different for different navigation positions. If this is the case, use ragged=True. None is default.
output_dtypeNone, numpy.dtype: See docstring for output_signal_size for more information. Default None.
lazy_outputNone or bool: If True, the output will be returned as a lazy signal. This means the calculation itself will be delayed until either compute() is used, or the signal is stored as a file. If False, the output will be returned as a non-lazy signal, this means the outputs will be calculated directly, and loaded into memory. If None the output will be lazy if the input signal is lazy, and non-lazy if the input signal is non-lazy.
silence_warningsbool, str or tuple, list of str: If True, don’t warn when one of the signal axes are non-uniform, or the scales of the signal axes differ. If "non-uniform", "scales" or "units" are in the list the warning will be silenced when using non-uniform axis, different scales or different units of the signal axes, respectively. If False, all warnings will be added to the logger. Default is False.
**kwargsdict: All extra keyword arguments are passed to the provided function

Notes

If the function results do not have identical shapes, the result is an array of navigation shape, where each element corresponds to the result of the function (of arbitrary object type), called a “ragged array”. As such, most functions are not able to operate on the result and the data should be used directly.

This method is similar to Python’s map() that can also be utilized with a BaseSignal instance for similar purposes. However, this method has the advantage of being faster because it iterates the underlying numpy data array instead of the BaseSignal.

Currently requires a uniform axis.

Examples

Apply a Gaussian filter to all the images in the dataset. The sigma parameter is constant:

>>> import scipy.ndimage
>>> im = hs.signals.Signal2D(np.random.random((10, 64, 64)))
>>> im.map(scipy.ndimage.gaussian_filter, sigma=2.5)

Apply a Gaussian filter to all the images in the dataset. The signal parameter is variable:

>>> im = hs.signals.Signal2D(np.random.random((10, 64, 64)))
>>> sigmas = hs.signals.BaseSignal(np.linspace(2, 5, 10)).T
>>> im.map(scipy.ndimage.gaussian_filter, sigma=sigmas)

Rotate the two signal dimensions, with different amount as a function of navigation index. Delay the calculation by getting the output lazily. The calculation is then done using the compute method.

>>> from scipy.ndimage import rotate
>>> s = hs.signals.Signal2D(np.random.random((5, 4, 40, 40)))
>>> s_angle = hs.signals.BaseSignal(np.linspace(0, 90, 20).reshape(5, 4)).T
>>> s.map(rotate, angle=s_angle, reshape=False, lazy_output=True)
>>> s.compute()

Rotate the two signal dimensions, with different amount as a function of navigation index. In addition, the output is returned as a new signal, instead of replacing the old signal.

>>> s = hs.signals.Signal2D(np.random.random((5, 4, 40, 40)))
>>> s_angle = hs.signals.BaseSignal(np.linspace(0, 90, 20).reshape(5, 4)).T
>>> s_rot = s.map(rotate, angle=s_angle, reshape=False, inplace=False)

If you want some more control over computing a signal that isn’t lazy you can always set lazy_output to True and then compute the signal setting the scheduler to ‘threading’, ‘processes’, ‘single-threaded’ or ‘distributed’.

Additionally, you can set the navigation_chunks argument to a tuple of integers to split the navigation axes into chunks. This can be useful if your signal is less that 100 mb but you still want to use multiple cores.

>>> s = hs.signals.Signal2D(np.random.random((5, 4, 40, 40)))
>>> s_angle = hs.signals.BaseSignal(np.linspace(0, 90, 20).reshape(5, 4)).T
>>> s.map(
...    rotate, angle=s_angle, reshape=False, lazy_output=True,
...    inplace=True, navigation_chunks=(2,2)
... )
>>> s.compute()

max(axis=None, out=None, rechunk=False)#

Returns a signal with the maximum of the signal along at least one axis.

Parameters:

axisint, str, DataAxis or tuple

Either a single or multiple axes in a tuple can be passed. In both cases, the axes can be passed directly, or specified using the index in axes_manager or the name of the axis. Any duplicates are removed. If "sig" or "nav", the signal or navigation axes will be used, respectively. If None, the operation is performed over all navigation axes (default).

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the maximum of the provided Signal over the specified axes

See also

min, sum, mean, std, var, indexmax, indexmin, valuemax, valuemin

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.max(0)
<Signal2D, title: , dimensions: (|64, 64)>

mean(axis=None, out=None, rechunk=False)#

Returns a signal with the average of the signal along at least one axis.

Parameters:

axisint, str, DataAxis or tuple

Either a single or multiple axes in a tuple can be passed. In both cases, the axes can be passed directly, or specified using the index in axes_manager or the name of the axis. Any duplicates are removed. If "sig" or "nav", the signal or navigation axes will be used, respectively. If None, the operation is performed over all navigation axes (default).

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the mean of the provided Signal over the specified axes

See also

max, min, sum, std, var, indexmax, indexmin, valuemax, valuemin

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.mean(0)
<Signal2D, title: , dimensions: (|64, 64)>

property metadata#: The metadata of the signal.

min(axis=None, out=None, rechunk=False)#

Returns a signal with the minimum of the signal along at least one axis.

Parameters:

axisint, str, DataAxis or tuple

Either a single or multiple axes in a tuple can be passed. In both cases, the axes can be passed directly, or specified using the index in axes_manager or the name of the axis. Any duplicates are removed. If "sig" or "nav", the signal or navigation axes will be used, respectively. If None, the operation is performed over all navigation axes (default).

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the minimum of the provided Signal over the specified axes

See also

max, sum, mean, std, var, indexmax, indexmin, valuemax, valuemin

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.min(0)
<Signal2D, title: , dimensions: (|64, 64)>

nanmax(axis=None, out=None, rechunk=False)#: Identical to max(), except ignores missing (NaN) values. See that method’s documentation for details.

nanmean(axis=None, out=None, rechunk=False)#: Identical to mean(), except ignores missing (NaN) values. See that method’s documentation for details.

nanmin(axis=None, out=None, rechunk=False)#: Identical to min(), except ignores missing (NaN) values. See that method’s documentation for details.

nanstd(axis=None, out=None, rechunk=False)#: Identical to std(), except ignores missing (NaN) values. See that method’s documentation for details.

nansum(axis=None, out=None, rechunk=False)#: Identical to sum(), except ignores missing (NaN) values. See that method’s documentation for details.

nanvar(axis=None, out=None, rechunk=False)#: Identical to var(), except ignores missing (NaN) values. See that method’s documentation for details.

normalize_bss_components(target='factors', function=<function sum>)#

Normalize BSS components.

Parameters:

target{“factors”, “loadings”}: Normalize components based on the scale of either the factors or loadings.
functionnumpy callable(), default numpy.sum: Each target component is divided by the output of function(target). The function must return a scalar when operating on numpy arrays and must have an axis argument.

normalize_decomposition_components(target='factors', function=<function sum>)#

Normalize decomposition components.

Parameters:

target{“factors”, “loadings”}: Normalize components based on the scale of either the factors or loadings.
functionnumpy callable(), default numpy.sum: Each target component is divided by the output of function(target). The function must return a scalar when operating on numpy arrays and must have an axis argument.

normalize_poissonian_noise(navigation_mask=None, signal_mask=None)#

Normalize the signal under the assumption of Poisson noise.

Scales the signal to normalize the Poisson data for subsequent decomposition analysis (Keenan and Kotula, 2004).

Parameters:

navigation_mask{None, bool numpy array}, default None: Optional mask applied in the navigation axis.
signal_mask{None, bool numpy array}, default None: Optional mask applied in the signal axis.

property original_metadata#: The original metadata of the signal.

plot(navigator='auto', axes_manager=None, plot_markers=True, **kwargs)#

Plot the signal at the current coordinates.

For multidimensional datasets an optional figure, the “navigator”, with a cursor to navigate that data is raised. In any case it is possible to navigate the data using the sliders. Currently only signals with signal_dimension equal to 0, 1 and 2 can be plotted.

Parameters:

navigatorstr, None, or BaseSignal (or subclass).

Allowed string values are ``’auto’``, ``’slider’``, and ``’spectrum’``.

If 'auto':
- If navigation_dimension > 0, a navigator is provided to explore the data.
- If navigation_dimension is 1 and the signal is an image the navigator is a sum spectrum obtained by integrating over the signal axes (the image).
- If navigation_dimension is 1 and the signal is a spectrum the navigator is an image obtained by stacking all the spectra in the dataset horizontally.
- If navigation_dimension is > 1, the navigator is a sum image obtained by integrating the data over the signal axes.
- Additionally, if navigation_dimension > 2, a window with one slider per axis is raised to navigate the data.
- For example, if the dataset consists of 3 navigation axes “X”, “Y”, “Z” and one signal axis, “E”, the default navigator will be an image obtained by integrating the data over “E” at the current “Z” index and a window with sliders for the “X”, “Y”, and “Z” axes will be raised. Notice that changing the “Z”-axis index changes the navigator in this case.
- For lazy signals, the navigator will be calculated using the compute_navigator() method.
If 'slider':
- If navigation dimension > 0 a window with one slider per axis is raised to navigate the data.
If 'spectrum':
- If navigation_dimension > 0 the navigator is always a spectrum obtained by integrating the data over all other axes.
- Not supported for lazy signals, the 'auto' option will be used instead.
If None, no navigator will be provided.

Alternatively a BaseSignal (or subclass) instance can be provided. The navigation or signal shape must match the navigation shape of the signal to plot or the navigation_shape + signal_shape must be equal to the navigator_shape of the current object (for a dynamic navigator). If the signal dtype is RGB or RGBA this parameter has no effect and the value is always set to 'slider'.

axes_managerNone or AxesManager

If None, the signal’s axes_manager attribute is used.

plot_markersbool, default True

Plot markers added using s.add_marker(marker, permanent=True). Note, a large number of markers might lead to very slow plotting.

navigator_kwdsdict

Only for image navigator, additional keyword arguments for matplotlib.pyplot.imshow().

normstr, default 'auto'

The function used to normalize the data prior to plotting. Allowable strings are: 'auto', 'linear', 'log'. If 'auto', intensity is plotted on a linear scale except when power_spectrum=True (only for complex signals).

autoscalestr

The string must contain any combination of the 'x' and 'v' characters. If 'x' or 'v' (for values) are in the string, the corresponding horizontal or vertical axis limits are set to their maxima and the axis limits will reset when the data or the navigation indices are changed. Default is 'v'.

**kwargsdict

Only when plotting an image: additional (optional) keyword arguments for matplotlib.pyplot.imshow().

plot_bss_factors(comp_ids=None, calibrate=True, same_window=True, title=None, cmap='gray', per_row=3, **kwargs)#

Plot factors from blind source separation results. In case of 1D signal axis, each factors line can be toggled on and off by clicking on their corresponding line in the legend.

Parameters:

comp_idsNone, int, or list of int: If comp_ids is None, maps of all components will be returned. If it is an int, maps of components with ids from 0 to the given value will be returned. If comp_ids is a list of ints, maps of components with ids contained in the list will be returned.
calibratebool: If True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: if True, plots each factor to the same window. They are not scaled. Default is True.
titlestr: Title of the matplotlib plot or label of the line in the legend when the dimension of factors is 1 and same_window is True.
cmapColormap: The colormap used for the factor images, or for peak characteristics. Default is the matplotlib gray colormap (plt.cm.gray).
per_rowint: The number of plots in each row, when the same_window parameter is True.

See also

plot_bss_loadings, plot_bss_results

plot_bss_loadings(comp_ids=None, calibrate=True, same_window=True, title=None, with_factors=False, cmap='gray', no_nans=False, per_row=3, axes_decor='all', **kwargs)#

Plot loadings from blind source separation results. In case of 1D navigation axis, each loading line can be toggled on and off by clicking on their corresponding line in the legend.

Parameters:

comp_idsNone, int or list of int: If comp_ids=None, maps of all components will be returned. If it is an int, maps of components with ids from 0 to the given value will be returned. If comp_ids is a list of ints, maps of components with ids contained in the list will be returned.
calibratebool: if True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: If True, plots each factor to the same window. They are not scaled. Default is True.
titlestr: Title of the matplotlib plot or label of the line in the legend when the dimension of loadings is 1 and same_window is True.
with_factorsbool: If True, also returns figure(s) with the factors for the given comp_ids.
cmapColormap: The colormap used for the loading image, or for peak characteristics,. Default is the matplotlib gray colormap ("gray").
no_nansbool: If True, removes NaN’s from the loading plots.
per_rowint: The number of plots in each row, when the same_window parameter is True.
axes_decorstr or None, optional: One of: 'all', 'ticks', 'off', or None 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

See also

plot_bss_factors, plot_bss_results

plot_bss_results(factors_navigator='smart_auto', loadings_navigator='smart_auto', factors_dim=2, loadings_dim=2)#

Plot the blind source separation factors and loadings.

Unlike plot_bss_factors() and plot_bss_loadings(), this method displays one component at a time. Therefore it provides a more compact visualization than then other two methods. The loadings and factors are displayed in different windows and each has its own navigator/sliders to navigate them if they are multidimensional. The component index axis is synchronized between the two.

Parameters:

factors_navigatorstr, None, or BaseSignal (or subclass): One of: 'smart_auto', 'auto', None, 'spectrum' or a BaseSignal object. 'smart_auto' (default) displays sliders if the navigation dimension is less than 3. For a description of the other options see the plot() documentation for details.
loadings_navigatorstr, None, or BaseSignal (or subclass): See the factors_navigator parameter
factors_dimint: Currently HyperSpy cannot plot a signal when the signal dimension is higher than two. Therefore, to visualize the BSS results when the factors or the loadings have signal dimension greater than 2, the data can be viewed as spectra (or images) by setting this parameter to 1 (or 2). (The default is 2)
loadings_dimint: See the factors_dim parameter

See also

plot_bss_factors, plot_bss_loadings, plot_decomposition_results

plot_cluster_distances(cluster_ids=None, calibrate=True, same_window=True, with_centers=False, cmap='gray', no_nans=False, per_row=3, axes_decor='all', title=None, **kwargs)#

Plot the euclidian distances to the centroid of each cluster.

In case of 1D navigation axis, each line can be toggled on and off by clicking on the corresponding line in the legend.

Parameters:

cluster_idsNone, int, or list of int: if None (default), returns maps of all components using the number_of_cluster was defined when executing cluster. Otherwise it raises a ValueError. if int, returns maps of cluster labels with ids from 0 to given int. if list of ints, returns maps of cluster labels with ids in given list.
calibratebool: if True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: if True, plots each factor to the same window. They are not scaled. Default is True.
titlestr: Title of the matplotlib plot or label of the line in the legend when the dimension of distance is 1 and same_window is True.
with_centersbool: If True, also returns figure(s) with the cluster centers for the given cluster_ids.
cmapmatplotlib.colors.Colormap: The colormap used for the factor image, or for peak characteristics, the colormap used for the scatter plot of some peak characteristic.
no_nansbool: If True, removes NaN’s from the loading plots.
per_rowint: the number of plots in each row, when the same_window parameter is True.
axes_decorNone or str {‘all’, ‘ticks’, ‘off’}, 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

See also

plot_cluster_signals, plot_cluster_results, plot_cluster_labels

plot_cluster_labels(cluster_ids=None, calibrate=True, same_window=True, with_centers=False, cmap='gray', no_nans=False, per_row=3, axes_decor='all', title=None, **kwargs)#

Plot cluster labels from a cluster analysis. In case of 1D navigation axis, each loading line can be toggled on and off by clicking on the legended line.

Parameters:

cluster_idsNone, int, or list of int: if None (default), returns maps of all components using the number_of_cluster was defined when executing cluster. Otherwise it raises a ValueError. if int, returns maps of cluster labels with ids from 0 to given int. if list of ints, returns maps of cluster labels with ids in given list.
calibratebool: if True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: if True, plots each factor to the same window. They are not scaled. Default is True.
titlestr: Title of the matplotlib plot or label of the line in the legend when the dimension of labels is 1 and same_window is True.
with_centersbool: If True, also returns figure(s) with the cluster centers for the given cluster_ids.
cmapmatplotlib.colors.Colormap: The colormap used for the factor image, or for peak characteristics, the colormap used for the scatter plot of some peak characteristic.
no_nansbool: If True, removes NaN’s from the loading plots.
per_rowint: the number of plots in each row, when the same_window parameter is True.
axes_decorNone or str {'all', 'ticks', 'off'}, default 'all': 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

See also

plot_cluster_signals, plot_cluster_results

plot_cluster_metric()#

Plot the cluster metrics calculated using the estimate_number_of_clusters() method

See also

estimate_number_of_clusters, cluster_analysis, get_cluster_labels
get_cluster_signals, plot_cluster_results, plot_cluster_signals
plot_cluster_labels

plot_cluster_results(centers_navigator='smart_auto', labels_navigator='smart_auto', centers_dim=2, labels_dim=2)#

Plot the cluster labels and centers.

Unlike plot_cluster_labels() and plot_cluster_signals(), this method displays one component at a time. Therefore it provides a more compact visualization than then other two methods. The labels and centers are displayed in different windows and each has its own navigator/sliders to navigate them if they are multidimensional. The component index axis is synchronized between the two.

Parameters:

centers_navigator, labels_navigatorNone, {"smart_auto" | "auto" | "spectrum"} or BaseSignal, default "smart_auto": "smart_auto" displays sliders if the navigation dimension is less than 3. For a description of the other options see plot documentation for details.
labels_dim, centers_dimsint, default 2: Currently HyperSpy cannot plot signals of dimension higher than two. Therefore, to visualize the clustering results when the centers or the labels have signal dimension greater than 2 we can view the data as spectra(images) by setting this parameter to 1(2)

See also

plot_cluster_signals, plot_cluster_labels

plot_cluster_signals(signal='mean', cluster_ids=None, calibrate=True, same_window=True, title=None, per_row=3)#

Plot centers from a cluster analysis.

Parameters:

signal{“mean”, “sum”, “centroid”}, optional: If “mean” or “sum” return the mean signal or sum respectively over each cluster. If “centroid”, returns the signals closest to the centroid.
cluster_idsNone, int, or list of int: If None, returns maps of all clusters. If int, returns maps of clusters with ids from 0 to given int. If list of ints, returns maps of clusters with ids in given list.
calibratebool, default True: If True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool, default True: If True, plots each center to the same window. They are not scaled.
titleNone or str, default None: Title of the matplotlib plot or label of the line in the legend when the dimension of loadings is 1 and same_window is True.
per_rowint, default 3: The number of plots in each row, when the same_window parameter is True.

See also

plot_cluster_labels

plot_cumulative_explained_variance_ratio(*args, **kwargs)#

[Deprecated] Deprecated: use plot_cumulative_scree_plot() instead.

Notes

Deprecated since version 2.5: Function plot_cumulative_explained_variance_ratio() is deprecated and will be removed in version 3.0. Use plot_cumulative_scree_plot() instead.

plot_cumulative_scree_plot(n=50)#

Plot the cumulative scree plot up to n components.

For centred decompositions (e.g. PCA), the y-axis shows the cumulative explained variance ratio. For uncentred decompositions, it shows the cumulative proportion of total variation.

Parameters:

nint: Number of components to show.

Returns:

axmatplotlib.axes: Axes object containing the cumulative plot.

See also

plot_scree_plot

plot_decomposition_factors(comp_ids=None, calibrate=True, same_window=True, title=None, cmap='gray', per_row=3, **kwargs)#

Plot factors from a decomposition. In case of 1D signal axis, each factors line can be toggled on and off by clicking on their corresponding line in the legend.

Parameters:

comp_idsNone, int or list of int: If comp_ids is None, maps of all components will be returned if the output_dimension was defined when executing decomposition(). Otherwise it raises a ValueError. If comp_ids is an int, maps of components with ids from 0 to the given value will be returned. If comp_ids is a list of ints, maps of components with ids contained in the list will be returned.
calibratebool: If True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: If True, plots each factor to the same window. They are not scaled. Default is True.
titlestr: Title of the matplotlib plot or label of the line in the legend when the dimension of factors is 1 and same_window is True.
cmapColormap: The colormap used for the factor images, or for peak characteristics. Default is the matplotlib gray colormap ("gray").
per_rowint: The number of plots in each row, when the same_window parameter is True.

See also

plot_decomposition_loadings, plot_decomposition_results

plot_decomposition_loadings(comp_ids=None, calibrate=True, same_window=True, title=None, with_factors=False, cmap='gray', no_nans=False, per_row=3, axes_decor='all', **kwargs)#

Plot loadings from a decomposition. In case of 1D navigation axis, each loading line can be toggled on and off by clicking on the legended line.

Parameters:

comp_idsNone, int, or list of int: If comp_ids is None, maps of all components will be returned if the output_dimension was defined when executing decomposition(). Otherwise it raises a ValueError. If comp_ids is an int, maps of components with ids from 0 to the given value will be returned. If comp_ids is a list of ints, maps of components with ids contained in the list will be returned.
calibratebool: if True, calibrates plots where calibration is available from the axes_manager. If False, plots are in pixels/channels.
same_windowbool: if True, plots each factor to the same window. They are not scaled. Default is True.
titlestr: Title of the matplotlib plot or label of the line in the legend when the dimension of loadings is 1 and same_window is True.
with_factorsbool: If True, also returns figure(s) with the factors for the given comp_ids.
cmapColormap: The colormap used for the loadings images, or for peak characteristics. Default is the matplotlib gray colormap ("gray").
no_nansbool: If True, removes NaN’s from the loading plots.
per_rowint: The number of plots in each row, when the same_window parameter is True.
axes_decorstr or None, optional: One of: 'all', 'ticks', 'off', or None 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.

See also

plot_decomposition_factors, plot_decomposition_results

plot_decomposition_results(factors_navigator='smart_auto', loadings_navigator='smart_auto', factors_dim=2, loadings_dim=2)#

Plot the decomposition factors and loadings.

Unlike plot_decomposition_factors() and plot_decomposition_loadings(), this method displays one component at a time. Therefore it provides a more compact visualization than then other two methods. The loadings and factors are displayed in different windows and each has its own navigator/sliders to navigate them if they are multidimensional. The component index axis is synchronized between the two.

Parameters:

factors_navigatorstr, None, or BaseSignal (or subclass): One of: 'smart_auto', 'auto', None, 'spectrum' or a BaseSignal object. 'smart_auto' (default) displays sliders if the navigation dimension is less than 3. For a description of the other options see the plot() documentation for details.
loadings_navigatorstr, None, or BaseSignal (or subclass): See the factors_navigator parameter
factors_dim, loadings_dimint: Currently HyperSpy cannot plot a signal when the signal dimension is higher than two. Therefore, to visualize the BSS results when the factors or the loadings have signal dimension greater than 2, the data can be viewed as spectra (or images) by setting this parameter to 1 (or 2). (The default is 2)

See also

plot_decomposition_factors, plot_decomposition_loadings, plot_bss_results

plot_explained_variance_ratio(*args, **kwargs)#

[Deprecated] Deprecated: use plot_scree_plot() instead.

Notes

Deprecated since version 2.5: Function plot_explained_variance_ratio() is deprecated and will be removed in version 3.0. Use plot_scree_plot() instead.

plot_scree_plot(n=30, log=True, threshold=0, hline='auto', vline=False, xaxis_type='index', xaxis_labeling=None, signal_fmt=None, noise_fmt=None, fig=None, ax=None, **kwargs)#

Plot the decomposition scree plot (explained variance ratio vs component index).

For centred decompositions (e.g. PCA), the y-axis shows the explained variance ratio. For uncentred decompositions (e.g. plain SVD without mean-centring), it shows the proportion of total variation (ratio of squared singular values), which is not the same as explained variance.

Read more in the User Guide.

Parameters:

nint or None: Number of components to plot. If None, all components will be plot
logbool, default True: If True, the y axis uses a log scale.
thresholdfloat or int: Threshold used to determine how many components should be highlighted as signal (as opposed to noise). If a float (between 0 and 1), threshold will be interpreted as a cutoff value, defining the proportion of variation at which to draw a line showing the cutoff between signal and noise; the number of signal components will be automatically determined by the cutoff value. If an int, threshold is interpreted as the number of components to highlight as signal (and no cutoff line will be drawn)
hline: {‘auto’, True, False}: Whether or not to draw a horizontal line illustrating the variance cutoff for signal/noise determination. Default is to draw the line at the value given in threshold (if it is a float) and not draw in the case threshold is an int, or not given. If True, (and threshold is an int), the line will be drawn through the last component defined as signal. If False, the line will not be drawn in any circumstance.
vline: bool, default False: Whether or not to draw a vertical line illustrating an estimate of the number of significant components. If True, the line will be drawn at the the knee or elbow position of the curve indicating the number of significant components. If False, the line will not be drawn in any circumstance.
xaxis_type{‘index’, ‘number’}: Determines the type of labeling applied to the x-axis. If 'index', axis will be labeled starting at 0 (i.e. “pythonic index” labeling); if 'number', it will start at 1 (number labeling).
xaxis_labeling{‘ordinal’, ‘cardinal’, None}: Determines the format of the x-axis tick labels. If 'ordinal', “1st, 2nd, …” will be used; if 'cardinal', “1, 2, …” will be used. If None, an appropriate default will be selected.
signal_fmtdict: Dictionary of matplotlib formatting values for the signal components
noise_fmtdict: Dictionary of matplotlib formatting values for the noise components
figmatplotlib.figure.Figure or None: If None, a default figure will be created, otherwise will plot into fig
axmatplotlib.axes.Axes or None: If None, a default ax will be created, otherwise will plot into ax
**kwargs: remaining keyword arguments are passed to matplotlib.figure.Figure

Returns:

matplotlib.axes.Axes: Axes object containing the scree plot

See also

decomposition, get_scree_plot_data, get_decomposition_loadings
get_decomposition_factors

Examples

To generate a scree plot with customized symbols for signal vs. noise components and a modified cutoff threshold value:

>>> s = hs.load("some_spectrum_image")
>>> s.decomposition()
>>> s.plot_scree_plot(
...    n=40,
...    threshold=0.005,
...    signal_fmt={'marker': 'v', 's': 150, 'c': 'pink'},
...    noise_fmt={'marker': '*', 's': 200, 'c': 'green'}
...    )

print_summary_statistics(formatter='%.3g', rechunk=False)#

Prints the five-number summary statistics of the data, the mean, and the standard deviation.

Prints the mean, standard deviation (std), maximum (max), minimum (min), first quartile (Q1), median, and third quartile. nans are removed from the calculations.

Parameters:

formatterstr

The number formatter to use for the output

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

See also

get_histogram

property ragged#: Whether the signal is ragged or not.

rebin(new_shape=None, scale=None, crop=True, dtype=None, out=None)#

Rebin the signal into a smaller or larger shape, based on linear interpolation. Specify either new_shape or scale. Scale of 1 means no binning and scale less than one results in up-sampling.

Parameters:

new_shapelist (of float or int) or None: For each dimension specify the new_shape. This will internally be converted into a scale parameter.
scalelist (of float or int) or None: For each dimension, specify the new:old pixel ratio, e.g. a ratio of 1 is no binning and a ratio of 2 means that each pixel in the new spectrum is twice the size of the pixels in the old spectrum. The length of the list should match the dimension of the Signal’s underlying data array. Note : Only one of ``scale`` or ``new_shape`` should be specified, otherwise the function will not run
cropbool: Whether or not to crop the resulting rebinned data (default is True). When binning by a non-integer number of pixels it is likely that the final row in each dimension will contain fewer than the full quota to fill one pixel. For example, a 5*5 array binned by 2.1 will produce two rows containing 2.1 pixels and one row containing only 0.8 pixels. Selection of crop=True or crop=False determines whether or not this “black” line is cropped from the final binned array or not. Please note that if ``crop=False`` is used, the final row in each dimension may appear black if a fractional number of pixels are left over. It can be removed but has been left to preserve total counts before and after binning.
dtype{None, numpy.dtype, “same”}: Specify the dtype of the output. If None, the dtype will be determined by the behaviour of numpy.sum(), if "same", the dtype will be kept the same. Default is None.
outBaseSignal (or subclass) or None: If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

Returns:

BaseSignal: The resulting cropped signal.

Raises:

NotImplementedError: If trying to rebin over a non-uniform axis.

Examples

>>> spectrum = hs.signals.Signal1D(np.ones([4, 4, 10]))
>>> spectrum.data[1, 2, 9] = 5
>>> print(spectrum)
<Signal1D, title: , dimensions: (4, 4|10)>
>>> print ('Sum =', sum(sum(sum(spectrum.data))))
Sum = 164.0

>>> scale = [2, 2, 5]
>>> test = spectrum.rebin(scale)
>>> print(test)
<Signal1D, title: , dimensions: (2, 2|5)>
>>> print('Sum =', sum(sum(sum(test.data))))
Sum = 164.0

>>> s = hs.signals.Signal1D(np.ones((2, 5, 10), dtype=np.uint8))
>>> print(s)
<Signal1D, title: , dimensions: (5, 2|10)>
>>> print(s.data.dtype)
uint8

Use dtype=np.unit16 to specify a dtype

>>> s2 = s.rebin(scale=(5, 2, 1), dtype=np.uint16)
>>> print(s2.data.dtype)
uint16

Use dtype=”same” to keep the same dtype

>>> s3 = s.rebin(scale=(5, 2, 1), dtype="same")
>>> print(s3.data.dtype)
uint8

By default dtype=None, the dtype is determined by the behaviour of numpy.sum, in this case, unsigned integer of the same precision as the platform integer

>>> s4 = s.rebin(scale=(5, 2, 1))
>>> print(s4.data.dtype)
uint32

remove_spikes(threshold_factor=5, axes=None, inplace=True, **kwargs)#

Remove spikes (intense pixels that may have been generated by X-ray or cosmic ray events) from data. Values fullfilling the following condition will be replaced by their local median:

\[\mathrm{value} > \mathrm{median} + \sigma * \mathrm{threshold\_factor}\]

where \(\sigma\) is the standard deviation taken along the given axes.

The local median is calculated using the scipy.ndimage.median_filter() function.

Parameters:

threshold_factorint, float: Factor used in the thresholding calculation. A higher value will give a higher threshold value to find spikes and less spikes will removed. It must be a positive number. Default is 5.
axesint, str, DataAxis or tuple: Specify the axes used for calculating the local median. It is recommended to use axes of similar nature, where the local median is representative of the current value (for example, spatial position of mapped values). axes can be a single or multiple axes in a tuple. In both cases, the axes can be passed directly, or specified using the index in axes_manager or the name of the axis. If None, for Signal1D, the navigation axes are used. For signals with signal dimension >= 2, the signal axes are used. For signals with a signal dimension of 0, all axes are used.
inplacebool, default True: If True, the data is replaced by the result. Otherwise, a new Signal with the result is returned.
**kwargsdict: Keyword arguments are passed to scipy.ndimage.median_filter() of dask_image.ndfilters.median_filter() for lazy signals.

Returns:

signalsubclass of BaseSignal: If inplace=False, the signal with removed spikes.

See also

hyperspy.api.signals.Signal1D.spikes_removal_tool
hyperspy.api.signals.Signal1D.spikes_diagnosis

Examples

>>> import hyperspy.api as hs
>>> s = hs.data.two_gaussians()

Add spikes

>>> s.data[10, 5, 800] = 750
>>> s.data[10, 20, 200] = 2000
>>> s.data[15, 25, 500] = 50000

>>> s.remove_spikes()

With the default threshold_factor value of 5, the two largest spikes (values of 2000 and 50000) have been removed but not the smallest one (value of 750).

>>> s.remove_spikes(threshold_factor=3.5)

Parameters can be passed for the calculation of the median filter

>>> s.remove_spikes(size=5)

reverse_bss_component(component_number)#

Reverse the independent component.

Parameters:

component_numberlist or int: component index/es

Examples

>>> s = hs.load('some_file')
>>> s.decomposition(True)
>>> s.blind_source_separation(3)

Reverse component 1

>>> s.reverse_bss_component(1)

Reverse components 0 and 2

>>> s.reverse_bss_component((0, 2))

reverse_decomposition_component(component_number)#

Reverse the decomposition component.

Parameters:

component_numberlist or int: component index/es

Examples

>>> s = hs.load('some_file')
>>> s.decomposition(True)

Reverse component 1

>>> s.reverse_decomposition_component(1)

Reverse components 0 and 2

>>> s.reverse_decomposition_component((0, 2))

rollaxis(axis, to_axis, optimize=False)#

Roll the specified axis backwards, until it lies in a given position.

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively. The axis to roll backwards.

The positions of the other axes do not change relative to one another.

to_axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively. The axis is rolled until it lies before this other axis.

optimizebool

If True, the location of the data in memory is optimised for the fastest iteration over the navigation axes. This operation can cause a peak of memory usage and requires considerable processing times for large datasets and/or low specification hardware. See the Transposing (changing signal spaces) section of the HyperSpy user guide for more information. When operating on lazy signals, if True, the chunks are optimised for the new axes configuration.

Returns:

sBaseSignal (or subclass): Output signal.

See also

numpy.roll(), swap_axes

Examples

>>> s = hs.signals.Signal1D(np.ones((5, 4, 3, 6)))
>>> s
<Signal1D, title: , dimensions: (3, 4, 5|6)>
>>> s.rollaxis(3, 1)
<Signal1D, title: , dimensions: (3, 4, 5|6)>
>>> s.rollaxis(2, 0)
<Signal1D, title: , dimensions: (5, 3, 4|6)>

save(filename=None, overwrite=None, extension=None, file_format=None, **kwds)#

Saves the signal in the specified format.

The function gets the format from the specified extension (Supported formats):

blockfile (blo): Read/write support for ASTAR blockfiles.
digitalsurf (sur): Read and write data from .sur/.pro file formats from Digital Surf.
emd (emd): Read data from Berkeley’s Electron Microscopy Data (EMD) files.
hspy (hspy): The default file format for HyperSpy based on the HDF5 standard.
image (png): Import/Export standard image formats using PIL or freeimage.
mrcz (mrcz): Compressed MRC file format extension with blosc meta-compression.
msa (msa): Open standard format for single spectra defined by the Microscopy Society of America.
nexus (nxs): Read NXdata sets from NeXus files and metadata. Data and metadata from general hdf5 files can also be examined.
pantarhei (prz): File format used by CEOS PantaRhei, based on simple numpy arrays and dictionaries.
ripple (rpl): RPL file contains the information on how to read the RAW file with the same name.
semper (unf): Read data from Semper UNF (unformatted) files.
tiff (tif): Import/Export standard image formats using Christoph Gohlke’s tifffile library.
tvips (tvips): Read support for TVIPS CMOS camera stream/movie files. Can be used for in-situ movies or 4D-STEM datasets.
usid (h5): Data structured according to the Universal Spectroscopic and Imaging Data (USID) model, written into Hierarchical Data Format (HDF5) files.
zspy (zspy): HyperSpy file format definition based on the zarr standard, particularly suited for big data sets.
numpy (npy): Load numpy binary format.

All formats are provided by RosettaSciIO v0.14.0.

File format support is provided by RosettaSciIO. For detailed information about supported formats, format-specific parameters, and examples, see the RosettaSciIO documentation.

If no extension is provided the default file format as defined in the preferences is used. Please note that not all the formats supports saving datasets of arbitrary dimensions, e.g. 'msa' only supports 1D data, and blockfiles only supports image stacks with a navigation_dimension < 2.

Each format accepts a different set of parameters. For details see the specific format documentation.

Parameters:

filenamestr, Path, or None

The output filename or directory path. Can be:

Full path with extension: '/path/to/my_file.hspy'
Directory path only: '/path/to/output_folder/' - When a directory is provided, the filename is constructed from tmp_parameters.filename and the extension is determined from the file_format or tmp_parameters.extension parameters.
None: Uses tmp_parameters.folder and tmp_parameters.filename if available.

About tmp_parameters: These are automatically created when loading files and store the original filename, folder, and extension. This enables convenient workflows like batch processing where you can load files, process them, and save to new locations without manually specifying filenames.

overwriteNone or bool

If None, if the file exists it will query the user. If True(False) it does(not) overwrite the file if it exists.

extensionNone or str

Deprecated since version 2.4: The extension parameter is deprecated in version 2.4 and will be removed in version 3.0. Use file_format instead.

The extension of the file that defines the file format. Allowable string values are: 'blo', 'sur', 'emd', 'hspy', 'png', 'mrcz', 'msa', 'nxs', 'prz', 'rpl', 'unf', 'tif', 'tvips', 'h5', 'zspy', 'npy' (provided by RosettaSciIO v0.14.0) 'hspy' and 'hdf5' are equivalent. Use 'hdf5' if compatibility with HyperSpy versions older than 1.2 is required. If None, the extension is determined from the following list in this order:

the filename (if a full filename with extension is provided)
the file_format parameter (mapped to corresponding extension)
Signal.tmp_parameters.extension
'.hspy' (the default extension)

chunkstuple or True or None (default)

HyperSpy, Nexus and EMD NCEM format only. Define chunks used when saving. The chunk shape should follow the order of the array (s.data.shape), not the shape of the axes_manager. If None and lazy signal, the dask array chunking is used. If None and non-lazy signal, the chunks are estimated automatically to have at least one chunk per signal space. If True, the chunking is determined by the the h5py guess_chunk function.

save_original_metadatabool , defaultFalse

Nexus file only. Option to save hyperspy.original_metadata with the signal. A loaded Nexus file may have a large amount of data when loaded which you may wish to omit on saving

use_defaultbool , defaultFalse

Nexus file only. Define the default dataset in the file. If set to True the signal or first signal in the list of signals will be defined as the default (following Nexus v3 data rules).

write_datasetbool, optional

Only for hspy files. If True, write the dataset, otherwise, don’t write it. Useful to save attributes without having to write the whole dataset. Default is True.

close_filebool, optional

Only for hdf5-based files and some zarr store. Close the file after writing. Default is True.

file_formatNone or str, optional

The name or the extension of the file format of choice to save the file. If not given, it is inferred from the file extension. Supported formats:

blockfile (blo): Read/write support for ASTAR blockfiles.
digitalsurf (sur): Read and write data from .sur/.pro file formats from Digital Surf.
emd (emd): Read data from Berkeley’s Electron Microscopy Data (EMD) files.
hspy (hspy): The default file format for HyperSpy based on the HDF5 standard.
image (png): Import/Export standard image formats using PIL or freeimage.
mrcz (mrcz): Compressed MRC file format extension with blosc meta-compression.
msa (msa): Open standard format for single spectra defined by the Microscopy Society of America.
nexus (nxs): Read NXdata sets from NeXus files and metadata. Data and metadata from general hdf5 files can also be examined.
pantarhei (prz): File format used by CEOS PantaRhei, based on simple numpy arrays and dictionaries.
ripple (rpl): RPL file contains the information on how to read the RAW file with the same name.
semper (unf): Read data from Semper UNF (unformatted) files.
tiff (tif): Import/Export standard image formats using Christoph Gohlke’s tifffile library.
tvips (tvips): Read support for TVIPS CMOS camera stream/movie files. Can be used for in-situ movies or 4D-STEM datasets.
usid (h5): Data structured according to the Universal Spectroscopic and Imaging Data (USID) model, written into Hierarchical Data Format (HDF5) files.
zspy (zspy): HyperSpy file format definition based on the zarr standard, particularly suited for big data sets.
numpy (npy): Load numpy binary format.

All formats are provided by RosettaSciIO v0.14.0.

Examples

Save with a complete filename:

>>> s = hs.signals.Signal1D(np.arange(10))
>>> s.save("my_data.hspy")

Re-save a loaded signal in a different location (uses tmp_parameters):

>>> s = hs.load("original_data.hspy")  # tmp_parameters are auto-populated
>>> s.save("/new/output/folder/")      # Saves to /new/output/folder/original_data.hspy

Re-save a loaded signal in a different format:

>>> s = hs.load("data.hspy")           # Original format
>>> s.save("/output/", file_format="msa")  # Convert to MSA format
>>> s.save("/output/", file_format="rpl")  # Convert to Ripple format

Process multiple files and save in different format:

>>> import hyperspy.api as hs
>>> from pathlib import Path
>>>
>>> input_folder = Path("input_data/")
>>> output_folder = Path("processed_data/")
>>>
>>> for file_path in input_folder.glob("*.hspy"):
...     s = hs.load(file_path)
...     # Process the signal...
...     s = s.remove_background()
...     # Save in new location with different format
...     s.save(output_folder, file_format="msa")

set_noise_variance(variance)#

Set the noise variance of the signal.

Equivalent to s.metadata.set_item("Signal.Noise_properties.variance", variance).

Parameters:

varianceNone or float or BaseSignal (or subclass): Value or values of the noise variance. A value of None is equivalent to clearing the variance.

Returns:

None

set_signal_origin(origin)#

Set the signal_origin metadata value.

The signal_origin attribute specifies if the data was obtained through experiment or simulation.

Parameters:

originstr: Typically 'experiment' or 'simulation'

set_signal_type(signal_type='')#

Set the signal type and convert the current signal accordingly.

The signal_type attribute specifies the type of data that the signal contains e.g. electron energy-loss spectroscopy data, photoemission spectroscopy data, etc.

When setting signal_type to a “known” type, HyperSpy converts the current signal to the most appropriate BaseSignal subclass. Known signal types are signal types that have a specialized BaseSignal subclass associated, usually providing specific features for the analysis of that type of signal.

HyperSpy ships only with generic signal types. External packages can register domain-specific signal types, usually associated with specific measurement techniques. To print a list of registered signal types in the current installation, call print_known_signal_types(), and see the developer guide for details on how to add new signal_types. A non-exhaustive list of HyperSpy extensions is maintained here: hyperspy/hyperspy-extensions-list. See also the HyperSpy Website for an overview of the ecosystem.

Parameters:

signal_typestr, optional: If no arguments are passed, the signal_type is set to undefined and the current signal converted to a generic signal subclass. Otherwise, set the signal_type to the given signal type or to the signal type corresponding to the given signal type alias. Setting the signal_type to a known signal type (if exists) is highly advisable. If none exists, it is good practice to set signal_type to a value that best describes the data signal type.

See also

hyperspy.api.print_known_signal_types

Examples

Let’s first print all known signal types (assuming the extensions eXSpy and holoSpy are installed):

>>> s = hs.signals.Signal1D([0, 1, 2, 3])
>>> s
<Signal1D, title: , dimensions: (|4)>
>>> hs.print_known_signal_types()
+--------------------+---------------------+--------------------+----------+
|    signal_type     |       aliases       |     class name     | package  |
+--------------------+---------------------+--------------------+----------+
| DielectricFunction | dielectric function | DielectricFunction |   exspy  |
|      EDS_SEM       |                     |   EDSSEMSpectrum   |   exspy  |
|      EDS_TEM       |                     |   EDSTEMSpectrum   |   exspy  |
|        EELS        |       TEM EELS      |    EELSSpectrum    |   exspy  |
|      hologram      |                     |   HologramImage    |  holospy |
+--------------------+---------------------+--------------------+----------+

We can set the signal_type using the signal_type:

>>> s.set_signal_type("EELS")
>>> s
<EELSSpectrum, title: , dimensions: (|4)>
>>> s.set_signal_type("EDS_SEM")
>>> s
<EDSSEMSpectrum, title: , dimensions: (|4)>

or any of its aliases:

>>> s.set_signal_type("TEM EELS")
>>> s
<EELSSpectrum, title: , dimensions: (|4)>

To set the signal_type to “undefined”, simply call the method without arguments:

>>> s.set_signal_type()
>>> s
<Signal1D, title: , dimensions: (|4)>

split(axis='auto', number_of_parts='auto', step_sizes='auto')#

Splits the data into several signals.

The split can be defined by giving the number_of_parts, a homogeneous step size, or a list of customized step sizes. By default ('auto'), the function is the reverse of stack().

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

If 'auto' and if the object has been created with stack() (and stack_metadata=True), this method will return the former list of signals (information stored in metadata._HyperSpy.Stacking_history). If it was not created with stack(), the last navigation axis will be used.

number_of_partsstr or int

Number of parts in which the spectrum image will be split. The splitting is homogeneous. When the axis size is not divisible by the number_of_parts the remainder data is lost without warning. If number_of_parts and step_sizes is 'auto', number_of_parts equals the length of the axis, step_sizes equals one, and the axis is suppressed from each sub-spectrum.

step_sizesstr, list (of int), or int

Size of the split parts. If 'auto', the step_sizes equals one. If an int is given, the splitting is homogeneous.

Returns:

list of BaseSignal: A list of the split signals

Raises:

NotImplementedError: If trying to split along a non-uniform axis.

Examples

>>> s = hs.signals.Signal1D(np.random.random([4, 3, 2]))
>>> s
<Signal1D, title: , dimensions: (3, 4|2)>
>>> s.split()
[<Signal1D, title: , dimensions: (3|2)>, <Signal1D, title: , dimensions: (3|2)>, <Signal1D, title: , dimensions: (3|2)>, <Signal1D, title: , dimensions: (3|2)>]
>>> s.split(step_sizes=2)
[<Signal1D, title: , dimensions: (3, 2|2)>, <Signal1D, title: , dimensions: (3, 2|2)>]
>>> s.split(step_sizes=[1, 2])
[<Signal1D, title: , dimensions: (3, 1|2)>, <Signal1D, title: , dimensions: (3, 2|2)>]

squeeze()#

Remove single-dimensional entries from the shape of an array and the axes. See numpy.squeeze() for more details.

Returns:

ssignal: A new signal object with single-entry dimensions removed

Examples

>>> s = hs.signals.Signal2D(np.random.random((2, 1, 1, 6, 8, 8)))
>>> s
<Signal2D, title: , dimensions: (6, 1, 1, 2|8, 8)>
>>> s = s.squeeze()
>>> s
<Signal2D, title: , dimensions: (6, 2|8, 8)>

std(axis=None, out=None, rechunk=False)#

Returns a signal with the standard deviation of the signal along at least one axis.

Parameters:

axisint, str, DataAxis or tuple

Either a single or multiple axes in a tuple can be passed. In both cases, the axes can be passed directly, or specified using the index in axes_manager or the name of the axis. Any duplicates are removed. If "sig" or "nav", the signal or navigation axes will be used, respectively. If None, the operation is performed over all navigation axes (default).

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the standard deviation of the provided Signal over the specified axes

See also

max, min, sum, mean, var, indexmax, indexmin, valuemax, valuemin

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.std(0)
<Signal2D, title: , dimensions: (|64, 64)>

sum(axis=None, out=None, rechunk=False)#

Sum the data over the given axes.

Parameters:

axisint, str, DataAxis or tuple

Either a single or multiple axes in a tuple can be passed. In both cases, the axes can be passed directly, or specified using the index in axes_manager or the name of the axis. Any duplicates are removed. If "sig" or "nav", the signal or navigation axes will be used, respectively. If None, the operation is performed over all navigation axes (default).

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

BaseSignal: A new Signal containing the sum of the provided Signal along the specified axes.

See also

max, min, mean, std, var, indexmax, indexmin, valuemax, valuemin

Notes

If you intend to calculate the numerical integral of an unbinned signal, please use the integrate1D() function instead. To avoid erroneous misuse of the sum function as integral, it raises a warning when working with an unbinned, non-uniform axis.

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.sum(0)
<Signal2D, title: , dimensions: (|64, 64)>

swap_axes(axis1, axis2, optimize=False)#

Swap two axes in the signal.

Parameters:

axis1: :class:`int`, :class:`str`, or :class:`~hyperspy.axes.DataAxis`: The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.
axis2: :class:`int`, :class:`str`, or :class:`~hyperspy.axes.DataAxis`: The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.
optimizebool: If True, the location of the data in memory is optimised for the fastest iteration over the navigation axes. This operation can cause a peak of memory usage and requires considerable processing times for large datasets and/or low specification hardware. See the Transposing (changing signal spaces) section of the HyperSpy user guide for more information. When operating on lazy signals, if True, the chunks are optimised for the new axes configuration.

Returns:

sBaseSignal (or subclass): A copy of the object with the axes swapped.

See also

rollaxis

to_device()#

Transfer data array from host to GPU device memory using cupy.asarray. Lazy signals are not supported by this method, see user guide for information on how to process data lazily using the GPU.

Returns:

None.

Raises:

BaseException: Raise expection if cupy is not installed.
BaseException: Raise expection if signal is lazy.

to_host()#

Transfer data array from GPU device to host memory.

Returns:

None.

Raises:

BaseException: Raise expection if signal is lazy.

transpose(signal_axes=None, navigation_axes=None, optimize=False)#

Transposes the signal to have the required signal and navigation axes.

Parameters:

signal_axesNone, int, or iterable type: The number (or indices) of axes to convert to signal axes
navigation_axesNone, int, or iterable type: The number (or indices) of axes to convert to navigation axes
optimizebool: If True, the location of the data in memory is optimised for the fastest iteration over the navigation axes. This operation can cause a peak of memory usage and requires considerable processing times for large datasets and/or low specification hardware. See the Transposing (changing signal spaces) section of the HyperSpy user guide for more information. When operating on lazy signals, if True, the chunks are optimised for the new axes configuration.

See also

T, as_signal2D, as_signal1D

Notes

With the exception of both axes parameters (signal_axes and navigation_axes getting iterables, generally one has to be None (i.e. “floating”). The other one specifies either the required number or explicitly the indices of axes to move to the corresponding space. If both are iterables, full control is given as long as all axes are assigned to one space only.

Examples

>>> # just create a signal with many distinct dimensions
>>> s = hs.signals.BaseSignal(np.random.rand(1,2,3,4,5,6,7,8,9))
>>> s
<BaseSignal, title: , dimensions: (|9, 8, 7, 6, 5, 4, 3, 2, 1)>

>>> s.transpose() # swap signal and navigation spaces
<BaseSignal, title: , dimensions: (9, 8, 7, 6, 5, 4, 3, 2, 1|)>

>>> s.T # a shortcut for no arguments
<BaseSignal, title: , dimensions: (9, 8, 7, 6, 5, 4, 3, 2, 1|)>

>>> # roll to leave 5 axes in navigation space
>>> s.transpose(signal_axes=5)
<BaseSignal, title: , dimensions: (4, 3, 2, 1|9, 8, 7, 6, 5)>

>>> # roll leave 3 axes in navigation space
>>> s.transpose(navigation_axes=3)
<BaseSignal, title: , dimensions: (3, 2, 1|9, 8, 7, 6, 5, 4)>

>>> # 3 explicitly defined axes in signal space
>>> s.transpose(signal_axes=[0, 2, 6])
<BaseSignal, title: , dimensions: (8, 6, 5, 4, 2, 1|9, 7, 3)>

>>> # A mix of two lists, but specifying all axes explicitly
>>> # The order of axes is preserved in both lists
>>> s.transpose(navigation_axes=[1, 2, 3, 4, 5, 8], signal_axes=[0, 6, 7])
<BaseSignal, title: , dimensions: (8, 7, 6, 5, 4, 1|9, 3, 2)>

undo_treatments()#: Undo Poisson noise normalization and other pre-treatments.

Deprecated since version 2.5: This method is deprecated and will be removed in a future release. Pre-treatment data modifications are now reversed mathematically after decomposition, so explicit undo is no longer needed.

unfold(unfold_navigation=True, unfold_signal=True)#

Modifies the shape of the data by unfolding the signal and navigation dimensions separately

Parameters:

unfold_navigationbool: Whether or not to unfold the navigation dimension(s) (default: True)
unfold_signalbool: Whether or not to unfold the signal dimension(s) (default: True)

Returns:

needed_unfoldingbool: Whether or not one of the axes needed unfolding (and that unfolding was performed)

Notes

It doesn’t make sense to perform an unfolding when the total number of dimensions is < 2.

unfold_navigation_space()#

Modify the shape of the data to obtain a navigation space of dimension 1

Returns:

needed_unfoldingbool: Whether or not the navigation space needed unfolding (and whether it was performed)

unfold_signal_space()#

Modify the shape of the data to obtain a signal space of dimension 1

Returns:

needed_unfoldingbool: Whether or not the signal space needed unfolding (and whether it was performed)

unfolded(unfold_navigation=True, unfold_signal=True)#

Use this function together with a with statement to have the signal be unfolded for the scope of the with block, before automatically refolding when passing out of scope.

See also

unfold, fold

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> with s.unfolded():
...     # Do whatever needs doing while unfolded here
...     pass

update_plot()#: If this Signal has been plotted, update the signal and navigator plots, as appropriate.

valuemax(axis, out=None, rechunk=False)#

Returns a signal with the value of coordinates of the maximum along an axis.

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the calibrated coordinate values of the maximum along the specified axis.

See also

hyperspy.api.signals.BaseSignal.max, hyperspy.api.signals.BaseSignal.min
hyperspy.api.signals.BaseSignal.sum, hyperspy.api.signals.BaseSignal.mean
hyperspy.api.signals.BaseSignal.std, hyperspy.api.signals.BaseSignal.var
hyperspy.api.signals.BaseSignal.indexmax, hyperspy.api.signals.BaseSignal.indexmin
hyperspy.api.signals.BaseSignal.valuemin

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.valuemax(0)
<Signal2D, title: , dimensions: (|64, 64)>

valuemin(axis, out=None, rechunk=False)#

Returns a signal with the value of coordinates of the minimum along an axis.

Parameters:

axisint, str, or DataAxis

The axis can be passed directly, or specified using the index of the axis in the Signal’s axes_manager or the axis name. If "sig" or "nav", the signal or navigation axis will be used, respectively.

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

BaseSignal or subclass: A new Signal containing the calibrated coordinate values of the minimum along the specified axis.

See also

hyperspy.api.signals.BaseSignal.max, hyperspy.api.signals.BaseSignal.min
hyperspy.api.signals.BaseSignal.sum, hyperspy.api.signals.BaseSignal.mean
hyperspy.api.signals.BaseSignal.std, hyperspy.api.signals.BaseSignal.var
hyperspy.api.signals.BaseSignal.indexmax, hyperspy.api.signals.BaseSignal.indexmin
hyperspy.api.signals.BaseSignal.valuemax

var(axis=None, out=None, rechunk=False)#

Returns a signal with the variances of the signal along at least one axis.

Parameters:

axisint, str, DataAxis or tuple

Either a single or multiple axes in a tuple can be passed. In both cases, the axes can be passed directly, or specified using the index in axes_manager or the name of the axis. Any duplicates are removed. If "sig" or "nav", the signal or navigation axes will be used, respectively. If None, the operation is performed over all navigation axes (default).

outBaseSignal (or subclass) or None

If None, a new Signal is created with the result of the operation and returned (default). If a Signal is passed, it is used to receive the output of the operation, and nothing is returned.

rechunkbool, str or tuple

Only for lazy signal, default is False. If False, the chunking structure will be retained. If True (use "auto"), the data may be automatically rechunked before performing this operation, when the chunking changes.

Chunking options:

"auto": chunking doesn’t split the signal dimension,
"dask_auto": uses dask’s automatic chunking,
tuple: defines the chunking.

Returns:

sBaseSignal (or subclass): A new Signal containing the variance of the provided Signal over the specified axes

See also

max, min, sum, mean, std, indexmax, indexmin, valuemax, valuemin

Examples

>>> import numpy as np
>>> s = BaseSignal(np.random.random((64, 64, 1024)))
>>> s
<BaseSignal, title: , dimensions: (|1024, 64, 64)>
>>> s.var(0)
<Signal2D, title: , dimensions: (|64, 64)>

BaseSignal#

`BaseSignal`#