stempy.io package

Submodules

stempy.io.sparse_array module

exception stempy.io.sparse_array.FullExpansionDenied

Bases: Exception

class stempy.io.sparse_array.SparseArray(data, scan_shape, frame_shape, dtype=numpy.uint32, sparse_slicing=True, allow_full_expand=False, metadata=None)

Bases: object

Utility class for analyzing sparse electron counted data

This implements functions performed directly on the sparse data including binning scans/frames, and min/max/sum/mean operations for certain axes.

Standard slicing notation is also supported, including start, stop, and stride. Slicing returns either a new sparse array or a dense array depending on the user-defined settings.

VERSION = 3
bin_frames(bin_factor, in_place=False)

Perform a binning on the frame dimensions

This will sum frame values together to reduce the frame dimensions. The frame dimensions are the last 2 dimensions.

Parameters

  • bin_factor (int) – the factor to use for binning

  • in_place (bool) – whether to modify the current SparseArray or create and return a new one.

Returns

self if in_place is True, otherwise a new SparseArray

Return type

SparseArray

bin_scans(bin_factor, in_place=False)

Perform a binning on the scan dimensions

This will sum sparse frames together to reduce the scan dimensions. The scan dimensions are the first 1 or 2 dimension.

Parameters

  • bin_factor (int) – the factor to use for binning

  • in_place (bool) – whether to modify the current SparseArray or create and return a new one.

Returns

self if in_place is True, otherwise a new SparseArray

Return type

SparseArray

property frame_axes

Get the axes for the frame positions

Returns

the axes for the frame positions

Return type

tuple(int)

classmethod from_hdf5(filepath, **init_kwargs)

Create a SparseArray from a stempy HDF5 file

Parameters

  • filepath (str) – the path to the HDF5 file

  • init_kwargs (dict) – any kwargs to forward to SparseArray.__init__()

Returns

the generated sparse array

Return type

SparseArray

max(axis=None, dtype=None, **kwargs)

Return the maximum along a given axis.

For specialized axes, a quick, optimized max will be performed using the sparse data. For non specialized axes, a full expansion will be performed and then the max taken of that.

Current specialized axes are: 1. (0,) for 3D shape 2. (0, 1) for 4D shape

Parameters

  • axis (int or tuple) – the axis along which to perform the max

  • dtype (np.dtype) – the type of array to create and return. Defaults to self.dtype.

  • kwargs (dict) – any kwargs to pass to a non specialized axes operation

Returns

the result of the max

Return type

np.ndarray

mean(axis=None, dtype=None, **kwargs)

Return the mean along a given axis.

For specialized axes, a quick, optimized mean will be performed using the sparse data. For non specialized axes, a full expansion will be performed and then the mean taken of that.

Current specialized axes are: 1. (0,) for 3D shape 2. (0, 1) for 4D shape

Parameters

  • axis (int or tuple) – the axis along which to perform the mean

  • dtype (np.dtype) – the type of array to create and return. Defaults to np.float32.

  • kwargs (dict) – any kwargs to pass to a non specialized axes operation

Returns

the result of the mean

Return type

np.ndarray

min(axis=None, dtype=None, **kwargs)

Return the minimum along a given axis.

For specialized axes, a quick, optimized min will be performed using the sparse data. For non specialized axes, a full expansion will be performed and then the min taken of that.

Current specialized axes are: 1. (0,) for 3D shape 2. (0, 1) for 4D shape

Parameters

  • axis (int or tuple) – the axis along which to perform the min

  • dtype (np.dtype) – the type of array to create and return. Defaults to self.dtype.

  • kwargs (dict) – any kwargs to pass to a non specialized axes operation

Returns

the result of the min

Return type

np.ndarray

property ndim

The number of dimensions of the data

This is equal to len(scan shape + frame shape)

Returns

the number of dimensions of the data

Return type

int

property num_frames_per_scan

Get the number of frames per scan position

Returns

the number of frames per scan position

Return type

int

property num_scans

Get the number of scan positions

Returns

the number of scan positions

Return type

int

ravel_scans()

Reshape the SparseArray so the scan shape is flattened

