abtem.measurements

property base_axes_metadata#

block_direct(...) → DiffractionPatterns[source]#

Block the direct beam by setting the pixels of the zeroth-order Bragg reflection (non-scattered beam) to zero.

Parameters:

radius (float, optional) – The radius of the zeroth-order reflection to block [mrad]. If not given this will be inferred from the metadata, if available.
margin (bool, optional) – If True adds a margin to the blocking radius to fully block soft apertures. Margin is true by default for diffraction patterns with semiangle_cutoff in metadata.

Returns:

diffraction_patterns – The diffraction pattern(s) with the direct beam removed.

Return type:

center_of_mass(...) → Images | RealSpaceLineProfiles[source]#

Calculate center-of-mass images or line profiles from diffraction patterns. The results are of type complex where the real and imaginary part represents the x and y component.

Parameters:

units ({'1/Å', 'mrad'}) – Units of the center-of-mass values of the output images or line profiles. Default is ‘1/Å’.

Returns:

com_images (Images) – Center-of-mass images.
com_line_profiles (RealSpaceLineProfiles) – Center-of-mass line profiles (returned if there is only one scan axis).

property coordinates: tuple[ndarray, ndarray]#: Reciprocal-space frequency coordinates [1 / Å].

crop(...) → DiffractionPatterns[source]#

Crop the diffraction patterns such that they only include spatial frequencies (scattering angles) up to a given limit.

Parameters:

max_angle (float, optional) – The maximum included scattering angle in the cropped diffraction patterns.
max_frequency (float, optional) – The maximum included spatial frequency in the cropped diffraction patterns.
gpts (tuple of int) – The number of gpts in the cropped diffraction patterns.

Returns:

cropped_diffraction_patterns – The cropped diffraction pattern(s).

Return type:

property extent: tuple[float, float]#

property fftshift: bool#: True if the zero-frequency is shifted to the center of the array.

classmethod from_array_and_metadata(...) → Self[source]#

Creates diffraction pattern(s) from a given array and metadata.

Parameters:

array (array) – Complex array defining one or more 2D diffraction patterns. The second-to-last and last dimensions are the diffraction pattern y- and x-axis.
axes_metadata (list of AxesMetadata) – Axis metadata for each axis. The axis metadata must be compatible with the shape of the array. The last two axes must be RealSpaceAxis.
metadata (dict) – A dictionary defining the measurement metadata.

Returns:

diffraction_patterns – Diffraction pattern(s) from the array and metadata.

Return type:

IndexedDiffractionPatterns

gaussian_source_size(...) → DiffractionPatterns[source]#

Simulate the effect of a finite source size on diffraction pattern(s) using a Gaussian filter.

The filter is not applied to diffraction pattern individually, but the intensity of diffraction patterns are mixed across scan axes. Applying this filter requires two linear scan axes.

Applying this filter before integrating the diffraction patterns will produce the same image as integrating the diffraction patterns first then applying a Gaussian filter.

Parameters:: sigma (float or two float) – Standard deviation of Gaussian kernel in the x and y-direction. If given as a single number, the standard deviation is equal for both axes.
Returns:: filtered_diffraction_patterns – The filtered diffraction pattern(s).
Return type:: DiffractionPatterns

index_diffraction_spots(...) → IndexedDiffractionPatterns[source]#

Indexes the Bragg reflections (diffraction spots) by their Miller indices.

Parameters:

cell (ase.cell.Cell or float or tuple of float) – The assumed unit cell with respect to the diffraction pattern should be indexed. Must be one of ASE Cell object, float (for a cubic unit cell) or three floats (for orthorhombic unit cells).
orientation_matrices (ndarray, optional) – Orientation matrices used for indexing the diffraction spots. The shape of the orientation matrices must be broadcastable with the ensemble shape of the diffraction patterns.
sg_max (float, optional) – Maximum excitation error [1/Å] of the indexed diffraction spots. The default is estimated from the energy and g_max.
g_max (float, optional) – Maximum scattering vector [1/Å] of the indexed diffraction spots. The default is the maximum frequency of the diffraction patterns.
radius (float, optional) – Integration Radius of the diffraction spots [1/Å]. The default is the reciprocal-space sampling of the diffraction patterns.
centering ({'P', 'F', 'I', 'A', 'B', 'C'}) – Assumed lattice centering used for determining the reflection conditions.
energy (float, optional) – The energy of the electrons [keV]. The default is the energy stored in the metadata.

Returns:

indexed_patterns – The indexed diffraction pattern(s).

Return type:

integrate_radial(...) → Images[source]#

Create images by integrating the diffraction patterns over an annulus defined by an inner and outer integration angle.

Parameters:

inner (float) – Inner integration limit [mrad].
outer (float) – Outer integration limit [mrad].
offset (tuple of float) – Offset of center of annular integration region [mrad].

Returns:

integrated_images – The integrated images.

Return type:

integrated_center_of_mass() → Images[source]#

Calculate integrated center-of-mass (iCOM) images from diffraction patterns. This method is only implemented for diffraction patterns with exactly two scan axes.

Returns:: icom_images – The iCOM images.
Return type:: Images

interpolate(...)[source]#

Interpolate diffraction pattern(s) producing equivalent pattern(s) with a different sampling.

Parameters:

sampling ('uniform' or float or two floats) – Sampling of diffraction patterns after interpolation in x and y [1 / Å]. If a single value, the same sampling is used for both axes. If ‘uniform’, the diffraction patterns are down-sampled along the axis with the smallest pixel size such that the sampling is uniform.
gpts (tuple of int) – Number of grid points of the diffraction patterns after interpolation in x and y. Do not use if ‘sampling’ is used.

Returns:

interpolated_diffraction_patterns – The interpolated diffraction pattern(s).

Return type:

