stempy.image package¶

Module contents¶

class stempy.image.ImageArray(*args, **kwargs)¶: Bases: numpy.ndarray

stempy.image.calculate_average(reader)¶

Create an average image of all the images.

Parameters: reader (stempy.io.reader) – the file reader that has already opened the data.
Returns: The average image.
Return type: stempy.image.ImageArray

stempy.image.calculate_sum_sparse(electron_counts, frame_dimensions)¶

Compute a diffraction pattern from sparse electron counted data.

Parameters

electron_counts (numpy.ndarray (1D)) – A vector of electron positions flattened. Each pixel can only be a 1 (electron) or a 0 (no electron).
frame_dimensions (tuple of ints of length 2) – The shape of the detector.

Returns

A summed diffraction pattern.

Return type

numpy.ndarray

stempy.image.com_dense(frames)¶

Compute the center of mass for a set of dense 2D frames.

Parameters: frames (numpy.ndarray (2D or 3D)) – The frames to calculate the center of mass from
Returns: The center of mass along each axis of set of frames
Return type: np.ndarray

stempy.image.com_sparse(array, crop_to=None, init_center=None, replace_nans=True)¶

Compute center of mass (COM) for counted data directly from sparse (single) electron data. Empty frames will have COM set to NAN. There is an option to crop to a smaller region around the initial full frame COM to improve finding the center of the zero beam. If the cropped region has no counts in it then the frame is considered empty and COM will be NAN.

Parameters

array (stempy.io.SparseArray) – A SparseArray of the electron counted data
crop_to (tuple of ints of length 2) – optional; The size of the region to crop around initial full frame COM for improved COM near the zero beam
init_center (tuple of ints of length 2) – optional; The initial center to use before cropping. If this is not set then cropping will be applie around the center of mass of the each full frame.
replace_nans (bool) – If true (default) empty frames will have their center of mass set as the mean of the center of mass of the the entire data set. If this is False they will be set to np.NAN.

Returns

The center of mass in X and Y for each scan position. If a position has no data (len(electron_counts) == 0) then the center of the frame is used as the center of mass.

Return type

numpy.ndarray (2D)

stempy.image.create_stem_histogram(numBins, reader, inner_radii, outer_radii, scan_dimensions=(0, 0), center=(-1, -1))¶

Create a histogram of the stem images generated from the input.

Parameters

numBins – the number of bins the histogram should have.
reader (stempy.io.reader) – the file reader that has already opened the data.
inner_radii (list of ints) – a list of inner radii. Must match the length of outer_radii.
outer_radii (list of ints) – a list of outer radii. Must match the length of inner_radii.
scan_dimensions (tuple of ints of length 2) – the dimensions of the scan, where the order is (width, height). If set to (0, 0), an attempt will be made to read the scan dimensions from the data file.
center (tuple of ints of length 2) – the center of the images, where the order is (x, y). If set to (-1, -1), the center will be set to (scan_dimensions[0] / 2, scan_dimensions[1] / 2).

Returns

The bins and the frequencies of the histogram.

Return type

a tuple of length 2 of lists

stempy.image.create_stem_images(input, inner_radii, outer_radii, scan_dimensions=(0, 0), center=(-1, -1), frame_dimensions=None, frame_offset=0)¶

Create a series of stem images from the input.

Parameters

input (stempy.io.reader, an h5py file, ElectronCountedData, SparseArray, or numpy.ndarray) – the file reader that has already opened the data, or an open h5py file, or an ElectronCountedData namedtuple containing the sparse data, or a SparseArray, or a numpy.ndarray of either the sparse or the raw data (if the frame_dimensions argument is supplied, numpy.ndarray is inferred to be sparse data).
inner_radii (list of ints) – a list of inner radii. Must match the length of outer_radii.
outer_radii (list of ints) – a list of outer radii. Must match the length of inner_radii.
scan_dimensions (tuple of ints of length 2) – the dimensions of the scan, where the order is (width, height). If set to (0, 0), an attempt will be made to read the scan dimensions from the data file.
center (tuple of ints of length 2) – the center of the images, where the order is (x, y). If set to (-1, -1), the center will be set to (scan_dimensions[0] / 2, scan_dimensions[1] / 2).
frame_dimensions (tuple of ints of length 2) – the dimensions of each frame, where the order is (width, height). Only used for input of type numpy.ndarray, in which case its presence implies that the input is sparse data rather than raw data.
frame_offset (int) – the amount by which to offset the frame. Only used for sparse data input of type numpy.ndarray.

Returns

A numpy array of the STEM images.

Return type

numpy.ndarray

stempy.image.electron_count(reader, darkreference=None, number_of_samples=40, background_threshold_n_sigma=4, xray_threshold_n_sigma=10, threshold_num_blocks=1, scan_dimensions=(0, 0), verbose=False, gain=None, apply_row_dark=False, apply_row_dark_use_mean=True)¶

Generate a list of coordinates of electron hits.

Parameters

reader (stempy.io.reader) – the file reader that has already opened the data.
darkreference (stempy.image.ImageArray or stempy::Image<double>) – the dark reference to subtract, potentially generated via stempy.image.calculate_average().
number_of_samples (int) – the number of samples to take when calculating the thresholds.
background_threshold_n_sigma (int) – N-Sigma used for calculating the background threshold.
xray_threshold_n_sigma (int) – N-Sigma used for calculating the X-Ray threshold
threshold_num_blocks (int) – The number of blocks of data to use when calculating the threshold.
scan_dimensions (tuple of ints of length 2) – the dimensions of the scan, where the order is (width, height). Required if data is a numpy.ndarray.
verbose (bool) – whether or not to print out verbose output.
gain (numpy.ndarray (2D)) – the gain mask to apply. Must match the frame dimensions
apply_row_dark (bool) – whether to apply the row dark algorithm to the data.
apply_row_dark_use_mean – whether to use mean (if True) or median (if False) in the row dark algorith. Only applicable if apply_row_dark is True.
apply_row_dark_use_mean – bool