The resulting SparseArray will be 3D, with 1 scan dimension and 2 frame dimensions.

Returns

self

Return type

SparseArray

reshape(*shape)

Set the shape of the data (scan shape + frame shape)

Parameters

shape (argument list or tuple of length 3 or 4) – the new shape of the data.

Returns

self

Return type

SparseArray

property scan_axes

Get the axes for the scan positions

Returns

the axes for the scan positions

Return type

tuple(int)

property scan_positions

Get an array of scan positions for the data

Returns

the scan positions

Return type

np.ndarray of int

property shape

The full shape of the data (scan shape + frame shape)

Returns

the full shape of the data

Return type

tuple of length 3 or 4

sum(axis=None, dtype=None, **kwargs)

Return the sum along a given axis.

For specialized axes, a quick, optimized sum will be performed using the sparse data. For non specialized axes, a full expansion will be performed and then the sum taken of that.

Current specialized axes are: 1. (0,) for 3D shape 2. (0, 1) for 4D shape

Parameters

  • axis (int or tuple) – the axis along which to perform the sum

  • dtype (np.dtype) – the type of array to create and return. Defaults to self.dtype.

  • kwargs (dict) – any kwargs to pass to a non specialized axes operation

Returns

the result of the sum

Return type

np.ndarray

to_dense()

Create and return a fully dense version of the sparse array

If the array shape is large, this may cause the system to run out of memory.

This is equivalent to array[:] if allow_full_expand is True and sparse_slicing is False.

Returns

the fully dense array

Return type

np.ndarray

write_to_hdf5(path)

Save the SparseArray to an HDF5 file.

Parameters

path (str) – path to the HDF5 file.

stempy.io.sparse_array.load_h5_to_dict(group, d)
stempy.io.sparse_array.save_dict_to_h5(d, group)

Module contents

class stempy.io.FileVersion

Bases: object

VERSION1 = 1
VERSION2 = 2
VERSION3 = 3
VERSION4 = 4
VERSION5 = 5
class stempy.io.Reader

Bases: stempy.io.ReaderMixin, object

class stempy.io.SectorThreadedReader

Bases: stempy.io.ReaderMixin, object

stempy.io.load_electron_counts(path)

Load electron counted data from an HDF5 file.

Parameters

path (str) – path to the HDF5 file.

Returns

a SparseArray containing the electron counted data

Return type

SparseArray

stempy.io.reader(path, version=FileVersion.VERSION1)

Create a file reader to read the data.

Parameters

  • path (str or h5py file) – either the path to the file or an open h5py file.

  • version (version from stempy.io.FileVersion) – the version of the file reader to use (unused for h5py files).

Returns

The reader for the data.

Return type

stempy.io.Reader, stempy.io.SectorReader, or stempy.io.PyReader

stempy.io.save_electron_counts(path, array)

Save the electron counted data to an HDF5 file.

Parameters

  • path (str) – path to the HDF5 file.

  • array (SparseArray) – the electron counted data.

stempy.io.save_raw_data(path, data, scan_dimensions=None, scan_positions=None, zip_data=False)

Save the raw data to an HDF5 file.

Parameters

  • path (str) – path to the HDF5 file.

  • data (numpy.ndarray) – the raw data to save.

  • scan_dimensions (tuple of ints of length 2) – the dimensions of the scan, where the order is (width, height).

  • scan_positions (list of ints) – the scan positions of each frame. This is only needed if the frames are not sorted.

  • zip_data (bool) – whether or not to compress the data with gzip.

stempy.io.save_stem_images(outputFile, images, names)

Save STEM images to an HDF5 file.

Parameters

  • outputFile (str) – path to the HDF5 file.

  • images (numpy.ndarray) – an array of STEM images.

  • names (a list of strings) – a list of names for the STEM images, to be saved as attributes. Must be the same length as images.

stempy.io.write_hdf5(path, reader, format=SectorReader.H5Format.Frame)

Write the data from a SectorReader to an HDF5 file.

Parameters

  • path (str) – path to the output HDF5 file.

  • reader (stempy.io.SectorReader) – a SectorReader that has opened the data.

  • format (SectorReader.H5Format) – whether to write in frame format or data cube format.