abtem.array

Module for describing array objects.

Module Contents

Classes

ArrayObject	A base class for simulation objects described by an array and associated metadata.
ComputableList	A list with methods for conveniently computing its items.

Functions

concatenate	Join a sequence of abTEM array classes along an existing axis.
from_zarr	Read abTEM data from zarr (supports legacy and canonical formats).
moveaxis
multi_output_blockwise
stack	Stack multiple array objects (e.g. Waves and BaseMeasurements) along a new ensemble axis.
swapaxes
validate_axis_metadata
validate_lazy	Validate the lazy argument.

Data

ArrayItemType
ArrayObjectType
ArrayObjectTypeAlt
em
hs
tifffile
xr

API

abtem.array.ArrayItemType

None

class abtem.array.ArrayObject(...)

Bases: abtem.core.ensemble.Ensemble, abtem.core.utils.EqualityMixin, abtem.core.utils.CopyMixin

A base class for simulation objects described by an array and associated metadata.

Parameters:

• array (ndarray) – Array representing the array object.

• ensemble_axes_metadata (list of AxesMetadata) – Axis metadata for each ensemble axis. The axis metadata must be compatible with the shape of the array.

• metadata (dict) – A dictionary defining wave function metadata. All items will be added to the metadata of measurements derived from the waves.

Initialization

apply_func(...) → Self

Apply a function to the array object. The function must take an array as its first argument, only the array is modified, the metadata is not changed. The function is applied lazily if the array object is lazy.

Parameters:

• func (callable) – Function to apply to the array object.

• kwargs – Additional keyword arguments passed to the function.

Returns:

array_object – The array object with the function applied.

Return type:

ArrayObject or subclass of ArrayObject

apply_transform(...) → ArrayObject | list[ArrayObject]

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:

ArrayObject

property array: ndarray | dask.array.core.Array

Underlying array describing the array object.

property axes_metadata: AxesMetadataList

List of AxisMetadata.

property base_axes_metadata: list[AxisMetadata]

property base_dims: int

Number of base dimensions.

property base_shape: tuple[int, ...]

Shape of the base axes of the underlying array.

compute(...) → Self | tuple[Self, tuple]

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 scheduler is profiled.

• resource_profiler (bool) – Return ResourceProfiler class used to profile Dask’s execution at the resource level.

• kwargs – Additional keyword arguments passed to dask.compute.

copy_to_device(...) → Self

Copy array to specified device.

Parameters:

device (str)

Returns:

object_on_device

Return type:

ArrayObject

property device: str

The device where the array is stored.

property dtype: dtype

Datatype of array.

property ensemble_axes_metadata: list[AxisMetadata]

List of AxisMetadata of the ensemble axes.

property ensemble_dims: int

Number of ensemble dimensions.

property ensemble_shape: tuple[int, ...]

Shape of the ensemble axes of the underlying array.

ensure_lazy(...) → Self

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(...) → Self

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

abstract classmethod from_array_and_metadata(...) → Self

Creates array object from a given array and metadata.

Parameters:

• array (ndarray) – Array defining the array object.

• axes_metadata (list of AxesMetadata) – Axis metadata for each axis. The axis metadata must be compatible with the shape of the array.

• metadata – A dictionary defining the metadata of the array object.

Returns:

array_object – The array object.

Return type:

ArrayObject or subclass of ArrayObject

classmethod from_zarr(...) → Self

Read wave functions from a Zarr 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.

get_from_metadata(...)

get_items(...) → dict

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

property is_complex: bool

True if array is complex.

property is_lazy: bool

True if array is lazy.

lazy(...) → Self

max(...) → ArrayObject

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(...) → Self

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 stored as a dictionary.

min(...) → ArrayObject

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.

rechunk(...) → ArrayObject

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.

set_ensemble_axes_metadata(...) → Self

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.

squeeze(...) → Self

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(...) → ArrayObject

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(...) → ArrayObject

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() → Self

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

to_data_array()

Convert ArrayObject to a xarray DataArray. Requires xarray to be installed.

Returns:

The converted xarray DataArray.

Return type:

xarray.DataArray

Raises:

ImportError – If xarray is not installed.

to_gpu(...) → Self

Move the array from the host memory to a gpu.

