IndexedDiffractionPatterns#

class abtem.measurements.IndexedDiffractionPatterns(array, miller_indices, positions, ensemble_axes_metadata=None, metadata=None)[source]#

Bases: abtem.measurements.BaseMeasurements

Diffraction patterns indexed by their Miller indices.

Parameters

array (np.ndarray) – 1D or greater array of type float. 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 (np.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.
positions (np.ndarray) – The reciprocal space coordinates of the diffraction spots as an N 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.

__init__(array, miller_indices, positions, ensemble_axes_metadata=None, metadata=None)[source]#

Methods

`__init__`(array, miller_indices, positions[, ...])
`abs`()	Calculates the absolute value of a complex-valued measurement.
`apply_transform`(transform[, max_batch])	Transform the wave functions by a given transformation.
`block_direct`()	Remove the zero-order spot.
`compute`([progress_bar, profiler, ...])	Turn a lazy abTEM object into its in-memory equivalent.
`copy`()	Make a copy.
`copy_to_device`(device)	Copy array to specified device.
`crop`([max_angle, max_frequency])	Crop the indexed diffraction patterns such that they only include spots with spatial frequencies (scattering angles) up to a given limit.
`ensemble_blocks`([chunks])	Split the ensemble into an array of smaller ensembles.
`ensure_lazy`([chunks])	Creates an equivalent lazy version of the array object.
`expand_dims`([axis, axis_metadata])	Expand the shape of the array object.
`from_array_and_metadata`(array, ...)	Creates array object from a given array and metadata.
`from_zarr`(url[, chunks])	Read wave functions from a hdf5 file.
`generate_blocks`([chunks])	Generate chunks of the ensemble.
`generate_ensemble`([keepdims])	Generate every member of the ensemble.
`get_items`(items[, keepdims])	Index the array and the corresponding axes metadata.
`imag`()	Returns the imaginary part of a complex-valued measurement.
`intensity`()	Calculates the squared norm of a complex-valued measurement.
`max`([axis, keepdims, split_every])	Maximum of array object over one or more axes.
`mean`([axis, keepdims, split_every])	Mean of array object over one or more axes.
`min`([axis, keepdims, split_every])	Minmimum of array object over one or more axes.
`no_base_chunks`()	Rechunk to remove chunks across the base dimensions.
`normalize_ensemble`([scale, shift])	Normalize the ensemble by shifting ad scaling each member.
`normalize_to_spot`([spot])	Normalize the intensity of the diffraction spots.
`phase`()	Calculates the phase of a complex-valued measurement.
`poisson_noise`([dose_per_area, total_dose, ...])	Add Poisson noise (i.e.
`real`()	Returns the real part of a complex-valued measurement.
`rechunk`(chunks, **kwargs)	Rechunk dask array.
`reduce_ensemble`()	Calculates the mean of an ensemble measurement (e.g.
`relative_difference`(other[, min_relative_tol])	Calculates the relative difference with respect to another compatible measurement.
`remove_low_intensity`([threshold])	Remove diffraction spots with intensity below a threshold for all ensemble dimensions.
`select_block`(index, chunks)	Select a block from the ensemble.
`set_ensemble_axes_metadata`(axes_metadata, axis)	Sets the axes metadata of an ensemble axis.
`show`([ax, cbar, cmap, vmin, vmax, power, ...])	Show the diffraction spots using matplotlib.
`sort`([criterion])	Sort the diffraction spots according to a given criterion.
`squeeze`([axis])	Remove axes of length one from array object.
`std`([axis, keepdims, split_every])	Standard deviation of array object over one or more axes.
`sum`([axis, keepdims, split_every])	Sum of array object over one or more axes.
`to_cpu`()	Move the array to the host memory from an arbitrary source array.
`to_data_array`()	Convert the indexed diffraction patterns to xarray DataArray.
`to_dataframe`()	Convert the indexed diffraction patterns to pandas DataFrame.
`to_gpu`([device])	Move the array from the host memory to a gpu.
`to_hyperspy`()	Convert measurement to a Hyperspy signal.
`to_tiff`(filename, **kwargs)	Write data to a tiff file.
`to_zarr`(url[, compute, overwrite])	Write data to a zarr file.

Attributes

`angular_positions`	Scattering angles of the diffraction spots.
`array`	Underlying array describing the array object.
`axes_metadata`	List of AxisMetadata.
`base_axes_metadata`	List of AxisMetadata of the base axes.
`base_dims`	Number of base dimensions.
`base_shape`	Shape of the base axes of the underlying array.
`device`	The device where the array is stored.
`dtype`	Datatype of array.
`ensemble_axes_metadata`	List of AxisMetadata of the ensemble axes.
`ensemble_dims`	Number of ensemble dimensions.
`ensemble_shape`	Shape of the ensemble axes of the underlying array.
`intensities`	Intensities of the diffraction spots.
`intensities_dict`	A dictionary mapping miller indices to intensities.
`is_complex`	True if array is complex.
`is_lazy`	True if array is lazy.
`metadata`	Metadata describing the measurement.
`miller_indices`	Miller indices of the diffraction spots.
`positions`	Reciprocal space positions of the diffraction spots.
`positions_dict`	A dictionary mapping miller indices to reciprocal space positions [1/Å].
`shape`	Shape of the underlying array.

abs()#

Calculates the absolute value of a complex-valued measurement.

Return type: TypeVar(T, bound= BaseMeasurement)

property angular_positions#: Scattering angles of the diffraction spots.

apply_transform(transform, max_batch='auto')#

Transform the wave functions by a given transformation.

Parameters

transform (ArrayObjectTransform) – The array object transformation to apply.
max_batch (int, optional) – The number of wave functions in each chunk of the Dask array. If ‘auto’ (default), the batch size is automatically chosen based on the abtem user configuration settings “dask.chunk-size” and “dask.chunk-size-gpu”.

Returns

transformed_array_object – The transformed array object.

Return type

ArrayObjectTransform

property array: np.ndarray | da.core.Array#

Underlying array describing the array object.

Return type: np.ndarray | da.core.Array

property axes_metadata: abtem.core.axes.AxesMetadataList#

List of AxisMetadata.

Return type: AxesMetadataList

property base_axes_metadata: list#

List of AxisMetadata of the base axes.

Return type: list

property base_dims#: Number of base dimensions.

property base_shape: tuple[int, ...]#

Shape of the base axes of the underlying array.

Return type: tuple[int, ...]

block_direct()[source]#

Remove the zero-order spot.

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

compute(progress_bar=None, profiler=False, resource_profiler=False, **kwargs)#

Turn a lazy abTEM object into its in-memory equivalent.

Parameters

progress_bar (bool) – Display a progress bar in the terminal or notebook during computation. The progress bar is only displayed with a local scheduler.
profiler (bool) – Return Profiler class used to profile Dask’s execution at the task level. Only execution with a local is profiled.
resource_profiler (bool) – Return ResourceProfiler class is used to profile Dask’s execution at the resource level.
kwargs – Additional keyword arguments passes to dask.compute.

copy()#: Make a copy.

copy_to_device(device)#

Copy array to specified device.

Parameters: device (str) –
Returns: object_on_device
Return type: T

crop(max_angle=None, max_frequency=None)[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.
max_frequency (float, optional) – The maximum included spatial frequency in the cropped diffraction patterns.

Returns

cropped

Return type

IndexedDiffractionPatterns

property device: str#

The device where the array is stored.

Return type: str

property dtype#: Datatype of array.

property ensemble_axes_metadata#: List of AxisMetadata of the ensemble axes.

ensemble_blocks(chunks=None)#

Split the ensemble into an array of smaller ensembles.

Parameters: chunks (iterable of tuples) – Block sizes along each dimension.
Return type: Array

property ensemble_dims#: Number of ensemble dimensions.

property ensemble_shape: tuple#

Shape of the ensemble axes of the underlying array.

Return type: tuple

ensure_lazy(chunks='auto')#

Creates an equivalent lazy version of the array object.

Parameters: chunks (int or tuple or str) – How to chunk the array. See dask.array.from_array.
Returns: lazy_array_object – Lazy version of the array object.
Return type: ArrayObject or subclass of ArrayObject

expand_dims(axis=None, axis_metadata=None)#

Expand the shape of the array object.

Parameters

axis (int or tuple of ints) – Position in the expanded axes where the new axis (or axes) is placed.
axis_metadata (AxisMetadata or List of AxisMetadata, optional) – The axis metadata describing the expanded axes. Default is UnknownAxis.

Returns

expanded – View of array object with the number of dimensions increased.

Return type

ArrayObject or subclass of ArrayObject

from_array_and_metadata(array, axes_metadata, metadata)[source]#

Creates array object 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 wave function y- and x-axis, respectively.
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 wave function metadata. All items will be added to the metadata of measurements derived from the waves. The metadata must contain the electron energy [eV].

Returns

wave_functions – The created wave functions.

Return type

Waves

classmethod from_zarr(url, chunks='auto')#

Read wave functions from a hdf5 file.

urlstr: Location of the data, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data.
chunkstuple of ints or tuples of ints: Passed to dask.array.from_array(), allows setting the chunks on initialisation, if the chunking scheme in the on-disc dataset is not optimal for the calculations to follow.

Return type: TypeVar(T, bound= ArrayObject)

generate_blocks(chunks=1)#

Generate chunks of the ensemble.

Parameters: chunks (iterable of tuples) – Block sizes along each dimension.

generate_ensemble(keepdims=False)#

Generate every member of the ensemble.

Parameters: keepdims (bool, opptional) – If True, all ensemble axes are left in the result as dimensions with size one. Default is False.
Yields: ArrayObject or subclass of ArrayObject – Member of the ensemble.

get_items(items, keepdims=False)#

Index the array and the corresponding axes metadata. Only ensemble axes can be indexed.

Parameters

items (int or tuple of int or slice) – The array is indexed according to this.
keepdims (bool, optional) – If True, all ensemble axes are left in the result as dimensions with size one. Default is False.

Returns

indexed_array – The indexed array object.

Return type

ArrayObject or subclass of ArrayObject

imag()#

Returns the imaginary part of a complex-valued measurement.

Return type: TypeVar(T, bound= BaseMeasurement)

property intensities: numpy.ndarray#

Intensities of the diffraction spots.

Return type: ndarray

property intensities_dict: Dict[tuple[int, int, int], numpy.ndarray]#

A dictionary mapping miller indices to intensities.

Return type: Dict[tuple[int, int, int], ndarray]

intensity()#

Calculates the squared norm of a complex-valued measurement.

Return type: TypeVar(T, bound= BaseMeasurement)

property is_complex: bool#

True if array is complex.

Return type: bool

property is_lazy: bool#

True if array is lazy.

Return type: bool

max(axis=None, keepdims=False, split_every=2)#

Maximum of array object over one or more axes. Only ensemble axes can be reduced.

Parameters

axis (int or tuple of ints, optional) – Axis or axes along which a maxima are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the maxima are calculated over multiple axes. The indicated axes must be ensemble axes.
keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.
split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns

reduced_array – The reduced array object.

Return type

ArrayObject or subclass of ArrayObject

mean(axis=None, keepdims=False, split_every=2)#

Mean of array object over one or more axes. Only ensemble axes can be reduced.

Parameters

axis (int or tuple of ints, optional) – Axis or axes along which a means are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the mean is calculated over multiple axes. The indicated axes must be ensemble axes.
keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.
split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns

reduced_array – The reduced array object.

Return type

ArrayObject or subclass of ArrayObject

property metadata: dict#

Metadata describing the measurement.

Return type: dict

property miller_indices: numpy.ndarray#

Miller indices of the diffraction spots.

Return type: ndarray

min(axis=None, keepdims=False, split_every=2)#

Minmimum of array object over one or more axes. Only ensemble axes can be reduced.

Parameters

axis (int or tuple of ints, optional) – Axis or axes along which a minima are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the minima are calculated over multiple axes. The indicated axes must be ensemble axes.
keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.
split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns

reduced_array – The reduced array object.

Return type

ArrayObject or subclass of ArrayObject

no_base_chunks()#: Rechunk to remove chunks across the base dimensions.

normalize_ensemble(scale='max', shift='mean')#

Normalize the ensemble by shifting ad scaling each member.

Parameters

scale ({'max', 'min', 'sum', 'mean', 'ptp'}) –
shift ({'max', 'min', 'sum', 'mean', 'ptp'}) –

Returns

normalized_measurements

Return type

BaseMeasurements or subclass of _BaseMeasurement

normalize_to_spot(spot=None)[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

phase()#

Calculates the phase of a complex-valued measurement.

Return type: TypeVar(T, bound= BaseMeasurement)

poisson_noise(dose_per_area=None, total_dose=None, samples=1, seed=None)#

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 [electrons per Å:sup:2].
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 or subclass of _BaseMeasurement

property positions: numpy.ndarray#

Reciprocal space positions of the diffraction spots.

Return type: ndarray

property positions_dict: Dict[tuple[int, int, int], numpy.ndarray]#

A dictionary mapping miller indices to reciprocal space positions [1/Å].

Return type: Dict[tuple[int, int, int], ndarray]

real()#

Returns the real part of a complex-valued measurement.

Return type: TypeVar(T, bound= BaseMeasurement)

rechunk(chunks, **kwargs)#

Rechunk dask array.

chunksint or tuple or str: How to rechunk the array. See dask.array.rechunk.
kwargs :: Additional keyword arguments passes to dask.array.rechunk.

reduce_ensemble()#

Calculates the mean of an ensemble measurement (e.g. of frozen phonon configurations).

Return type: TypeVar(T, bound= BaseMeasurement)

relative_difference(other, min_relative_tol=0.0)#

Calculates the relative difference with respect to another compatible measurement.

Parameters

other (BaseMeasurements) – Measurement to which the difference is calculated.
min_relative_tol (float) – Avoids division by zero errors by defining a minimum value of the divisor in the relative difference.

Returns

difference – The relative difference as a measurement of the same type.

Return type

BaseMeasurements

remove_low_intensity(threshold=0.001)[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

select_block(index, chunks)#

Select a block from the ensemble.

Parameters

index (tuple of ints) – Index of selected block.
chunks (iterable of tuples) – Block sizes along each dimension.

set_ensemble_axes_metadata(axes_metadata, axis)#

Sets the axes metadata of an ensemble axis.

Parameters

axes_metadata (AxisMetadata) – The new axis metadata.
axis (int) – The axis to set.

property shape: tuple[int, ...]#

Shape of the underlying array.

Return type: tuple[int, ...]

show(ax=None, cbar=False, cmap=None, vmin=None, vmax=None, power=1.0, common_color_scale=False, scale=1, explode=None, figsize=None, title=True, units=None, interact=False, display=True)[source]#

Show the diffraction spots 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.
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.
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

MeasurementVisualization2D

sort(criterion='distance')[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

Return type

IndexedDiffractionPatterns

squeeze(axis=None)#

Remove axes of length one from array object.

Parameters: axis (int or tuple of ints, optional) – Selects a subset of the entries of length one in the shape.
Returns: squeezed – The input array object, but with all or a subset of the dimensions of length 1 removed.
Return type: ArrayObject or subclass of ArrayObject

std(axis=None, keepdims=False, split_every=2)#

Standard deviation of array object over one or more axes. Only ensemble axes can be reduced.

Parameters

axis (int or tuple of ints, optional) – Axis or axes along which a standard deviations are calculated. The default is to compute the mean of the flattened array. If this is a tuple of ints, the standard deviations are calculated over multiple axes. The indicated axes must be ensemble axes.
keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.
split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns

reduced_array – The reduced array object.

Return type

ArrayObject or subclass of ArrayObject

sum(axis=None, keepdims=False, split_every=2)#

Sum of array object over one or more axes. Only ensemble axes can be reduced.

Parameters

axis (int or tuple of ints, optional) – Axis or axes along which a sums are performed. The default is to compute the mean of the flattened array. If this is a tuple of ints, the sum is performed over multiple axes. The indicated axes must be ensemble axes.
keepdims (bool, optional) – If True, the reduced axes are left in the result as dimensions with size one. Default is False.
split_every (int) – Only used for lazy arrays. See dask.array.reductions.

Returns

reduced_array – The reduced array object.

Return type

ArrayObject or subclass of ArrayObject

to_cpu()#

Move the array to the host memory from an arbitrary source array.

Return type: TypeVar(T, bound= ArrayObject)

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_of_indexed_spots
Return type: pd.DataFrame

to_gpu(device='gpu')#

Move the array from the host memory to a gpu.

Return type: TypeVar(T, bound= ArrayObject)

to_hyperspy()#: Convert measurement to a Hyperspy signal.

to_tiff(filename, **kwargs)#

Write data to a tiff file.

Parameters

filename (str) – The filename of the file to write.
kwargs – Keyword arguments passed to tifffile.imwrite.

to_zarr(url, compute=True, overwrite=False, **kwargs)#

Write data to a zarr file.

Parameters

url (str) – Location of the data, typically a path to a local file. A URL can also include a protocol specifier like s3:// for remote data.
compute (bool) – If true compute immediately; return dask.delayed.Delayed otherwise.
overwrite (bool) – If given array already exists, overwrite=False will cause an error, where overwrite=True will replace the existing data.
kwargs – Keyword arguments passed to dask.array.to_zarr.