Returns

the coordinates of the electron hits for each frame.

Return type

SparseArray

stempy.image.filter_bad_sectors(com, cut_off)¶

Missing sectors of data can greatly affect the center of mass calculation. This function attempts to fix that issue. Usually, the problem will be evident by a bimodal histogram for the horizontal center of mass. Set the cut_off to a value between the real values and the outliers. cut_off is a tuple where values below cut_off[0] or above cut_off[1] will be set to the local median.

Parameters

com (np.ndarray (3d)) – The center of mass for the vertical and horizontal axes
cut_off (2-tuple) – The lower and upper cutoffs as a 2-tuple

:rtype numpy.ndarray (3d)

stempy.image.mask_real_space(array, mask)¶

Calculate a diffraction pattern from an arbitrary set of positions defined in a mask in real space

Parameters

array (SparseArray) – The sparse dataset
mask (np.ndarray) – The mask to apply with 0 for probe positions to ignore and 1 for probe positions to include in the sum. Must have the same scan shape as array

Return type

np.ndarray

stempy.image.maximum_diffraction_pattern(reader, darkreference=None)¶

Generate an image of the maximum diffraction pattern.

Parameters

reader (stempy.io.reader) – the file reader that has already opened the data.
darkreference (stempy.image.ImageArray or stempy::Image<double>) – the dark reference to subtract, potentially generated via stempy.image.calculate_average().

Returns

the maximum diffraction pattern.

Return type

stempy.image.ImageArray

stempy.image.phase_from_com(com, theta=0, flip=False, reg=1e-10)¶

Integrate 4D-STEM centre of mass (DPC) measurements to calculate object phase. Assumes a three dimensional array com, with the final two dimensions corresponding to the image and the first dimension of the array corresponding to the y and x centre of mass respectively. Note this version of the reconstruction is not quantitative.

Thanks to the py4DSTEM project and author Hamish Brown.

Parameters

com (numpy.ndarray, 3D) – The center of mass for each frame as a 3D array of size [2, M, N]
theta – The angle between real space and reciprocal space in radians

type theta: float :param flip: Whether to flip the com direction to account for a mirror across the vertical axis. type flip: bool :param reg: A regularization parameter type reg: float

Returns: A 2D ndarray of the DPC phase.
Return type: numpy.ndarray

stempy.image.plot_virtual_darkfield(image, centers_x, centers_y, radii, axes=None)¶

Plot circles on the diffraction pattern corresponding to the position and size of virtual dark field apertures. This has the same center and radii inputs as stempy.image.virtual_darkfield so users can check their input is physically correct.

Parameters

image (np.ndarray, 2D) – The diffraction pattern to plot over
centers_x (iterable) – The center of each round aperture as the row locations
centers_y (iterable) – The center of each round aperture as the column locations
radii (iterable) – The radius of each aperture.
axes (matplotlib.axes._subplots.AxesSubplot) – A matplotlib axes instance to use for the plotting. If None then a new plot is created.

Return type

matplotlib.axes._subplots.AxesSubplot

Example

>>> sp = stempy.io.load_electron_counts('file.h5')
>>> stempy.image.plot_virtual_darkfield(sp.sum(axis=(0, 1), 260, 160, 10) # 1 aperture

stempy.image.radial_sum(reader, center=(-1, -1), scan_dimensions=(0, 0))¶

Generate a radial sum from which STEM images can be generated.

Parameters

reader (stempy.io.reader) – the file reader that has already opened the data.
center (tuple of ints of length 2) – the center of the image, where the order is (x, y). If set to (-1, -1), the center will be set to (scan_dimensions[0] / 2, scan_dimensions[1] / 2).
scan_dimensions (tuple of ints of length 2) – the dimensions of the scan, where the order is (width, height). If set to (0, 0), an attempt will be made to read the scan dimensions from the data file.

Returns

The generated radial sum.

Return type

numpy.ndarray

stempy.image.radial_sum_sparse(sa, center)¶

Radial sum of sparse electron counted data

Parameters

sa (stempy.io.SparseArray) – A SparseArray data set.
center (tuple of ints of length 2) – The center of the diffraction pattern in pixels.

Returns

A ndarray of the radial sum of shape (scan_shape[0], scan_shape[0], max(frame_dimensions)/2

Return type

numpy.ndarray

stempy.image.virtual_darkfield(array, centers_x, centers_y, radii)¶

Calculate a virtual dark field image from a set of round virtual apertures in diffraction space. Each aperture is defined by a center and radius and the final image is the sum of all of them.

Parameters

array (SparseArray) – The SparseArray
centers_x (number or iterable) – The center of each round aperture as the row locations
centers_y (number or iterable) – The center of each round aperture as the column locations
radii (number or iterable) – The radius of each aperture.

Return type

np.ndarray

Example

>>> sp = stempy.io.load_electron_counts('file.h5')
>>> df2 = stempy.image.virtual_darkfield(sp, (288, 260), (288, 160), (10, 10)) # 2 apertures
>>> df1 = stempy.image.virtual_darkfield(sp, 260, 160, 10) # 1 aperture