to_hyperspy(...)

Convert ArrayObject to a Hyperspy signal.

Parameters:

transpose (bool, optional) – If True, transpose the base axes of the array before converting to a Hyperspy signal. Default is True.

Returns:

signal – The converted Hyperspy signal.

Return type:

Hyperspy signal

Raises:

• ImportError – If Hyperspy is not installed.

• RuntimeError – If the number of base dimensions is not 1 or 2.

Notes

This method requires Hyperspy to be installed. You can find more information about Hyperspy at https://hyperspy.org.

to_quantem()

Convert ArrayObject to quantem Dataset object.

to_tiff(...)

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(...)

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.

abtem.array.ArrayObjectType

‘TypeVar(…)’

abtem.array.ArrayObjectTypeAlt

‘TypeVar(…)’

class abtem.array.ComputableList

Bases: list

A list with methods for conveniently computing its items.

Initialization

Initialize self. See help(type(self)) for accurate signature.

compute(...) → list[ArrayObject] | tuple[list[ArrayObject], tuple]

Turn a list of lazy ArrayObjects object into the in-memory equivalents.

kwargs :

Keyword arguments passed to ArrayObject.compute.

to_zarr(...)

Write data to a zarr file.

Parameters:

• url (str) – Location of the data. For Zarr 3 zip stores, use a .zip extension. For directory stores, use .zarr extension or a directory path.

• compute (bool) – If true compute immediately; return dask.delayed.Delayed otherwise. Note that the returned delayed write nests an array.compute() executed under whatever scheduler is active when the caller finally computes it – the multi-GPU bootstrap and the forced synchronous GPU scheduler apply only to compute=True. On GPU, prefer compute=True or compute the result before saving.

• overwrite (bool) – If given array already exists, overwrite=False will cause an error, where overwrite=True will replace the existing data.

• progress_bar (bool) – Display a progress bar in the terminal or notebook during computation. The progress bar is only displayed with a local scheduler.

• compression_level (int or None) – If set (0–9), applies Zstandard compression with Blosc backend at that level. Level 0 disables compression. Default is 4, raises ValueError if > 9.

• kwargs – Keyword arguments passed to dask.array.to_zarr.

abtem.array.concatenate(...) → ArrayObject

Join a sequence of abTEM array classes along an existing axis.

Parameters:

• arrays (sequence of array objects) – Each abTEM array object must have the same type and shape, except in the dimension corresponding to axis. The axis metadata along the concatenated axis must be compatible for concatenation.

• axis (int, optional) – The axis along which the arrays will be joined. Default is 0.

Returns:

array_object – The concatenated array object of the same type as the input.

Return type:

ArrayObject

abtem.array.em: Optional[ModuleType]

None

abtem.array.from_zarr(...)

Read abTEM data from zarr (supports legacy and canonical formats).

Parameters:

• url (str) – Location of the data. A URL can include a protocol specifier like s3:// for remote data. For Zarr 3 zip stores, this should be a path to a .zip file.

• chunks (tuple 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.

Returns:

imported

Return type:

ArrayObject

abtem.array.hs: Optional[ModuleType]

None

abtem.array.moveaxis(...) → ArrayObject

abtem.array.multi_output_blockwise(...) → tuple[dask.array.core.Array, ...]

abtem.array.stack(...) → abtem.array.ArrayObjectType

Stack multiple array objects (e.g. Waves and BaseMeasurements) along a new ensemble axis.

Parameters:

• arrays (sequence of array objects) – Each abTEM array object must have the same type and shape.

• axis_metadata (AxisMetadata) – The axis metadata describing the new axis.

• axis (int) – The ensemble axis in the resulting array object along which the input arrays are stacked.

Returns:

array_object – The stacked array object of the same type as the input.

Return type:

ArrayObject

abtem.array.swapaxes(...)

abtem.array.tifffile: Optional[ModuleType]

None

abtem.array.validate_axis_metadata(...) → AxisMetadata

abtem.array.validate_lazy(...) → bool

Validate the lazy argument.

Parameters:

lazy (bool or None) – If None, return the default value from the configuration. If a boolean, return the value.

Returns:

lazy – The validated value of lazy.

Return type:

bool

abtem.array.xr: Optional[ModuleType]

None