property limits: list[tuple[float, float]]#: Lowest and highest spatial frequency in x and y [1 / Å].

lorentzian_source_size(...) → DiffractionPatterns[source]#

Simulate the effect of a finite source size on diffraction pattern(s) using a Lorentzian (Cauchy) filter.

The filter mixes intensities across scan axes (not within each diffraction pattern) and requires two linear scan axes. Applying this filter before integrating gives the same result as integrating first and then applying a lorentzian_filter() to the resulting images.

Parameters:

half_width (float or two float) – Half-width at half-maximum (HWHM) of the Lorentzian kernel in the x and y-direction [Å]. If given as a single number it is equal for both axes.
truncate (float, optional) – Truncate the kernel at this many half-widths (default is 10.0).

Returns:

filtered_diffraction_patterns – The filtered diffraction pattern(s).

Return type:

Notes

The Lorentzian kernel is parameterized by its HWHM γ (half_width), with FWHM_L = 2γ. This differs from gaussian_source_size(), which uses the standard deviation σ (FWHM_G ≈ 2.3548·σ).

property max_angles: tuple[float, float]#: Maximum scattering angle in x and y [mrad].

property max_frequency#: Maximum spatial frequency in x and y [1 / Å].

property offset: tuple[float, float]#

poisson_noise(...)[source]#

Add Poisson noise (i.e. shot noise) to a measurement corresponding to the provided total_dose (per measurement if applied to an ensemble) or dose_per_area (not applicable for single measurements).

Parameters:

dose_per_area (float, optional) – The irradiation dose per unit of scan area [electrons per Å:sup:2]. This is only valid if the diffraction patterns has two scan axes.
total_dose (float, optional) – The irradiation dose per diffraction pattern.
samples (int, optional) – The number of samples to draw from a Poisson distribution. If this is greater than 1, an additional ensemble axis will be added to the measurement.
seed (int, optional) – Seed the random number generator.

Returns:

noisy_measurement – The noisy measurement.

Return type:

BaseMeasurements

polar_binning(...)[source]#

Create polar measurements from the diffraction patterns by binning the measurements on a polar grid. This method may be used to simulate a segmented detector with a specified number of radial and azimuthal bins.

Each bin is a segment of an annulus and the bins are spaced equally in the radial and azimuthal directions. The bins fit between a given inner and outer integration limit, they may be rotated around the origin, and their center may be shifted from the origin.

Parameters:

nbins_radial (int) – Number of radial bins.
nbins_azimuthal (int) – Number of angular bins.
inner (float) – Inner integration limit of the bins [mrad] (default is 0.0).
outer (float) – Outer integration limit of the bins [mrad]. If not specified, this is set to be the maximum detected angle of the diffraction pattern.
rotation (float) – Rotation of the bins around the origin [mrad] (default is 0.0).
offset (two float) – Offset of the bins from the origin in x and y [mrad]. Default is (0.0, 0.0).

Returns:

polar_measurements – The polar measurements.

Return type:

pseudo_voigtian_source_size(...) → DiffractionPatterns[source]#

Simulate the effect of a finite source size on diffraction pattern(s) using a pseudo-Voigtian filter (weighted sum of Gaussian and Lorentzian).

The filter mixes intensities across scan axes (not within each diffraction pattern) and requires two linear scan axes. Applying this filter before integrating gives the same result as integrating first and then applying a pseudo_voigtian_filter() to the resulting images.

Parameters:

gaussian_sigma (float or two float) – Standard deviation (σ) of the Gaussian component [Å]. If given as a single number it is equal for both axes.
lorentzian_gamma (float or two float) – Half-width at half-maximum (HWHM, γ) of the Lorentzian component [Å]. If given as a single number it is equal for both axes.
eta (float) – Lorentzian mixing fraction η ∈ [0, 1]. η = 0 gives a pure Gaussian; η = 1 gives a pure Lorentzian.
truncate (float, optional) – Truncate the kernel at this many effective half-widths (default 10.0).

Returns:

filtered_diffraction_patterns – The filtered diffraction pattern(s).

Return type:

Notes

The pseudo-Voigt profile is PV = (1-η)·G + η·L, where G and L are Gaussian and Lorentzian profiles with widths σ and γ respectively. Width parameterization: FWHM_G = 2√(2 ln 2)·σ ≈ 2.3548·σ; FWHM_L = 2γ.

radial_binning(...) → PolarMeasurements[source]#

Create polar measurement(s) from the diffraction pattern(s) by binning the measurements in annular regions. This method may be used to simulate a segmented detector with a specified number of radial bins.

This is equivalent to detecting a wave function using the FlexibleAnnularDetector.

Parameters:

step_size (float, optional) – Radial extent of the bins [mrad]. Default is 1.0.
inner (float, optional) – Inner integration limit of the bins [mrad]. Default is 0.0.
outer (float, optional) – Outer integration limit of the bins [mrad]. If not specified, this is set to be the maximum detected angle of the diffraction pattern.

Returns:

radially_binned_measurement – Radially binned polar measurement(s).

Return type:

property sampling: tuple[float, float]#: Sampling of diffraction patterns in x and y [1 / Å].

tile_scan(...) → DiffractionPatterns[source]#

Tile the scan axes of the diffraction patterns. The diffraction patterns must have one or more scan axes.

Parameters:: repetitions (two int) – The number of repetitions of the scan positions along the x- and y-axis.
Returns:: tiled_diffraction_patterns – The tiled diffraction patterns.
Return type:: DiffractionPatterns

voigtian_source_size(...) → DiffractionPatterns[source]#

Simulate the effect of a finite source size on diffraction pattern(s) using a Voigt filter (convolution of Gaussian and Lorentzian).

