RealSpaceLineProfiles

class abtem.measurements.RealSpaceLineProfiles(array, sampling=None, ensemble_axes_metadata=None, metadata=None)

Bases: _BaseMeasurement1D

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

Parameters:

• array (np.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.

__init__(array, sampling=None, ensemble_axes_metadata=None, metadata=None)

Methods

__init__(array[, sampling, ...])
abs()	Calculates the absolute value of a complex-valued measurement.
apply_func(func, **kwargs)	rtype: TypeVar(T, bound= ArrayObject)
apply_transform(transform[, max_batch])	Transform the wave functions by a given transformation.
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.
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, axes_metadata)	Creates line profile(s) 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_from_metadata(name[, broadcastable])
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.
interpolate([sampling, gpts, order, endpoint])	Interpolate line profile(s) producing equivalent line profile(s) with a different sampling.
lazy([chunks])	rtype: TypeVar(T, bound= ArrayObject)
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.
phase()	Calculates the phase of a complex-valued measurement.
poisson_noise([dose_per_area, total_dose, ...])	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).
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. of frozen phonon configurations).
relative_difference(other[, min_relative_tol])	Calculates the relative difference with respect to another compatible measurement.
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, common_scale, explode, overlay, ...])	Show the reciprocal-space line profile(s) using matplotlib.
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.
tile(repetitions)	Tile line profiles(s).
to_cpu()	Move the array to the host memory from an arbitrary source array.
to_data_array()	Convert ArrayObject to a xarray DataArray.
to_gpu([device])	Move the array from the host memory to a gpu.
to_hyperspy()	Convert ArrayObject to a Hyperspy signal.
to_measurement_ensemble()
to_tiff(filename, **kwargs)	Write data to a tiff file.
to_zarr(url[, compute, overwrite])	Write data to a zarr file.
width([height])	Calculate the width of line(s) at a given height, e.g. full width at half maximum (the default).

Attributes

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.
extent	Extent of measurements [Å] or [1/Å].
is_complex	True if array is complex.
is_lazy	True if array is lazy.
metadata	Metadata describing the measurement.
sampling	Extent of measurements [Å] or [1/Å].
shape	Shape of the underlying array.

abs()

Calculates the absolute value of a complex-valued measurement.

Return type:

TypeVar(T, bound= BaseMeasurements)

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: ndarray | Array

Underlying array describing the array object.

property axes_metadata: AxesMetadataList

List of AxisMetadata.

property base_axes_metadata: list[RealSpaceAxis]

List of AxisMetadata of the base axes.

property base_dims

Number of base dimensions.

property base_shape: tuple[int, ...]

Shape of the base axes of the underlying array.

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

property device: str

The device where the array is stored.

property dtype: base

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[int, ...]

Shape of the ensemble axes of the underlying array.

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

property extent: float

Extent of measurements [Å] or [1/Å].

classmethod from_array_and_metadata(array, axes_metadata, metadata=None)

Creates line profile(s) from a given array and metadata.

Parameters:

• array (array) – Complex array defining one or more 1D line profiles.

• 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, optional) – A dictionary defining the measurement metadata.

Returns:

line_profiles – Line profiles from the array and metadata.

Return type:

RealSpaceLineProfiles

classmethod from_zarr(url, chunks='auto')

Read wave functions from a hdf5 file.

Return type:

TypeVar(T, bound= ArrayObject)

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.

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= BaseMeasurements)

intensity()

Calculates the squared norm of a complex-valued measurement.

Return type:

TypeVar(T, bound= BaseMeasurements)

interpolate(sampling=None, gpts=None, order=3, endpoint=False)

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

Parameters:

• sampling (float, optional) – Sampling of line profiles after interpolation [Å].

• gpts (int, optional) – Number of grid points of line profiles after interpolation. Do not use if ‘sampling’ is used.

• order (int, optional) – The order of the spline interpolation (default is 3). The order has to be in the range 0-5.

• endpoint (bool, optional) – If True, end is the last position. Otherwise, it is not included. Default is False.

Returns:

interpolated_profiles – The interpolated line profile(s).

Return type:

RealSpaceLineProfiles

property is_complex: bool

True if array is complex.

property is_lazy: bool

True if array is lazy.

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.

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

phase()

Calculates the phase of a complex-valued measurement.

Return type:

TypeVar(T, bound= BaseMeasurements)

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

real()

Returns the real part of a complex-valued measurement.

Return type:

TypeVar(T, bound= BaseMeasurements)

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= BaseMeasurements)

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

property sampling: float

Extent of measurements [Å] or [1/Å].

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.

show(ax=None, common_scale=True, explode=False, overlay=None, figsize=None, title=True, units=None, legend=False, interact=False, display=True, **kwargs)

Show the reciprocal-space line profile(s) using matplotlib.

Parameters:

• ax (matplotlib Axes, optional) – If given the plots are added to the Axes. This is not available for image grids.

• common_scale (bool) – If True all plots are shown with a common y-axis. Default is False.

• 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, only the one plot is created. 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.

• legend (bool) – Add a legend to the plot. The labels will be derived from

• units (str, optional) – The units used for the x-axis. The given units must be compatible.

• 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

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

tile(repetitions)

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

to_cpu()

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

Return type:

TypeVar(T, bound= ArrayObject)

to_data_array()

Convert ArrayObject to a xarray DataArray.

to_gpu(device='gpu')

Move the array from the host memory to a gpu.

Return type:

TypeVar(T, bound= ArrayObject)

to_hyperspy()

Convert ArrayObject 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.

width(height=0.5)

Calculate the width of line(s) at a given height, e.g. full width at half maximum (the default).

Parameters:

height (float) – Fractional height at which the width is calculated.

Returns:

width – The calculated width.

Return type:

float