`exspy.signals`#

`DielectricFunction`(args, *kwargs)	Signal class for dielectric functions.
`EDSSpectrum`(args, *kwards)	General signal class for EDS spectra.
`EDSTEMSpectrum`(args, *kwards)	Signal class for EDS spectra measured in an TEM.
`EELSSpectrum`(args, *kwargs)	Signal class for EELS spectra.
`EDSSEMSpectrum`(args, *kwards)	Signal class for EDS spectra measured in an SEM.

`LazyDielectricFunction`(args, *kwargs)	Lazy signal class for dielectric functions.
`LazyEDSSpectrum`(args, *kwards)	Lazy general signal class for EDS spectra.
`LazyEDSSEMSpectrum`(args, *kwards)	Lazy signal class for EDS spectra measured in an SEM.
`LazyEDSTEMSpectrum`(args, *kwards)	Lazy signal class for EDS spectra measured in an TEM.
`LazyEELSSpectrum`(args, *kwargs)	Lazy signal class for EELS spectra.

Modules containing the eXSpy signals and their lazy counterparts.

EELSSpectrum: For electron energy-loss data with signal_dimension equal one, i.e. spectral data of n dimensions. The signal is binned by default.
EDSTEMSpectrum: For electron energy-dispersive X-ray data acquired in a transmission electron microscopy with signal_dimension equal one, i.e. spectral data of n dimensions. The signal is binned by default.
EDSSEMSpectrum: For electron energy-dispersive X-ray data acquired in a scanning electron microscope with signal_dimension equal one, i.e. spectral data of n dimensions. The signal is binned by default.
DielectricFunction: For dielectric function data with signal_dimension equal one. The signal is unbinned by default.

class exspy.signals.DielectricFunction(*args, **kwargs)#

Bases: ComplexSignal1D

Signal class for dielectric functions.

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

get_electron_energy_loss_spectrum(zlp, t)#

Compute single-scattering electron-energy loss spectrum from the dielectric function.

Parameters:

zlp (float or hyperspy.api.signals.BaseSignal) – If the ZLP is the same for all spectra, the intengral of the ZLP can be provided as a number. Otherwise, if the ZLP intensity is not the same for all spectra, it can be provided as i) a Signal of the same dimensions as the current signal containing the ZLP spectra for each location ii) a Signal of signal dimension 0 and navigation_dimension equal to the current signal containing the integrated ZLP intensity.
t (None, float or hyperspy.api.signals.BaseSignal) – The sample thickness in nm. If the thickness is the same for all spectra it can be given by a number. Otherwise, it can be provided as a Signal with signal dimension 0 and navigation_dimension equal to the current signal.

Return type:

hyperspy.api.signals.BaseSignal

get_number_of_effective_electrons(nat, cumulative=False)#

Compute the number of effective electrons using the Bethe f-sum rule.

The Bethe f-sum rule gives rise to two definitions of the effective number (see [*]), neff1 and neff2:

\[n_{\mathrm{eff_{1}}} = n_{\mathrm{eff}}\left(-\Im\left(\epsilon^{-1}\right)\right)\]

and:

\[n_{\mathrm{eff_{2}}} = n_{\mathrm{eff}}\left(\epsilon_{2}\right)\]

This method computes and return both.

Parameters:: nat (float) – Number of atoms (or molecules) per unit volume of the sample.
Returns:: neff1, neff2 – Signal1D instances containing neff1 and neff2. The signal and navigation dimensions are the same as the current signal if cumulative is True, otherwise the signal dimension is 0 and the navigation dimension is the same as the current signal.
Return type:: hyperspy.api.signals.Signal1D

Notes

class exspy.signals.EDSSEMSpectrum(*args, **kwards)#

Bases: EDSSpectrum

Signal class for EDS spectra measured in an SEM.

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

create_model(auto_background=True, auto_add_lines=True, *args, **kwargs)#

Create a model for the current SEM EDS data.

Parameters:

auto_background (boolean, default True) – If True, adds automatically a polynomial order 6 to the model, using the edsmodel.add_polynomial_background method.
auto_add_lines (boolean, default True) – If True, automatically add Gaussians for all X-rays generated in the energy range by an element using the edsmodel.add_family_lines method.
dictionary ({None, dict}, optional) – A dictionary to be used to recreate a model. Usually generated using hyperspy.model.as_dictionary()

Returns:

model

Return type:

EDSSEMModel instance.

get_calibration_from(ref, nb_pix=1)#

Copy the calibration and all metadata of a reference.

Primary use: To add a calibration to ripple file from INCA software

Parameters:

ref (signal) – The reference contains the calibration in its metadata
nb_pix (int) – The live time (real time corrected from the “dead time”) is divided by the number of pixel (spectrums), giving an average live time.

Raises:

NotImplementedError – If the signal axis is a non-uniform axis.

Examples

>>> ref = exspy.data.EDS_SEM_TM002()
>>> s = exspy.signals.EDSSEMSpectrum(ref.data)
>>> print(s.axes_manager[0].scale)
>>> s.get_calibration_from(ref)
>>> print(s.axes_manager[0].scale)
1.0
0.01

set_microscope_parameters(beam_energy=None, live_time=None, tilt_stage=None, azimuth_angle=None, elevation_angle=None, energy_resolution_MnKa=None, display=True, toolkit=None)#

Set the microscope parameters.

If no arguments are given, raises an interactive mode to fill the values.

Parameters:

beam_energy (float) – The energy of the electron beam in keV
live_time (float) – In second
tilt_stage (float) – In degree
azimuth_angle (float) – In degree
elevation_angle (float) – In degree
energy_resolution_MnKa (float) – In eV
display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkit (str, iterable of str or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

Examples

>>> s = exspy.data.EDS_TEM_FePt_nanoparticles()
>>> print('Default value %s eV' %
>>>       s.metadata.Acquisition_instrument.
>>>       SEM.Detector.EDS.energy_resolution_MnKa)
>>> s.set_microscope_parameters(energy_resolution_MnKa=135.)
>>> print('Now set to %s eV' %
>>>       s.metadata.Acquisition_instrument.
>>>       SEM.Detector.EDS.energy_resolution_MnKa)
Default value 130.0 eV
Now set to 135.0 eV

class exspy.signals.EDSSpectrum(*args, **kwards)#

Bases: Signal1D

General signal class for EDS spectra.

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

add_elements(elements)#

Add elements and the corresponding X-ray lines.

The list of elements is stored in metadata.Sample.elements

Parameters:: elements (list of strings) – The symbol of the elements.

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> print(s.metadata.Sample.elements)
>>> s.add_elements(['Ar'])
>>> print(s.metadata.Sample.elements)
['Al' 'C' 'Cu' 'Mn' 'Zr']
['Al', 'Ar', 'C', 'Cu', 'Mn', 'Zr']

add_lines(lines=(), only_one=True, only_lines=('a',))#

Add X-rays lines to the internal list.

Although most functions do not require an internal list of X-ray lines because they can be calculated from the internal list of elements, ocassionally it might be useful to customize the X-ray lines to be use by all functions by default using this method. The list of X-ray lines is stored in metadata.Sample.xray_lines

Parameters:

lines (list of strings) – A list of valid element X-ray lines to add e.g. Fe_Kb. Additionally, if metadata.Sample.elements is defined, add the lines of those elements that where not given in this list. If the list is empty (default), and metadata.Sample.elements is defined, add the lines of all those elements.
only_one (bool) – If False, add all the lines of each element in metadata.Sample.elements that has not line defined in lines. If True (default), only add the line at the highest energy above an overvoltage of 2 (< beam energy / 2).
only_lines ({None, list of strings}) – If not None, only the given lines will be added.

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.add_lines()
>>> print(s.metadata.Sample.xray_lines)
['Al_Ka', 'C_Ka', 'Cu_La', 'Mn_La', 'Zr_La']

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.set_microscope_parameters(beam_energy=30)
>>> s.add_lines()
>>> print(s.metadata.Sample.xray_lines)
['Al_Ka', 'C_Ka', 'Cu_Ka', 'Mn_Ka', 'Zr_La']

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.add_lines()
>>> print(s.metadata.Sample.xray_lines)
>>> s.add_lines(['Cu_Ka'])
>>> print(s.metadata.Sample.xray_lines)
['Al_Ka', 'C_Ka', 'Cu_La', 'Mn_La', 'Zr_La']
['Al_Ka', 'C_Ka', 'Cu_Ka', 'Cu_La', 'Mn_La', 'Zr_La']

add_xray_lines_markers(xray_lines, render_figure=True)#

Add marker on a spec.plot() with the name of the selected X-ray lines

Parameters:: xray_lines (list of string) – A valid list of X-ray lines

estimate_background_windows(line_width=[2, 2], windows_width=1, xray_lines=None)#

Estimate two windows around each X-ray line containing only the background.

Parameters:

line_width (list of two floats) – The position of the two windows around the X-ray line is given by the line_width (left and right) times the calculated FWHM of the line.
windows_width (float) – The width of the windows is is the windows_width times the calculated FWHM of the line.
xray_lines (None or list of string) – If None, use metadata.Sample.elements.xray_lines. Else, provide an iterable containing a list of valid X-ray lines symbols.

Returns:

windows_position – The position of the windows in energy. Each line corresponds to a X-ray line. In a line, the two first values correspond to the limits of the left window and the two last values correspond to the limits of the right window.

Return type:

2D array of float

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.add_lines()
>>> bw = s.estimate_background_windows(line_width=[5.0, 2.0])
>>> s.plot(background_windows=bw)
>>> s.get_lines_intensity(background_windows=bw, plot_result=True)
Fe_Ka at 6.4039 keV : Intensity = 2754.00
Pt_La at 9.4421 keV : Intensity = 15090.00

See also

plot, get_lines_intensity

estimate_integration_windows(windows_width=2.0, xray_lines=None)#

Estimate a window of integration for each X-ray line.

Parameters:

windows_width (float) – The width of the integration windows is the ‘windows_width’ times the calculated FWHM of the line.
xray_lines (None or list of string) – If None, use ‘metadata.Sample.elements.xray_lines’. Else, provide an iterable containing a list of valid X-ray lines symbols.

Returns:

integration_windows – The positions of the windows in energy. Each row corresponds to a X-ray line. Each row contains the left and right value of the window.

Return type:

2D array of float

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.add_lines()
>>> iw = s.estimate_integration_windows()
>>> s.plot(integration_windows=iw)
>>> s.get_lines_intensity(integration_windows=iw, plot_result=True)
Fe_Ka at 6.4039 keV : Intensity = 3710.00
Pt_La at 9.4421 keV : Intensity = 15872.00

See also

plot, get_lines_intensity

get_lines_intensity(xray_lines=None, integration_windows=2.0, background_windows=None, plot_result=False, only_one=True, only_lines=('a',), **kwargs)#

Return the intensity map of selected Xray lines.

The intensities, the number of X-ray counts, are computed by suming the spectrum over the different X-ray lines. The sum window width is calculated from the energy resolution of the detector as defined in ‘energy_resolution_MnKa’ of the metadata. Backgrounds average in provided windows can be subtracted from the intensities.

Parameters:

xray_lines ({None, Iterable* of strings}) – If None, if metadata.Sample.elements.xray_lines contains a list of lines use those. If metadata.Sample.elements.xray_lines is undefined or empty but metadata.Sample.elements is defined, use the same syntax as add_line to select a subset of lines for the operation. Alternatively, provide an iterable containing a list of valid X-ray lines symbols. * Note that while dictionaries and strings are iterable, their use is ambiguous and specifically not allowed.
integration_windows (Float or array) – If float, the width of the integration windows is the ‘integration_windows_width’ times the calculated FWHM of the line. Else provide an array for which each row corresponds to a X-ray line. Each row contains the left and right value of the window.
background_windows (None or 2D array of float) – If None, no background subtraction. Else, the backgrounds average in the windows are subtracted from the return intensities. ‘background_windows’ provides the position of the windows in energy. Each line corresponds to a X-ray line. In a line, the two first values correspond to the limits of the left window and the two last values correspond to the limits of the right window.
plot_result (bool) – If True, plot the calculated line intensities. If the current object is a single spectrum it prints the result instead.
only_one (bool) – If False, use all the lines of each element in the data spectral range. If True use only the line at the highest energy above an overvoltage of 2 (< beam energy / 2).
only_lines ({None, list of strings}) – If not None, use only the given lines.
kwargs – The extra keyword arguments for plotting. See utils.plot.plot_signals

Returns:

intensities – A list containing the intensities as BaseSignal subclasses.

Return type:

list

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.get_lines_intensity(['Mn_Ka'], plot_result=True)
Mn_La at 0.63316 keV : Intensity = 96700.00

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.plot(['Mn_Ka'], integration_windows=2.1)
>>> s.get_lines_intensity(['Mn_Ka'],
>>>                       integration_windows=2.1, plot_result=True)
Mn_Ka at 5.8987 keV : Intensity = 53597.00

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.set_elements(['Mn'])
>>> s.set_lines(['Mn_Ka'])
>>> bw = s.estimate_background_windows()
>>> s.plot(background_windows=bw)
>>> s.get_lines_intensity(background_windows=bw, plot_result=True)
Mn_Ka at 5.8987 keV : Intensity = 46716.00

get_take_off_angle()#

Calculate the take-off-angle (TOA).

TOA is the angle with which the X-rays leave the surface towards the detector. Parameters are read in ‘SEM.Stage.tilt_alpha’, ‘Acquisition_instrument.SEM.Detector.EDS.azimuth_angle’ and ‘SEM.Detector.EDS.elevation_angle’ and ‘SEM.Stage.tilt_beta in ‘metadata’.

Returns:: take_off_angle – in Degree
Return type:: float

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.get_take_off_angle()
37.0
>>> s.set_microscope_parameters(tilt_stage=20.)
>>> s.get_take_off_angle()
57.0

See also

hs.eds.take_off_angle

plot(xray_lines=False, only_lines=('a', 'b'), only_one=False, background_windows=None, integration_windows=None, navigator='auto', plot_markers=True, autoscale='v', norm='auto', axes_manager=None, navigator_kwds={}, **kwargs)#

Plot the EDS spectrum. The following markers can be added

The position of the X-ray lines and their names.
The background windows associated with each X-ray lines. A black line links the left and right window with the average value in each window.

Parameters:

xray_lines ({False, True, 'from_elements', list of string}) – If not False, indicate the position and the name of the X-ray lines. If True, if metadata.Sample.elements.xray_lines contains a list of lines use those. If metadata.Sample.elements.xray_lines is undefined or empty or if xray_lines equals ‘from_elements’ and metadata.Sample.elements is defined, use the same syntax as add_line to select a subset of lines for the operation. Alternatively, provide an iterable containing a list of valid X-ray lines symbols.
only_lines (None or list of strings) – If not None, use only the given lines (eg. (‘a’,’Kb’)). If None, use all lines.
only_one (bool) – If False, use all the lines of each element in the data spectral range. If True use only the line at the highest energy above an overvoltage of 2 (< beam energy / 2).
background_windows (None or 2D array of float) – If not None, add markers at the position of the windows in energy. Each line corresponds to a X-ray lines. In a line, the two first value corresponds to the limit of the left window and the two last values corresponds to the limit of the right window.
integration_windows (None or 'auto' or float or 2D array of float) – If not None, add markers at the position of the integration windows. If ‘auto’ (or float), the width of the integration windows is 2.0 (or float) times the calculated FWHM of the line. see ‘estimate_integration_windows’. Else provide an array for which each row corresponds to a X-ray line. Each row contains the left and right value of the window.
navigator (str, None, or BaseSignal (or subclass).)
'auto' (Allowed string values are) –
- 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'.
'slider' –
- 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'.
'spectrum'. (and) –
- 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_manager (None or AxesManager) – If None, the signal’s axes_manager attribute is used.
plot_markers (bool, 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_kwds (dict) – Only for image navigator, additional keyword arguments for matplotlib.pyplot.imshow().
norm (str, 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).
autoscale (str) – 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'.

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.plot()

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.plot(True)

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.add_lines()
>>> bw = s.estimate_background_windows()
>>> s.plot(background_windows=bw)

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.plot(['Mn_Ka'], integration_windows='auto')

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.add_lines()
>>> bw = s.estimate_background_windows()
>>> s.plot(background_windows=bw, integration_windows=2.1)

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_shape (list (of float or int) or None) – For each dimension specify the new_shape. This will internally be converted into a scale parameter.
scale (list (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
crop (bool) – 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.
out (BaseSignal (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:

The resulting cropped signal.

Return type:

BaseSignal

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_xray_lines_markers(xray_lines, render_figure=True)#

Remove marker previously added on a spec.plot() with the name of the selected X-ray lines

Parameters:

xray_lines (list of string) – A valid list of X-ray lines to remove
render_figure (bool) – If True, render the figure after removing the markers

set_elements(elements)#

Erase all elements and set them.

Parameters:: elements (list of strings) – A list of chemical element symbols.

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> print(s.metadata.Sample.elements)
>>> s.set_elements(['Al'])
>>> print(s.metadata.Sample.elements)
['Al' 'C' 'Cu' 'Mn' 'Zr']
['Al']

set_lines(lines, only_one=True, only_lines=('a',))#

Erase all Xrays lines and set them.

See add_lines for details.

Parameters:

lines (list of strings) – A list of valid element X-ray lines to add e.g. Fe_Kb. Additionally, if metadata.Sample.elements is defined, add the lines of those elements that where not given in this list.
only_one (bool) – If False, add all the lines of each element in metadata.Sample.elements that has not line defined in lines. If True (default), only add the line at the highest energy above an overvoltage of 2 (< beam energy / 2).
only_lines ({None, list of strings}) – If not None, only the given lines will be added.

Examples

>>> s = exspy.data.EDS_SEM_TM002()
>>> s.add_lines()
>>> print(s.metadata.Sample.xray_lines)
>>> s.set_lines(['Cu_Ka'])
>>> print(s.metadata.Sample.xray_lines)
['Al_Ka', 'C_Ka', 'Cu_La', 'Mn_La', 'Zr_La']
['Al_Ka', 'C_Ka', 'Cu_Ka', 'Mn_La', 'Zr_La']

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

Sum the data over the given axes.

Parameters:

axis (int, 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).
out (BaseSignal (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.
rechunk (bool) – Only has effect when operating on lazy signal. Default False, which means the chunking structure will be retained. If True, the data may be automatically rechunked before performing this operation.

Returns:

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

Return type:

BaseSignal

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.

See also

max, min, 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.sum(0)
<Signal2D, title: , dimensions: (|64, 64)>

class exspy.signals.EDSTEMSpectrum(*args, **kwards)#

Bases: EDSSpectrum

Signal class for EDS spectra measured in an TEM.

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

static CL_get_mass_thickness(weight_percent, thickness)#

Creates a array of mass_thickness based on a known material composition and measured thickness. Required for absorption correction calcultions using the Cliff Lorimer method.

Parameters:

weight_percent (BaseSignal (or subclass)) – Stack of compositions as determined from an initial k_factor quantification.
thickness (float or numpy.ndarray) – Either a float value for thickness in nm or an array equal to the size of the EDX map with thickness at each position of the sample.

Returns:

mass_thickness – Mass thickness in kg/m².

Return type:

numpy.ndarray

create_model(auto_background=True, auto_add_lines=True, *args, **kwargs)#

Create a model for the current TEM EDS data.

Parameters:

auto_background (bool, default True) – If True, adds automatically a polynomial order 6 to the model, using the edsmodel.add_polynomial_background method.
auto_add_lines (bool, default True) – If True, automatically add Gaussians for all X-rays generated in the energy range by an element using the edsmodel.add_family_lines method.
dictionary ({None, dict}, optional) – A dictionary to be used to recreate a model. Usually generated using hyperspy.model.as_dictionary()

Returns:

model

Return type:

EDSTEMModel instance.

decomposition(normalize_poissonian_noise=True, navigation_mask=1.0, closing=True, *args, **kwargs)#

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

The results are stored in self.learning_results.

See also

vacuum_mask

References

get_calibration_from(ref, nb_pix=1)#

Copy the calibration and all metadata of a reference.

Primary use: To add a calibration to ripple file from INCA software

Parameters:

ref (signal) – The reference contains the calibration in its metadata
nb_pix (int) – The live time (real time corrected from the “dead time”) is divided by the number of pixel (spectrums), giving an average live time.

Raises:

NotImplementedError – If the signal axis is a non-uniform axis.

Examples

>>> ref = exspy.data.EDS_TEM_FePt_nanoparticles()
>>> s = exspy.data.EDS_TEM_FePt_nanoparticles(ref.data)
>>> print(s.axes_manager[0].scale)
>>> s.get_calibration_from(ref)
>>> print(s.axes_manager[0].scale)
1.0
0.020028

get_probe_area(navigation_axes=None)#

Calculates a pixel area which can be approximated to probe area, when the beam is larger than or equal to pixel size. The probe area can be calculated only when the number of navigation dimension are less than 2 and all the units have the dimensions of length.

Parameters:: navigation_axes (DataAxis, string or integer (or list of)) – Navigation axes corresponding to the probe area. If string or integer, the provided value is used to index the axes_manager.
Return type:: probe area in nm².

Examples

>>> s = exspy.data.EDS_TEM_FePt_nanoparticles()
>>> si = hs.stack([s]*3)
>>> si.axes_manager.navigation_axes[0].scale = 0.01
>>> si.axes_manager.navigation_axes[0].units = 'μm'
>>> si.get_probe_area()
100.0

quantification(intensities, method, factors, composition_units='atomic', absorption_correction=False, take_off_angle='auto', thickness='auto', convergence_criterion=0.5, navigation_mask=1.0, closing=True, plot_result=False, probe_area='auto', max_iterations=30, show_progressbar=None, **kwargs)#

Absorption corrected quantification using Cliff-Lorimer, the zeta-factor method, or ionization cross sections. The function iterates through quantification function until two successive interations don’t change the final composition by a defined percentage critera (0.5% by default).

Parameters:

intensities (list of signal) – the intensitiy for each X-ray lines.
method ({'CL', 'zeta', 'cross_section'}) – Set the quantification method: Cliff-Lorimer, zeta-factor, or ionization cross sections.
factors (list of float) – The list of kfactors, zeta-factors or cross sections in same order as intensities. Note that intensities provided by Hyperspy are sorted by the alphabetical order of the X-ray lines. eg. factors =[0.982, 1.32, 1.60] for [‘Al_Ka’, ‘Cr_Ka’, ‘Ni_Ka’].
composition_units ({'atomic', 'weight'}) – The quantification returns the composition in ‘atomic’ percent by default, but can also return weight percent if specified.
absorption_correction (bool) – Specify whether or not an absorption correction should be applied. ‘False’ by default so absorption will not be applied unless specfied.
take_off_angle ({'auto'}) – The angle between the sample surface and the vector along which X-rays travel to reach the centre of the detector.
thickness ({'auto'}) – thickness in nm (can be a single value or have the same navigation dimension as the signal). NB: Must be specified for ‘CL’ method. For ‘zeta’ or ‘cross_section’ methods, first quantification step provides a mass_thickness internally during quantification.
convergence_criterion (The convergence criterium defined as the percentage) – difference between 2 successive iterations. 0.5% by default.
navigation_mask (None or float or signal) – The navigation locations marked as True are not used in the quantification. If float is given the vacuum_mask method is used to generate a mask with the float value as threhsold. Else provides a signal with the navigation shape. Only for the ‘Cliff-Lorimer’ method.
closing (bool) – If true, applied a morphologic closing to the mask obtained by vacuum_mask.
plot_result (bool) – If True, plot the calculated composition. If the current object is a single spectrum it prints the result instead.
{'auto'} (probe_area =) – This allows the user to specify the probe_area for interaction with the sample needed specifically for the cross_section method of quantification. When left as ‘auto’ the pixel area is used, calculated from the navigation axes information.
max_iterations (int) – An upper limit to the number of calculations for absorption correction.
kwargs – The extra keyword arguments are passed to plot.

Returns:

A list of quantified elemental maps (signal) giving the composition of
the sample in weight or atomic percent with absorption correciton taken
into account based on the sample thickness estimate provided.
If the method is ‘zeta’ this function also returns the mass thickness
profile for the data.
If the method is ‘cross_section’ this function also returns the atom
counts for each element.

Examples

>>> s = exspy.data.EDS_TEM_FePt_nanoparticles()
>>> s.add_lines()
>>> kfactors = [1.450226, 5.075602] #For Fe Ka and Pt La
>>> bw = s.estimate_background_windows(line_width=[5.0, 2.0])
>>> s.plot(background_windows=bw)
>>> intensities = s.get_lines_intensity(background_windows=bw)
>>> res = s.quantification(intensities, kfactors, plot_result=True,
>>>                        composition_units='atomic')
Fe (Fe_Ka): Composition = 15.41 atomic percent
Pt (Pt_La): Composition = 84.59 atomic percent

See also

vacuum_mask

set_microscope_parameters(beam_energy=None, live_time=None, tilt_stage=None, azimuth_angle=None, elevation_angle=None, energy_resolution_MnKa=None, beam_current=None, probe_area=None, real_time=None, display=True, toolkit=None)#

Set the microscope parameters.

If no arguments are given, raises an interactive mode to fill the values.

Parameters:

beam_energy (float) – The energy of the electron beam in keV
live_time (float) – In seconds
tilt_stage (float) – In degree
azimuth_angle (float) – In degree
elevation_angle (float) – In degree
energy_resolution_MnKa (float) – In eV
beam_current (float) – In nA
probe_area (float) – In nm²
real_time (float) – In seconds
display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkit (str, iterable of str or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.

Examples

>>> s = exspy.data.EDS_TEM_FePt_nanoparticles()
>>> print(s.metadata.Acquisition_instrument.
>>>       TEM.Detector.EDS.energy_resolution_MnKa)
>>> s.set_microscope_parameters(energy_resolution_MnKa=135.)
>>> print(s.metadata.Acquisition_instrument.
>>>       TEM.Detector.EDS.energy_resolution_MnKa)
133.312296
135.0

vacuum_mask(threshold=1.0, closing=True, opening=False)#

Generate mask of the vacuum region

Parameters:

threshold (float) – For a given pixel, maximum value in the energy axis below which the pixel is considered as vacuum.
closing (bool) – If true, applied a morphologic closing to the mask
opnening (bool) – If true, applied a morphologic opening to the mask

Returns:

mask – The mask of the region

Return type:

signal

Examples

>>> # Simulate a spectrum image with vacuum region
>>> s = exspy.data.EDS_TEM_FePt_nanoparticles()
>>> s_vac = hs.signals.BaseSignal(
        np.ones_like(s.data, dtype=float))*0.005
>>> s_vac.add_poissonian_noise()
>>> si = hs.stack([s]*3 + [s_vac])
>>> si.vacuum_mask().data
array([False, False, False,  True], dtype=bool)

class exspy.signals.EELSSpectrum(*args, **kwargs)#

Bases: Signal1D

Signal class for EELS spectra.

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

add_elements(elements, include_pre_edges=False)#

Declare the elemental composition of the sample.

The ionisation edges of the elements present in the current energy range will be added automatically.

Parameters:

elements (tuple of strings) – The symbol of the elements. Note this input must always be in the form of a tuple. Meaning: add_elements((‘C’,)) will work, while add_elements((‘C’)) will NOT work.
include_pre_edges (bool) – If True, the ionization edges with an onset below the lower energy limit of the SI will be included

Examples

>>> s = hs.signals.EELSSpectrum(np.arange(1024))
>>> s.add_elements(('C', 'O'))

Raises:: ValueError –

align_zero_loss_peak(calibrate=True, also_align=[], print_stats=True, subpixel=True, mask=None, signal_range=None, show_progressbar=None, crop=True, **kwargs)#

Align the zero-loss peak.

This function first aligns the spectra using the result of estimate_zero_loss_peak_centre which finds the maximum in the given energy range, then if subpixel is True, proceeds to align with subpixel accuracy using align1D. The offset is automatically correct if calibrate is True.

Parameters:

calibrate (bool) – If True, set the offset of the spectral axis so that the zero-loss peak is at position zero.
also_align (list of signals) – A list containing other spectra of identical dimensions to align using the shifts applied to the current spectrum. If calibrate is True, the calibration is also applied to the spectra in the list.
print_stats (bool) – If True, print summary statistics of the ZLP maximum before the alignment.
subpixel (bool) – If True, perform the alignment with subpixel accuracy using cross-correlation.
mask (Signal1D of bool data type or bool array.) – It must have signal_dimension = 0 and navigation_shape equal to the shape of the current signal. Where mask is True the shift is not computed and set to nan.
signal_range (tuple of integers, tuple of floats. Optional) – Will only search for the ZLP within the signal_range. If given in integers, the range will be in index values. If given floats, the range will be in spectrum values. Useful if there are features in the spectrum which are more intense than the ZLP. Default is searching in the whole signal. Note that ROIs can be used in place of a tuple.
show_progressbar (None or bool) – If True, display a progress bar. If None, the default from the preferences settings is used.
crop (bool) – If True automatically crop the signal axis at both ends if needed.

Raises:

NotImplementedError – If the signal axis is a non-uniform axis.

Examples

>>> s_ll = hs.signals.EELSSpectrum(np.zeros(1000))
>>> s_ll.data[100] = 100
>>> s_ll.align_zero_loss_peak()

Aligning both the lowloss signal and another signal

>>> s = hs.signals.EELSSpectrum(np.range(1000))
>>> s_ll.align_zero_loss_peak(also_align=[s])

Aligning within a narrow range of the lowloss signal

>>> s_ll.align_zero_loss_peak(signal_range=(-10.,10.))

See also

estimate_zero_loss_peak_centre, align1D, estimate_shift1D.

Notes

Any extra keyword arguments are passed to align1D. For more information read its docstring.

create_model(low_loss=None, auto_background=True, auto_add_edges=True, GOS='dft', gos_file_path=None, dictionary=None)#

Create a model for the current EELS data.

Parameters:

ll (None or EELSSpectrum) – If an EELSSpectrum is provided, it will be assumed that it is a low-loss EELS spectrum, and it will be used to simulate the effect of multiple scattering by convolving it with the EELS spectrum.
auto_background (bool) – If True, and if spectrum is an EELS instance adds automatically a powerlaw to the model and estimate the parameters by the two-area method.
auto_add_edges (bool) – If True, and if spectrum is an EELS instance, it will automatically add the ionization edges as defined in the EELSSpectrum instance. Adding a new element to the spectrum using the add_elements() method automatically add the corresponding ionisation edges to the model.
GOS (Generalized Oscillator Strength, availiable option in ['hydrogenic', 'dft', 'dirac', 'Hartree-Slater'], default is 'dft') – The GOS to use. Default is 'dft'.
gos_file_path (str, None) – Only with GOS=’dft’ or ‘dirac’. Specify the file path of the gosh file to use. If None, use the file from doi:10.5281/zenodo.7645765
dictionary (None or dict) – A dictionary to be used to recreate a model. Usually generated using as_dictionary()
GOS

Returns:

model

Return type:

EELSModel instance.

Raises:

NotImplementedError – If the signal axis is a non-uniform axis.

edges_at_energy(energy='interactive', width=10, only_major=False, order='closest', display=True, toolkit=None)#

Show EELS edges according to an energy range selected from the spectrum or within a provided energy window

Parameters:

energy ('interactive' or float) – If it is ‘interactive’, a table with edges are shown and it depends on the energy range selected in the spectrum. If it is a float, a table with edges are shown and it depends on the energy window defined by energy +/- (width/2). The default is ‘interactive’.
width (float) – Width of window, in eV, around energy in which to find nearby energies, i.e. a value of 10 eV (the default) means to search +/- 5 eV. The default is 10.
only_major (bool) – Whether to show only the major edges. The default is False.
order (str) – Sort the edges, if ‘closest’, return in the order of energy difference, if ‘ascending’, return in ascending order, similarly for ‘descending’. The default is ‘closest’.

Returns:

An interactive widget if energy is ‘interactive’, or a html-format
table or ASCII table, depends on the environment.

estimate_elastic_scattering_intensity(threshold, show_progressbar=None)#

Rough estimation of the elastic scattering intensity by truncation of a EELS low-loss spectrum.

Parameters:

threshold ({Signal1D, float, int}) – Truncation energy to estimate the intensity of the elastic scattering. The threshold can be provided as a signal of the same dimension as the input spectrum navigation space containing the threshold value in the energy units. Alternatively a constant threshold can be specified in energy/index units by passing float/int.
show_progressbar (None or bool) – If True, display a progress bar. If None, the default from the preferences settings is used.

Returns:

I0 – The elastic scattering intensity.

Return type:

Signal1D

See also

estimate_elastic_scattering_threshold

estimate_elastic_scattering_threshold(window=10.0, tol=None, window_length=5, polynomial_order=3, start=1.0)#

Calculate the first inflexion point of the spectrum derivative within a window.

This method assumes that the zero-loss peak is located at position zero in all the spectra. Currently it looks for an inflexion point, that can be a local maximum or minimum. Therefore, to estimate the elastic scattering threshold start + window must be less than the first maximum for all spectra (often the bulk plasmon maximum). If there is more than one inflexion point in energy the window it selects the smoother one what, often, but not always, is a good choice in this case.

Parameters:

window ({None, float}) – If None, the search for the local inflexion point is performed using the full energy range. A positive float will restrict the search to the (0,window] energy window, where window is given in the axis units. If no inflexion point is found in this spectral range the window value is returned instead.
tol ({None, float}) – The threshold tolerance for the derivative. If “auto” it is automatically calculated as the minimum value that guarantees finding an inflexion point in all the spectra in given energy range.
window_length (int) – If non zero performs order three Savitzky-Golay smoothing to the data to avoid falling in local minima caused by the noise. It must be an odd integer.
polynomial_order (int) – Savitzky-Golay filter polynomial order.
start (float) – Position from the zero-loss peak centre from where to start looking for the inflexion point.

Returns:

threshold – A Signal1D of the same dimension as the input spectrum navigation space containing the estimated threshold. Where the threshold couldn’t be estimated the value is set to nan.

Return type:

Signal1D

See also

estimate_elastic_scattering_intensity, align_zero_loss_peak, find_peaks1D_ohaver, fourier_ratio_deconvolution.

Notes

The main purpose of this method is to be used as input for estimate_elastic_scattering_intensity. Indeed, for currently achievable energy resolutions, there is not such a thing as a elastic scattering threshold. Therefore, please be aware of the limitations of this method when using it.

estimate_thickness(threshold=None, zlp=None, density=None, mean_free_path=None)#

Estimates the thickness (relative and absolute) of a sample using the log-ratio method.

The current EELS spectrum must be a low-loss spectrum containing the zero-loss peak. The hyperspectrum must be well calibrated and aligned. To obtain the thickness relative to the mean free path don’t set the density and the mean_free_path.

Parameters:

threshold ({BaseSignal, float}, optional) – If the zero-loss-peak is not provided, use this energy threshold to roughly estimate its intensity by truncation. If the threshold is constant across the dataset use a float. Otherwise, provide a signal of the same dimension as the input spectrum navigation space containing the threshold value in the energy units.
zlp (BaseSignal, optional) – If not None the zero-loss peak intensity is calculated from the ZLP spectrum supplied by integration.
mean_free_path (float, optional) – The mean free path of the material in nanometers. If not provided, the thickness is given relative to the mean free path.
density (float, optional) – The density of the material in g/cm**3. This is used to estimate the mean free path when the mean free path is not known and to perform the angular corrections.

Returns:

s – The thickness relative to the MFP. It returns a Signal1D, Signal2D or a BaseSignal, depending on the current navigation dimensions.

Return type:

BaseSignal

Notes

For details see Egerton, R. Electron Energy-Loss Spectroscopy in the Electron Microscope. Springer-Verlag, 2011.

estimate_zero_loss_peak_centre(mask=None)#

Estimate the position of the zero-loss peak.

This function provides just a coarse estimation of the position of the zero-loss peak centre by computing the position of the maximum of the spectra. For subpixel accuracy use estimate_shift1D.

Parameters:: mask (Signal1D of bool data type or bool array) – It must have signal_dimension = 0 and navigation_shape equal to the navigation shape of the current signal. Where mask is True the shift is not computed and set to nan.
Returns:: zlpc – The estimated position of the maximum of the ZLP peak.
Return type:: Signal1D subclass

Notes

This function only works when the zero-loss peak is the most intense feature in the spectrum. If it is not in most cases the spectrum can be cropped to meet this criterion. Alternatively use estimate_shift1D.

See also

estimate_shift1D, align_zero_loss_peak

fourier_log_deconvolution(zlp, add_zlp=False, crop=False)#

Performs fourier-log deconvolution.

Parameters:

zlp (EELSSpectrum) – The corresponding zero-loss peak.
add_zlp (bool) – If True, adds the ZLP to the deconvolved spectrum
crop (bool) – If True crop the spectrum to leave out the channels that have been modified to decay smoothly to zero at the sides of the spectrum.

Return type:

An EELSSpectrum containing the current data deconvolved.

Raises:

NotImplementedError – If the signal axis is a non-uniform axis.

Notes

For details see: Egerton, R. Electron Energy-Loss Spectroscopy in the Electron Microscope. Springer-Verlag, 2011.

fourier_ratio_deconvolution(ll, fwhm=None, threshold=None, extrapolate_lowloss=True, extrapolate_coreloss=True)#

Performs Fourier-ratio deconvolution.

The core-loss should have the background removed. To reduce the noise amplification the result is convolved with a Gaussian function.

Parameters:

ll (EELSSpectrum) – The corresponding low-loss (ll) EELSSpectrum.
fwhm (float or None) – Full-width half-maximum of the Gaussian function by which the result of the deconvolution is convolved. It can be used to select the final SNR and spectral resolution. If None, the FWHM of the zero-loss peak of the low-loss is estimated and used.
threshold ({None, float}) – Truncation energy to estimate the intensity of the elastic scattering. If None the threshold is taken as the first minimum after the ZLP centre.
extrapolate_lowloss (bool) – If True the signals are extrapolated using a power law,
extrapolate_coreloss (bool) – If True the signals are extrapolated using a power law,

Raises:

NotImplementedError – If the signal axis is a non-uniform axis.

Notes

For details see: Egerton, R. Electron Energy-Loss Spectroscopy in the Electron Microscope. Springer-Verlag, 2011.

generate_subshells(include_pre_edges=False)#

Calculate the subshells for the current energy range for the elements present in self.elements

Parameters:: include_pre_edges (bool) – If True, the ionization edges with an onset below the lower energy limit of the SI will be included

get_zero_loss_peak_mask(zero_loss_peak_mask_width=5.0, signal_mask=None)#

Return boolean array with True value at the position of the zero loss peak. This mask can be used to restrict operation to the signal locations not marked as True (masked).

Parameters:

zero_loss_peak_mask_width (float) – Width of the zero loss peak mask.
signal_mask (numpy.ndarray of bool) – Restricts the operation to the signal locations not marked as True (masked).

Return type:

bool array

kramers_kronig_analysis(zlp=None, iterations=1, n=None, t=None, delta=0.5, full_output=False)#

Calculate the complex dielectric function from a single scattering distribution (SSD) using the Kramers-Kronig relations.

It uses the FFT method as in [1]. The SSD is an EELSSpectrum instance containing SSD low-loss EELS with no zero-loss peak. The internal loop is devised to approximately subtract the surface plasmon contribution supposing an unoxidized planar surface and neglecting coupling between the surfaces. This method does not account for retardation effects, instrumental broadening and surface plasmon excitation in particles.

Note that either refractive index or thickness are required. If both are None or if both are provided an exception is raised.

Parameters:

zlp ({None, number, Signal1D}) – ZLP intensity. It is optional (can be None) if t is None and n is not None and the thickness estimation is not required. If t is not None, the ZLP is required to perform the normalization and if t is not None, the ZLP is required to calculate the thickness. If the ZLP is the same for all spectra, the integral of the ZLP can be provided as a number. Otherwise, if the ZLP intensity is not the same for all spectra, it can be provided as i) a Signal1D of the same dimensions as the current signal containing the ZLP spectra for each location ii) a BaseSignal of signal dimension 0 and navigation_dimension equal to the current signal containing the integrated ZLP intensity.
iterations (int) – Number of the iterations for the internal loop to remove the surface plasmon contribution. If 1 the surface plasmon contribution is not estimated and subtracted (the default is 1).
n ({None, float}) – The medium refractive index. Used for normalization of the SSD to obtain the energy loss function. If given the thickness is estimated and returned. It is only required when t is None.
t ({None, number, Signal1D}) – The sample thickness in nm. Used for normalization of the SSD to obtain the energy loss function. It is only required when n is None. If the thickness is the same for all spectra it can be given by a number. Otherwise, it can be provided as a BaseSignal with signal dimension 0 and navigation_dimension equal to the current signal.
delta (float) – A small number (0.1-0.5 eV) added to the energy axis in specific steps of the calculation the surface loss correction to improve stability.
full_output (bool) – If True, return a dictionary that contains the estimated thickness if t is None and the estimated surface plasmon excitation and the spectrum corrected from surface plasmon excitations if iterations > 1.

Returns:

eps (DielectricFunction instance) –

The complex dielectric function results,

\[\epsilon = \epsilon_1 + i*\epsilon_2,\]

contained in an DielectricFunction instance.
output (Dictionary (optional)) – A dictionary of optional outputs with the following keys
- thickness: the estimated thickness in nm calculated by normalization of the SSD (only when t is None)
- surface plasmon estimation: the estimated surface plasmon excitation (only if iterations > 1.)

Raises:

ValueError – If both n and t are undefined (None).
AttributeError – If the beam_energy or the collection semi-angle are not defined in metadata.
NotImplementedError – If the signal axis is a non-uniform axis.

Notes

This method is based in Egerton’s Matlab code [1] with a minor difference: the wrap-around problem when computing the FFTs is workarounded by padding the signal instead of subtracting the reflected tail.

plot(plot_edges=False, only_edges=('Major', 'Minor'), **kwargs)#

Plot the EELS spectrum. Markers indicating the position of the EELS edges can be added.

Parameters:

plot_edges ({False, True, list of string or string}) – If True, draws on s.metadata.Sample.elements for edges. Alternatively, provide a string of a single edge, or an iterable containing a list of valid elements, EELS families or edges. For example, an element should be ‘Zr’, an element edge family should be ‘Zr_L’ or an EELS edge ‘Zr_L3’.
only_edges (tuple of string) – Either ‘Major’ or ‘Minor’. Defaults to both.
kwargs – The extra keyword arguments for plot()

power_law_extrapolation(window_size=20, extrapolation_size=1024, add_noise=False, fix_neg_r=False)#

Extrapolate the spectrum to the right using a powerlaw.

Parameters:

window_size (int) – The number of channels from the right side of the spectrum that are used to estimate the power law parameters.
extrapolation_size (int) – Size of the extrapolation in number of channels
add_noise (bool) – If True, add poissonian noise to the extrapolated spectrum.
fix_neg_r (bool) – If True, the negative values for the “components.PowerLaw” parameter r will be flagged and the extrapolation will be done with a constant zero-value.

Return type:

A new spectrum, with the extrapolation.

static print_edges_near_energy(energy=None, width=10, only_major=False, order='closest', edges=None)#

Find and print a table of edges near a given energy that are within the given energy window.

Parameters:

energy (float) – Energy to search, in eV
width (float) – Width of window, in eV, around energy in which to find nearby energies, i.e. a value of 10 eV (the default) means to search +/- 5 eV. The default is 10.
only_major (bool) – Whether to show only the major edges. The default is False.
order (str) – Sort the edges, if ‘closest’, return in the order of energy difference, if ‘ascending’, return in ascending order, similarly for ‘descending’. The default is ‘closest’.
edges (iterable) – A sequence of edges, if provided, it overrides energy, width, only_major and order.

Returns:

A PrettyText object where its representation is ASCII in terminal and
html-formatted in Jupyter notebook

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_shape (list (of float or int) or None) – For each dimension specify the new_shape. This will internally be converted into a scale parameter.
scale (list (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
crop (bool) – 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.
out (BaseSignal (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:

The resulting cropped signal.

Return type:

BaseSignal

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

richardson_lucy_deconvolution(psf, iterations=15, show_progressbar=None, num_workers=None)#

1D Richardson-Lucy Poissonian deconvolution of the spectrum by the given kernel.

Parameters:

psf (EELSSpectrum) – It must have the same signal dimension as the current spectrum and a spatial dimension of 0 or the same as the current spectrum.
iterations (int) – Number of iterations of the deconvolution. Note that increasing the value will increase the noise amplification.
show_progressbar (None or bool) – If True, display a progress bar. If None, the default from the preferences settings is used.
num_workers (None or int) – Number of worker used by dask. If None, default to dask default value.

Raises:

NotImplementedError – If the signal axis is a non-uniform axis.

Notes

For details on the algorithm see Gloter, A., A. Douiri, M. Tence, and C. Colliex. “Improving Energy Resolution of EELS Spectra: An Alternative to the Monochromator Solution.” Ultramicroscopy 96, no. 3–4 (September 2003): 385–400.

set_microscope_parameters(beam_energy=None, convergence_angle=None, collection_angle=None, toolkit=None, display=True)#

Set the microscope parameters that are necessary to calculate the GOS.

If not all of them are defined, in interactive mode raises an UI item to fill the values.

beam_energy: float: The energy of the electron beam in keV.
convergence_anglefloat: The microscope convergence semi-angle in mrad.
collection_anglefloat: The collection semi-angle in mrad.
toolkitstr, iterable of str or None: If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.
displaybool: If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.

spikes_diagnosis(signal_mask=None, navigation_mask=None, zero_loss_peak_mask_width=None, **kwargs)#

Plots a histogram to help in choosing the threshold for spikes removal.

Parameters:

signal_mask (boolean array) – Restricts the operation to the signal locations not marked as True (masked)
navigation_mask (boolean array) – Restricts the operation to the navigation locations not marked as True (masked).
zero_loss_peak_mask_width (None or float) – If None, the zero loss peak is not masked, otherwise, use the provided value as width of the zero loss peak mask. Default is None.
**kwargs (dict) – Keyword arguments pass to get_histogram()

See also

spikes_removal_tool

spikes_removal_tool(signal_mask=None, navigation_mask=None, threshold='auto', zero_loss_peak_mask_width=None, interactive=True, display=True, toolkit=None)#

Graphical interface to remove spikes from EELS spectra or luminescence data. If non-interactive, it removes all spikes.

Parameters:

signal_mask (numpy.ndarray of bool) – Restricts the operation to the signal locations not marked as True (masked).
navigation_mask (numpy.ndarray of bool) – Restricts the operation to the navigation locations not marked as True (masked).
threshold ('auto' or int) – if int set the threshold value use for the detecting the spikes. If "auto", determine the threshold value as being the first zero value in the histogram obtained from the spikes_diagnosis() method.
zero_loss_peak_mask_width (None or float) – If None, the zero loss peak is not masked, otherwise, use the provided value as width of the zero loss peak mask. Default is None.
interactive (bool) – If True, remove the spikes using the graphical user interface. If False, remove all the spikes automatically, which can introduce artefacts if used with signal containing peak-like features. However, this can be mitigated by using the signal_mask argument to mask the signal of interest.
display (bool) – If True, display the user interface widgets. If False, return the widgets container in a dictionary, usually for customisation or testing.
toolkit (str, iterable of str or None) – If None (default), all available widgets are displayed or returned. If string, only the widgets of the selected toolkit are displayed if available. If an interable of toolkit strings, the widgets of all listed toolkits are displayed or returned.
**kwargs (dict) – Keyword arguments pass to SpikesRemoval.

See also

spikes_diagnosis()

vacuum_mask(threshold=10.0, start_energy=None, closing=True, opening=False)#

Generate mask of the vacuum region

Parameters:

threshold (float) – For a given navigation coordinate, mean value in the energy axis below which the pixel is considered as vacuum.
start_energy (float, None) – Minimum energy included in the calculation of the mean intensity. If None, consider only the last quarter of the spectrum to calculate the mask.
closing (bool) – If True, a morphological closing is applied to the mask.
opening (bool) – If True, a morphological opening is applied to the mask.

Returns:

mask – The mask of the region.

Return type:

signal

class exspy.signals.LazyDielectricFunction(*args, **kwargs)#

Bases: DielectricFunction, LazyComplexSignal1D

Lazy signal class for dielectric functions. The computation is delayed until explicitly requested.

This class is not expected to be instantiated directly, instead use:

>>> data = da.ones((10, 10))
>>> s = hs.signals.DielectricFunction(data).as_lazy()

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

class exspy.signals.LazyEDSSEMSpectrum(*args, **kwards)#

Bases: EDSSEMSpectrum, LazyEDSSpectrum

Lazy signal class for EDS spectra measured in an SEM. The computation is delayed until explicitly requested.

This class is not expected to be instantiated directly, instead use:

>>> data = da.ones((10, 10))
>>> s = hs.signals.EDSSEMSpectrum(data).as_lazy()

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

class exspy.signals.LazyEDSSpectrum(*args, **kwards)#

Bases: EDSSpectrum, LazySignal1D

Lazy general signal class for EDS spectra. The computation is delayed until explicitly requested.

This class is not expected to be instantiated directly, instead use:

>>> data = da.ones((10, 10))
>>> s = hs.signals.EDSSpectrum(data).as_lazy()

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

class exspy.signals.LazyEDSTEMSpectrum(*args, **kwards)#

Bases: EDSTEMSpectrum, LazyEDSSpectrum

Lazy signal class for EDS spectra measured in an TEM. The computation is delayed until explicitly requested.

This class is not expected to be instantiated directly, instead use:

>>> data = da.ones((10, 10))
>>> s = hs.signals.EDSTEMSpectrum(data).as_lazy()

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

class exspy.signals.LazyEELSSpectrum(*args, **kwargs)#

Bases: EELSSpectrum, LazySignal1D

Lazy signal class for EELS spectra. The computation is delayed until explicitly requested.

This class is not expected to be instantiated directly, instead use:

>>> data = da.ones((10, 10))
>>> s = hs.signals.EELSSpectrum(data).as_lazy()

Create a signal instance.

Parameters:

data (numpy.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).
attributes (dict, optional) – A dictionary whose items are stored as attributes.
metadata (dict, 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_metadata (dict, 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.
ragged (bool 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.

exspy.signals#

`exspy.signals`#