The filter mixes intensities across scan axes (not within each diffraction pattern) and requires two linear scan axes. Applying this filter before integrating gives the same result as integrating first and then applying a voigtian_filter() to the resulting images.

Parameters:

gaussian_sigma (float or two float) – Standard deviation (σ) of the Gaussian component [Å]. If given as a single number it is equal for both axes.
lorentzian_gamma (float or two float) – Half-width at half-maximum (HWHM, γ) of the Lorentzian component [Å]. If given as a single number it is equal for both axes.
truncate (float, optional) – Truncate the Lorentzian component at this many half-widths (default 10.0). The Gaussian component uses the SciPy default (4·σ).

Returns:

filtered_diffraction_patterns – The filtered diffraction pattern(s).

Return type:

Notes

The Voigt profile combines two width parameters:

gaussian_sigma (σ): standard deviation of the Gaussian component, FWHM_G = 2√(2 ln 2)·σ ≈ 2.3548·σ.
lorentzian_gamma (γ): HWHM of the Lorentzian component, FWHM_L = 2γ.

For the same FWHM, γ = FWHM / 2 but σ = FWHM / (2√(2 ln 2)) ≈ FWHM / 2.3548.

class abtem.measurements.Images(...)[source]#

Bases: abtem.measurements._BaseMeasurement2D

A collection of 2D measurements such as HRTEM or STEM-ADF images. May be used to represent a reconstructed phase.

Parameters:

array (ndarray) – 2D or greater array containing data of type float or complex. The second-to-last and last dimensions are the image y- and x-axis, respectively.
sampling (two float) – Lateral sampling of images in x and y [Å].
ensemble_axes_metadata (list of AxisMetadata, optional) – List of metadata associated with the ensemble axes. The length and item order must match the ensemble axes.
metadata (dict, optional) – A dictionary defining measurement metadata.

Initialization

property base_axes_metadata: list[AxisMetadata]#

property coordinates: tuple[ndarray, ndarray]#: Coordinates of pixels in x and y [Å].

crop(...)[source]#

Crop images to a smaller extent.

Parameters:

extent (tuple of float) – Extent of rectangular cropping region in x and y [Å].
offset (tuple of float) – Lower corner of cropping region in x and y [Å] (default is (0,0)).

Returns:

cropped_images – The cropped images.

Return type:

diffractograms() → DiffractionPatterns[source]#

Calculate diffractograms (i.e. power spectra) from image(s).

Returns:: diffractograms – Diffractograms of image(s).
Return type:: DiffractionPatterns

property extent: tuple[float, float]#

classmethod from_array_and_metadata(...) → Images[source]#

Creates an image from a given array and metadata.

Parameters:

array (array) – Complex array defining one or more 2D wave functions. The second-to-last and last dimensions are the y- and x-axis.
axes_metadata (list of AxesMetadata) – Axis metadata for each axis. The axis metadata must be compatible with the shape of the array. The last two axes must be RealSpaceAxis.
metadata (dict) – A dictionary defining the measurement metadata.

Returns:

images – Images from the array and metadata.

Return type:

integrate_disc(...) → float[source]#

Integrate the values of the images on a disc-shaped region.

Parameters:

position (two floats) – Center of disc-shaped integration region [Å].
radius (float) – Radius of disc-shaped integration region [Å].

Returns:

Integral value.

Return type:

float

integrate_gradient()[source]#

Calculate integrated gradients. Requires complex images whose real and imaginary parts represent the x and y components of a gradient.

Returns:: integrated_gradient – The integrated gradient.
Return type:: Images

interpolate(...) → Images[source]#

Interpolate images producing equivalent images with a different sampling. Either ‘sampling’ or ‘gpts’ must be provided (but not both).

Parameters:

sampling (float or two float) – Sampling of images after interpolation in x and y [Å].
gpts (int or two int) – Number of grid points of images after interpolation in x and y. Do not use if ‘sampling’ is used.
method ({'fft', 'spline'}) –
The interpolation method.

fft :
Interpolate by cropping or zero-padding in reciprocal space. This method should be preferred for periodic images.

spline :
Interpolate using spline interpolation. This method should be preferred for non-periodic images.
boundary ({'periodic', 'reflect', 'constant'}) –
The boundary parameter determines how the input array is extended beyond its boundaries for spline interpolation.

periodic :
The images are extended by wrapping around to the opposite edge. Use this mode for periodic images (default).

reflect :
The images are extended by reflecting about the edge of the last pixel.

constant :
The images are extended by filling all values beyond the edge with the same constant value, defined by the ‘cval’ parameter.
order (int) – The order of the spline interpolation (default is 3). The order has to be in the range 0-5.
normalization ({'values', 'amplitude'}) –
The normalization parameter determines which quantity is preserved after normalization.

values :
The pixel-wise values of the images are preserved.

intensity :
The total intensity of the images is preserved.
cval (scalar, optional) – Value to fill past edges in spline interpolation input if boundary is ‘constant’ (default is 0.0).

Returns:

interpolated_images – The interpolated images.

Return type:

property offset: tuple[float, float]#

property sampling: tuple[float, float]#

scan_noise(...)[source]#

Apply scan noise to images.

Parameters:

dwell_time (float) – Dwell time of the beam [s].
flyback_time (float) – Flyback time of the beam [s].
rms_power (float) – RMS power of the scan noise [V].
max_frequency (float) – Maximum frequency of the scan noise [1/Å].

tile(...) → Images[source]#

Tile image(s).

Parameters:: repetitions (tuple of int) – The number of repetitions of the images along the x- and y-axis, respectively.
Returns:: tiled_images – The tiled image(s).
Return type:: Images

class abtem.measurements.IndexedDiffractionPatterns(...)[source]#

IndexedDiffractionPatterns

Diffraction patterns indexed by their Miller indices.

Parameters:

array (ndarray) – 1D or greater array of type float or complex. The last axis represents the diffraction spots and should have the same length as the number of miller indices, any preceding axis represents an ensemble axis.
miller_indices (ndarray) – The miller indices of the diffraction spots as an N x 3 array where N is the number of miller indices. The order of the miller indices must correspond to the array of intensities. The second axis represents each hkl miller index.
reciprocal_lattice_vectors (ndarray) – The reciprocal lattice vectors of the crystal as a 3 x 3 array. The first axis represents miller indices and the order of the items must correspond to the array of intensities. The second axis represents the reciprocal space positions in x, y and z [1/Å].
ensemble_axes_metadata (list of AxisMetadata, optional) – List of metadata associated with the ensemble axes. The length and item order must match the ensemble axes.
metadata (dict, optional) – A dictionary defining measurement metadata.

Initialization

property all_positions: ndarray#: Reciprocal space positions of the diffraction spots.

property angular_positions#: Scattering angles of the diffraction spots.

property base_axes_metadata: list[AxisMetadata]#

block_direct()[source]#

Remove the zero-order spot.

Returns:: blocked – The indexed diffraction spots without the zero-order spot.
Return type:: IndexedDiffractionPatterns

crop(...)[source]#

Crop the indexed diffraction patterns such that they only include spots with spatial frequencies (scattering angles) up to a given limit.

Parameters:

max_angle (float, optional) – The maximum included scattering angle in the cropped diffraction patterns.
k_max (float, optional) – The maximum included reciprocal lattice vector in the cropped diffraction spots.

Returns:

cropped – The cropped indexed diffraction spots.

Return type:

property ensemble_shape: tuple#

abstract from_array_and_metadata(...) → BaseMeasurements[source]#

property intensities: ndarray#: Intensities of the diffraction spots.

property intensities_dict: dict[tuple, ndarray]#: A dictionary mapping miller indices to intensities.

max_reciprocal_space_vector_length()[source]#

property miller_indices: ndarray#: Miller indices of the diffraction spots.

normalize_to_spot(...)[source]#

Normalize the intensity of the diffraction spots.

Parameters:: spot (tuple of three int) – The intensities will be normalized with respect to the intensity of this spot. Defaults to the most intense spot.
Returns:: normalized_indexed_diffraction_patterns
Return type:: IndexedDiffractionPatterns

property positions: ndarray#: Reciprocal space positions of the diffraction spots.

property positions_dict: dict[tuple, ndarray]#: A dictionary mapping miller indices to reciprocal space positions [1/Å].

property reciprocal_lattice_vectors: ndarray#: Reciprocal lattice vectors of the diffraction spots.

remove_low_intensity(...)[source]#

Remove diffraction spots with intensity below a threshold for all ensemble dimensions.

Parameters:: threshold (float) – Intensity threshold for removing diffraction spots.
Returns:: thresholded_spots – The indexed diffraction spots with an intensity above the given threshold.
Return type:: IndexedDiffractionPatterns

show(...)[source]#

Show the diffraction spots as an EllipseCollection using matplotlib.

Parameters:

ax (matplotlib.axes.Axes, optional) – If given the plots are added to the axis. This is not available for exploded plots.
cbar (bool, optional) – Add colorbar(s) to the image(s). The size and padding of the colorbars may be adjusted using the set_cbar_size and set_cbar_padding methods.
cmap (str, optional) – Matplotlib colormap name used to map scalar data to colors. If the measurement is complex the colormap must be one of ‘hsv’ or ‘hsluv’.
vmin (float, optional) – Minimum of the intensity color scale. Default is the minimum of the array values.
vmax (float, optional) – Maximum of the intensity color scale. Default is the maximum of the array values.
power (float) – Show diffraction spots intensities on a power scale. Cannot be used together with logscale.
logscale (bool) – If True, show diffraction spots on a logarithmic intensity scale. Cannot be used together with power != 1.0.
common_color_scale (bool, optional) – If True all images in an image grid are shown on the same colorscale, and a single colorbar is created (if it is requested). Default is False.
scale (float, optional) – Scale the radii of the circles representing the diffraction spots.
explode (bool or sequence of bool, optional) – If True, a grid of plots is created for all the items of the last two ensemble axes. If False, the first ensemble item is shown. May be given as a sequence of axis indices to create a grid of plots from the specified axes. The default is determined by the axis metadata.
overlay (bool or sequence of int, optional) – If True, all line profiles in the ensemble are shown in a single plot. If False, only the first ensemble item is shown. May be given as a sequence of axis indices to specify which line profiles in the ensemble to show together. The default is determined by the axis metadata.
figsize (two int, optional) – The figure size given as width and height in inches, passed to matplotlib.pyplot.figure.
title (bool or str, optional) – Set the column title of the plots. If True is given instead of a string the title will be given by the value corresponding to the “name” key of the axes metadata dictionary, if this item exists.
units (str) – The units used for the x and y axes. The given units must be compatible with the axes of the plots.
interact (bool) – If True, create an interactive visualization. This requires enabling the ipympl Matplotlib backend.
display (bool, optional) – If True (default) the figure is displayed immediately.

Returns:

visualization

Return type:

Visualization

sort(...)[source]#

Sort the diffraction spots according to a given criterion.

Parameters:

criterion ({'distance', 'intensity'}) –

The boundary parameter determines how the images are extended beyond their boundaries when the filter overlaps with a border.

distance :
Sort according to the distance in reciprocal space from the zero frequency.

intensity :
Sort according to the intensity of the diffraction spots.

Returns:

sorted_spots – The indexed diffraction spots sorted according to the given criterion.

Return type:

IndexedDiffractionPatterns

to_data_array()[source]#

Convert the indexed diffraction patterns to xarray DataArray.

Returns:: data_array_of_indexed_spots
Return type:: xarray.DataArray

to_dataframe()[source]#

Convert the indexed diffraction patterns to pandas DataFrame.

Returns:: data_frame
Return type:: pd.DataFrame

class abtem.measurements.MeasurementsEnsemble(...)[source]#

property base_axes_metadata#

classmethod from_array_and_metadata(...) → abtem.measurements.BaseMeasurementsSubclass[source]#

show(...) → Visualization[source]#

Show the image(s) using matplotlib.

Parameters:

ax (matplotlib.axes.Axes, optional) – If given the plots are added to the axis. This is not available for exploded plots.
power (float) – Show image on a power scale.
explode (bool, optional) – If True, a grid of images is created for all the items of the last two ensemble axes. If False, the first ensemble item is shown. May be given as a sequence of axis indices to create a grid of images from the specified axes. The default is determined by the axis metadata.
overlay (bool or sequence of int, optional) – If True, all line profiles in the ensemble are shown in a single plot. If False, only the first ensemble item is shown. May be given as a sequence of axis indices to specify which line profiles in the ensemble to show together. The default is determined by the axis metadata.
figsize (two int, optional) – The figure size given as width and height in inches, passed to matplotlib.pyplot.figure.
title (bool or str, optional) – Set the column title of the images. If True is given instead of a string the title will be given by the value corresponding to the “name” key of the axes metadata dictionary, if this item exists.
units (str) – The units used for the x and y axes. The given units must be compatible with the axes of the images.
interact (bool) – If True, create an interactive visualization. This requires enabling the ipympl Matplotlib backend.
display (bool, optional) – If True (default) the figure is displayed immediately.

Returns:

measurement_visualization_2d

Return type:

VisualizationImshow

class abtem.measurements.MomentumResolvedSpectrum(...)[source]#

MomentumResolvedSpectrum

Momentum-resolved energy-loss spectrum S(q, E).

Stores a 2D intensity array whose last two dimensions correspond to scattering-vector bins (q) and energy bins (E). Additional leading dimensions are ensemble axes.

Use crop() to restrict the q/energy-loss range before plotting with show() – besides zooming in, this also rescales the colour scale (and, for an exploded grid, every panel’s shared colour scale) to the cropped region instead of the full data.

Parameters:

array (ndarray or dask array) – Array of shape (..., n_q, n_E).
q_values (sequence of float) – Scattering-vector values [mrad] for each q bin.
e_values (sequence of float) – Energy-loss values [eV] for each energy bin.
ensemble_axes_metadata (list of AxisMetadata, optional)
metadata (dict, optional)

Initialization

property base_axes_metadata: list[AxisMetadata]#

crop(...) → MomentumResolvedSpectrum[source]#

Crop the spectrum to a q and/or energy-loss range.

Parameters:

q_range (tuple of float, optional) – Inclusive (min, max) scattering-vector range [mrad] to keep. If None (default), the full q range is kept.
e_range (tuple of float, optional) – Inclusive (min, max) energy-loss range [eV] to keep – note this is in eV (the unit e_values is stored in) regardless of the e_units display option of show(). If None (default), the full energy range is kept.

Returns:

cropped – The cropped spectrum.

Return type:

property e_values: tuple[float, ...]#: Energy-loss values [eV].

classmethod from_array_and_metadata(...) → MomentumResolvedSpectrum[source]#

property q_values: tuple[float, ...]#: Scattering-vector values [mrad].

show(...) → tuple[source]#

Show the spectrum as a 2D heatmap with q on the x-axis and energy on the y-axis.

Unlike other abTEM measurements this method plots directly with matplotlib (the q and energy axes are non-linear, so the shared Visualization imshow machinery does not apply) and therefore returns the raw matplotlib objects rather than a Visualization.

Parameters:

ax (matplotlib Axes, optional) – Only used for the single-panel case (ignored when exploding).
cbar (bool) – Show colorbar. Default True.
cmap (str, optional) – Colormap name. Default ‘viridis’.
vmin (float, optional) – Colour-scale limits. When exploding, a value left as None is filled from the global min/max across all panels so the shared colorbar is meaningful.
vmax (float, optional) – Colour-scale limits. When exploding, a value left as None is filled from the global min/max across all panels so the shared colorbar is meaningful.
power (float) – Display on a power scale.
explode (bool or sequence of int) – If True, explode all ensemble axes into a panel grid. If a sequence of ints, explode only those ensemble-axis indices (the remaining ensemble axes collapse to their first element). If falsy (default), a single panel is shown.
figsize ((width, height), optional)
title (bool or str) – If a string, used as the (base) title. If True, a default title is generated. If False, no title is set.
e_units (str) – Units for the energy axis (‘meV’ or ‘eV’). Default ‘meV’.
kwargs – Forwarded to matplotlib.axes.Axes.pcolormesh().

Returns:

fig, ax – (exploded grid).

Return type:

matplotlib Figure and Axes (single panel) or ndarray of Axes

class abtem.measurements.PolarMeasurements(...)[source]#

Class describing polar measurements with a specified number of radial and azimuthal bins.

Each bin is a segment of an annulus and the bins are spaced equally in the radial and azimuthal directions. The bins may be rotated around the origin, and their center may be shifted from the origin.

Parameters:

array (ndarray) – Array containing the measurement.
radial_sampling (float) – Sampling of the radial bins [mrad].
azimuthal_sampling (int) – Sampling of the azimuthal bins [rad].
radial_offset (float, optional) – Offset of the bins from the origin [mrad] (default is 0.0).
azimuthal_offset (float, optional) – Rotation of the bins around the origin [rad] (default is 0.0).
ensemble_axes_metadata (list of AxisMetadata, optional) – List of metadata associated with the ensemble axes. The length and item order must match the ensemble axes.
metadata (dict, optional) – A dictionary defining measurement metadata.

Returns:

polar_measurements – The polar measurements.

Return type:

Initialization

property azimuthal_offset: float#: Rotation of the bins around the origin [rad].

property azimuthal_sampling: float#: Sampling of the azimuthal bins [rad].

property base_axes_metadata: list[AxisMetadata]#

differentials(...) → Images[source]#

Calculate the differential signal by subtracting the intensity of specified detector regions.

Parameters:

direction_1 (tuple of int or tuple of tuple of int) – The detector regions used for calculating the differential signal for the first direction. The first item is the detector region(s) contributing to the positive term and the second item is the detector region(s) contributing to the negative terms.
direction_2 (tuple of int or tuple of tuple of int) – The detector regions used for calculating the differential signal for the second direction. The first item is the detector region(s) contributing to the positive term and the second item is the detector region(s) contributing to the negative terms.
return_complex (bool, optional) – If True, return a complex image where the real and imaginary part represents direction_1 and direction_2. If False, return images with an ensemble dimension for the directions.

Returns:

differential_image – The (complex) differential image(s).

Return type:

property extent#

classmethod from_array_and_metadata(...) → PolarMeasurements[source]#

Creates polar measurements(s) from a given array and metadata.

Parameters:

array (array) – Complex array defining one or more polar measurements. The second-to-last and last dimensions are the measurement y- and x-axis.
axes_metadata (list of AxesMetadata) – Axis metadata for each axis. The axis metadata must be compatible with the shape of the array. The last two axes must be RealSpaceAxis.
metadata (dict) – A dictionary defining the measurement metadata.

Returns:

polar_measurements – Polar measurement(s) from the array and metadata.

Return type:

gaussian_source_size(...) → PolarMeasurements[source]#

Simulate the effect of a finite source size on diffraction pattern(s) using a Gaussian filter.

The filter is not applied to diffraction pattern individually, but the intensity of diffraction patterns are mixed across scan axes. Applying this filter requires two linear scan axes.

Applying this filter before integrating the diffraction patterns will produce the same image as integrating the diffraction patterns first then applying a Gaussian filter.

Parameters:: sigma (float or two float) – Standard deviation of Gaussian kernel in the x and y-direction. If given as a single number, the standard deviation is equal for both axes.
Returns:: filtered_diffraction_patterns – The filtered diffraction pattern(s).
Return type:: DiffractionPatterns

integrate(...) → Images | RealSpaceLineProfiles[source]#

Integrate polar regions to produce an image or line profiles.

Parameters:

radial_limits (tuple of float) – Inner and outer radial angles of the integration limits [mrad].
azimuthal_limits (tuple of float) – Lower and upper azimuthal angles of the integration limits [rad].
detector_regions (int or sequence of int) – The explicit detector regions to integrate over.

Returns:

integrated_images

Return type:

Images or RealSpaceLineProfiles

integrate_radial(...) → Images | RealSpaceLineProfiles[source]#

Create images by integrating the polar measurements over an annulus defined by an inner and outer integration angle.

Parameters:

inner (float) – Inner integration limit [mrad].
outer (float) – Outer integration limit [mrad].

Returns:

integrated_images (Images) – The integrated images.
real_space_line_profiles (RealSpaceLineProfiles) – Integrated line profiles (returned if there is only one scan axis).

lorentzian_source_size(...) → PolarMeasurements[source]#

Simulate the effect of a finite source size on polar measurement(s) using a Lorentzian (Cauchy) filter.

The filter mixes intensities across scan axes (not within each measurement) and requires two linear scan axes.

Parameters:

half_width (float or two float) – Half-width at half-maximum (HWHM) of the Lorentzian kernel in the x and y-direction [Å]. If given as a single number it is equal for both axes.
truncate (float, optional) – Truncate the kernel at this many half-widths (default is 10.0).

Returns:

filtered_measurements – The filtered measurement(s).

Return type:

Notes

The Lorentzian kernel is parameterized by its HWHM γ (half_width), with FWHM_L = 2γ. This differs from gaussian_source_size(), which uses the standard deviation σ (FWHM_G ≈ 2.3548·σ).

property offset#

property outer_angle: float#: The outer angle of the outermost radial bin [mrad].

poisson_noise(...)[source]#

Add Poisson noise (i.e. shot noise) to a measurement corresponding to the provided ‘total_dose’ (per measurement if applied to an ensemble) or ‘dose_per_area’ (not applicable for single measurements).

Parameters:

dose_per_area (float, optional) – The irradiation dose per unit of scan area [electrons per Å:sup:2]. This is only valid if the diffraction patterns has two scan axes.
total_dose (float, optional) – The irradiation dose per diffraction pattern.
samples (int, optional) – The number of samples to draw from a Poisson distribution. If this is greater than 1, an additional ensemble axis will be added to the measurement.
seed (int, optional) – Seed the random number generator.

Returns:

noisy_measurement – The noisy measurement.

Return type:

BaseMeasurements

pseudo_voigtian_source_size(...) → PolarMeasurements[source]#

Simulate the effect of a finite source size on polar measurement(s) using a pseudo-Voigtian filter (weighted sum of Gaussian and Lorentzian).

The filter mixes intensities across scan axes (not within each measurement) and requires two linear scan axes.

Parameters:

gaussian_sigma (float or two float) – Standard deviation (σ) of the Gaussian component [Å]. If given as a single number it is equal for both axes.
lorentzian_gamma (float or two float) – Half-width at half-maximum (HWHM, γ) of the Lorentzian component [Å]. If given as a single number it is equal for both axes.
eta (float) – Lorentzian mixing fraction η ∈ [0, 1]. η = 0 gives a pure Gaussian; η = 1 gives a pure Lorentzian.
truncate (float, optional) – Truncate the kernel at this many effective half-widths (default 10.0).

Returns:

filtered_measurements – The filtered measurement(s).

Return type:

Notes

The pseudo-Voigt profile is PV = (1-η)·G + η·L, where G and L are Gaussian and Lorentzian profiles with widths σ and γ respectively. Width parameterization: FWHM_G = 2√(2 ln 2)·σ ≈ 2.3548·σ; FWHM_L = 2γ.

property radial_offset: float#: Offset of the bins from the origin [mrad].

property radial_sampling: float#: Sampling of the radial bins [mrad].

property sampling#

show(...) → Visualization[source]#

Show the polar measurements as an image or a grid of images. The images are shown by discretizing the polar bins on a regular grid.

Parameters:

ax (matplotlib.axes.Axes, optional) – If given the plots are added to the axis. This is not available for exploded plots.
gpts (int or tuple of int, optional) – Number of grid points in the image(s).
cbar (bool, optional) – Add colorbar(s) to the image(s). The size and padding of the colorbars may be adjusted using the set_cbar_size and set_cbar_padding methods.
cmap (str, optional) – Matplotlib colormap name used to map scalar data to colors. If the measurement is complex the colormap must be one of ‘hsv’ or ‘hsluv’.
vmin (float, optional) – Minimum of the intensity color scale. Default is the minimum of the array values.
vmax (float, optional) – Maximum of the intensity color scale. Default is the maximum of the array values.
power (float) – Show image on a power scale. Cannot be used together with logscale.
logscale (bool) – If True, show image on a logarithmic intensity scale. Cannot be used together with power != 1.0.
common_color_scale (bool, optional) – If True all images in an image grid are shown on the same colorscale, and a single colorbar is created (if it is requested). Default is False.
explode (bool, optional) – If True, a grid of images is created for all the items of the last two ensemble axes. If False, the first ensemble item is shown. May be given as a sequence of axis indices to create a grid of images from the specified axes. The default is determined by the axis metadata.
overlay (bool or sequence of int, optional) – If True, all line profiles in the ensemble are shown in a single plot. If False, only the first ensemble item is shown. May be given as a sequence of axis indices to specify which line profiles in the ensemble to show together. The default is determined by the axis metadata.
figsize (two int, optional) – The figure size given as width and height in inches, passed to matplotlib.pyplot.figure.
title (bool or str, optional) – Set the column title of the images. If True is given instead of a string the title will be given by the value corresponding to the “name” key of the axes metadata dictionary, if this item exists.
units (str) – The units used for the x and y axes. The given units must be compatible with the axes of the images.
interact (bool) – If True, create an interactive visualization. This requires enabling the ipympl Matplotlib backend.
display (bool, optional) – If True (default) the figure is displayed immediately.

Returns:

measurement_visualization_2d

Return type:

MeasurementVisualizationImshow

to_diffraction_patterns(...)[source]#

Convert the polar measurements to diffraction patterns by discretizing the polar bins on a regular grid.

Parameters:

gpts (int or two int) – Number of grid points describing the diffraction patterns.
margin (float or two float, optional) – The margin as a fraction of the outer angle of the polar measurements to add to the maximum angle of the diffraction patterns.

Returns:

diffraction_patterns – The diffraction patterns discretized from the polar measurements.

Return type:

to_image_ensemble()[source]#

Convert the polar measurements to an ensemble of images, where the radial and azimuthal angles becomes ensemble axes.

Returns:: image_ensemble
Return type:: Images

voigtian_source_size(...) → PolarMeasurements[source]#

Simulate the effect of a finite source size on polar measurement(s) using a Voigt filter (convolution of Gaussian and Lorentzian).

The filter mixes intensities across scan axes (not within each measurement) and requires two linear scan axes.

Parameters:

gaussian_sigma (float or two float) – Standard deviation (σ) of the Gaussian component [Å]. If given as a single number it is equal for both axes.
lorentzian_gamma (float or two float) – Half-width at half-maximum (HWHM, γ) of the Lorentzian component [Å]. If given as a single number it is equal for both axes.
truncate (float, optional) – Truncate the Lorentzian component at this many half-widths (default 10.0). The Gaussian component uses the SciPy default (4·σ).

Returns:

filtered_measurements – The filtered measurement(s).

Return type:

MomentumResolvedSpectrum

Notes

The Voigt profile combines two width parameters:

gaussian_sigma (σ): standard deviation of the Gaussian component, FWHM_G = 2√(2 ln 2)·σ ≈ 2.3548·σ.
lorentzian_gamma (γ): HWHM of the Lorentzian component, FWHM_L = 2γ.

For the same FWHM, γ = FWHM / 2 but σ = FWHM / (2√(2 ln 2)) ≈ FWHM / 2.3548.

class abtem.measurements.RealSpaceLineProfiles(...)[source]#

Bases: abtem.measurements._BaseMeasurement1D

A collection of real-space line profile(s).

Parameters:

array (ndarray) – 1D or greater array containing data of type float or complex.
sampling (float) – Sampling of line profiles [Å].
ensemble_axes_metadata (list of AxisMetadata, optional) – List of metadata associated with the ensemble axes. The length and item order must match the ensemble axes.
metadata (dict, optional) – A dictionary defining measurement metadata.

Initialization

property base_axes_metadata: list[RealSpaceAxis]#

tile(...) → RealSpaceLineProfiles[source]#

Tile line profiles(s).

Parameters:: repetitions (int) – The number of repetitions of the line profiles.
Returns:: tiled_line_profiles – The tiled line profiles(s).
Return type:: RealSpaceLineProfiles

class abtem.measurements.ReciprocalSpaceLineProfiles(...)[source]#

Bases: abtem.measurements._BaseMeasurement1D

A collection of reciprocal-space line profile(s).

Parameters:

array (ndarray) – 1D or greater array containing data of type float or complex.
sampling (float) – Sampling of line profiles [1 / Å].
ensemble_axes_metadata (list of AxisMetadata, optional) – List of metadata associated with the ensemble axes. The length and item order must match the ensemble axes.
metadata (dict, optional) – A dictionary defining measurement metadata.

Initialization

property angular_extent#: Extent of line profiles given as scattering angels [mrad].

property base_axes_metadata: list[AxisMetadata]#

abtem.measurements.calculate_max_reciprocal_space_vector(...)[source]#

abtem.measurements.integrate_disc(...) → float[source]#

Integrate the values of a 2d measurement on a disc-shaped region.

Parameters:

measurement (2d measurement) – The measurement to integrate
position (two floats) – Center of disc-shaped integration region
radius (float) – Radius of disc-shaped integration region
return_mean (bool) – If true return the mean, otherwise return the sum.
border (str) –
Specify how to treat integration regions that cross the image border. The valid values and their behaviours are:

’wrap’
The measurement is extended by wrapping around to the opposite edge.

’raise’
Raise an error if the integration region crosses the measurement border.
interpolate (float or False) – The image will be interpolated to this sampling. Units of Angstrom.

Returns:

Integral value

Return type:

float

abtem.measurements.interpolate_bilinear_cuda: Optional[Callable]#: None

abtem.measurements.momentum_resolved_spectrum(...) → MomentumResolvedSpectrum[source]#

Build S(q, E) from energy-resolved TDS diffraction patterns.

Dispatches on the type of detector:

SpectralAnnularDetector — sweeps an offset circular acceptance disk (acceptance radius outer, inner always 0) along a radial direction at each q-step. The q-axis runs from q_min to q_max in steps of outer (one disk-radius per step).
SpectralSlitDetector — uses DiffractionPatterns.interpolate_line() (spline interpolation) to integrate strips along the slit’s long axis. Samples directly from q_min to q_max (default q_min=0 includes the direct beam). The integration aperture perpendicular to q has full width width (= 2 * outer of an equivalent annular detector).

Both detector types share the same q_min / q_max convention — the same numerical values yield the same q-range in the output spectrum:

SpectralAnnularDetector(outer=r, q_min=Q0, q_max=Q)
SpectralSlitDetector(q_min=Q0, q_max=Q, width=2*r)

Parameters:

tds_diffraction_patterns (DiffractionPatterns) – Energy-resolved TDS diffraction patterns as returned by phonon_loss_diffraction_patterns(). Must have an EnergyLossAxis in its ensemble axes.
detector (SpectralAnnularDetector or SpectralSlitDetector) – Detector that controls the integration strategy and q-range.

Return type:

abtem.measurements.pd: Optional[ModuleType]#: None

abtem.measurements.periodic_crop(...) → ndarray[source]#

Crop an array with periodic boundary conditions. The cropping region is wrapped around the array.

Parameters:

array (ndarray) – The array to crop.
corner (two floats) – The corner of the cropping region.
new_shape (two ints) – The shape of the cropping region.

Returns:

cropped_array – The cropped array.

Return type:

ndarray

abtem.measurements.phonon_loss_diffraction_patterns(...) → DiffractionPatterns[source]#

Compute inelastic (TDS) diffraction patterns from energy-resolved frozen-phonon exit waves.

The thermal diffuse scattering signal is obtained per energy bin as:

I_coherent   = |FT(Σ_j psi_j)|² / N²   (elastic)
I_incoherent = Σ_j |FT(psi_j)|² / N     (total)
I_tds        = I_incoherent - I_coherent  (inelastic / phonon loss)

The returned DiffractionPatterns retain the EnergyLossAxis but the FrozenPhononsAxis is collapsed. Apply an offset AnnularDetector or SlitDetector to integrate over desired q points.

Note that I_tds is the variance of the diffracted amplitude across frozen-phonon configurations: with a single configuration per energy, I_incoherent and I_coherent are identical by construction and I_tds is exactly zero everywhere, not a numerical artifact. At least 2 configurations per energy are required for component="tds"/"all" (this is enforced with a ValueError); in practice many more are needed for good statistics.

Parameters:

exit_waves (Waves) – Complex exit waves from a multislice simulation with an EnergyResolvedAtomsEnsemble (ensemble_mean=False). Must contain both a FrozenPhononsAxis and an EnergyLossAxis in its ensemble axes. If the potential used more than one slice, prefer building it with projection="finite" — see the EnergyResolvedAtomsEnsemble notes on slice-boundary artifacts with out-of-plane displacement.
component ({'tds', 'coherent', 'incoherent', 'all'}) – Which component to return. 'all' stacks the three along a new leading OrdinalAxis(label='component').
max_angle (str or float) – Passed to Waves.diffraction_patterns.
parity (str) – Passed to Waves.diffraction_patterns.
block_direct (bool or float, optional) – If True, the direct beam is blocked in the resulting diffraction patterns. If given as a float, masks up to that scattering angle [mrad]. Default is False.
temperature (float, optional) – Sample temperature [K]. If given, unfolds the TDS signal — computed from a single frozen-phonon run per energy magnitude — into signed quantum loss (+E) and gain (-E) sides using Bose-Einstein detailed balance, following P. Zeiger’s approach. Requires component="tds" and an EnergyLossAxis whose values start at 0 and strictly increase (the classical/incoherent-minus-coherent signal is symmetric in loss/gain; only their split is a quantum effect). The zero-energy bin is unweighted. Default is None (no unfolding — the returned energies are the ones in exit_waves).

Returns:

Intensity patterns with the FrozenPhononsAxis removed and the EnergyLossAxis preserved (or replaced by its signed loss/gain unfolding if temperature is given).

Return type: