ncempy.algo.peak_find module

Module to find local maxima in 2D and 3D data such as images and density maps.

Many functions are based on work by Colin Ophus, cophus@lbl.gov and his excellent RealSpaceLattice01.m code.

author: Peter Ercius, percius@lbl.gov

ncempy.algo.peak_find.applyLatticeLimit(lattice, bounds)[source]

Remove lattice points outside the data bounds. For 2D and 3D data.

Parameters:

  • lattice (ndarray; (N, 2) or (N, 3)) – From lattice2D

  • bounds (tuple,) – Minimum and maximum for axes 0 and 1 (min0, max0, min1, max1) or axes 0, 1 and 2 (min0, max0, min1, max1, min2, max2)

Returns:

Same as lattice input except only containing points within the bounds specified. M <= N

Return type:

ndarray; (M, 2) or (M, 3)

ncempy.algo.peak_find.calculate_unit_cell(image, lattice, u, v, unit_cell_size)[source]

IN PROGRESS Calculate a unit cell using the input lattice and lattice parameters. Any unit cell at the edge of the image is not used as part of the unit cell will be invalid.

Parameters:

  • image (ndarray) – The image containing the unit cell in a regular pattern (i.e. a lattice)

  • lattice (ndarray) – The starting position of each unit cell in the image.

  • u (tuple) – The u and v vectors for the fitted lattice

  • v (tuple) – The u and v vectors for the fitted lattice

  • unit_cell_size (int or tuple) – If int then this is the number of pixels in the unit cell along the u vector. The size of the v vector will be automatically calculated to make the unit cell pixels square. If tuple then the number of pixels along each u and v dimension are used directly.

Returns:

An array of size unit_cell_size which contains the average value of each position in the unit cell for each peak position and u,v, lattice point.

Return type:

ndarray

ncempy.algo.peak_find.doubleRoll(image, vec)[source]

Roll an 2D ndarray (e.g. an image) along each dimension.

Parameters:

  • image (np.ndarray) – The 2D array to roll.

  • vec (iterable) – The number of time to apply the roll to the rows and columns where the tuple has the structure (row, col). Values in tuple must be int.

Returns:

The rolled image.

Return type:

np.ndarray

ncempy.algo.peak_find.enforceMinDist(positions, intensities, minDistance)[source]

Remove peaks that violate a minimum distance requirement. If two peaks are closer together than the minDistance then the one with the highest intensity is chosen.

Works for 2D and 3D data sets.

Parameters:

  • positions (np.ndarray) – An array of shape Nx3 or Nx2 containing the positions of the peaks to test

  • intensities (np.ndarray) – An array of shape Nx1 with the peak intensities.

  • minDistance (int) – The minimum distance in pixels

Returns:

validPeaks – An ndarray of Mx3 or Mx2 (M <= N) with invalid peaks removed.

Return type:

np.ndarray

ncempy.algo.peak_find.fit_peaks_gauss2d(image, peaks, cutOut, init, bounds, remove_edge_peaks=True)[source]

Fit peaks to a 2D Gaussian. The Gaussian function is gaussND.gauss2D()

Todo: Write tests. This function is copied from test_peakFind.ipynb Todo: Add example test_peakFind.ipynb from my jupyter notebook folder

Parameters:

  • image (np.ndarray) – The 2D image with the intensities to fit to

  • peaks (np.ndarray) – The peaks in a ndarray of shape (N,2) where N is the number of peaks. Should match output of peakFind.peakFind2D.

  • cutOut (int) – The size (+/-) of the region around each peak to fit.

  • init (tuple) – A tuple of initial sigma values in x and y. (sigma_x, sigma_y)

  • bounds (tuple) – A tuple of 2 tuples indicating the upper and lower bounds for the fitting. See scipy.optimize.curve_fit for more information. Ordered as ( (center_x_low, center_y_low, sigma_x_low, sigma_y_low), (center_x_high, center_y_high, sigma_x_high, sigma_y_high))

  • remove_edge_peaks (bool, default = True) – Peak positions at the edge of the image are set to NaN and are removed. If you want to have those positions returned as nan set this to False.

Note

This function uses np.meshgrid and indexing=’ij’ internally.

Returns:

Returns a tuple of 3 arrays:

[0] optimized peak positions as a (M, 2) ndarray. M <= N. Peaks on the edge of the image are removed. [1] peak intensity value interpolated at the optimized peak position. [2] the fitting values for each peak

Return type:

tuple

ncempy.algo.peak_find.fit_peaks_gauss3d(volume, peaks, cutOut, init, bounds, remove_edge_peaks=True)[source]

Fit peaks to a 2D Gaussian. The Gaussian function is gaussND.gauss2D()

Todo: Write tests. This function is copied from test_peakFind_3d.ipynb

Parameters:

  • volume (np.ndarray) – The 3D image with the intensities to fit to.

  • peaks (np.ndarray) – The peaks in a ndarray of shape (N, 3) where N is the number of peaks. Should match output of peakFind.peakFind3D.

  • cutOut (int) – The size (+/-) of the region around each peak to fit.

  • init (tuple) – A 3-tuple of initial sigma values in x and y. (sigma_x, sigma_y, sigma_z)

  • bounds (tuple) – A 2-tuple of 6-tuples indicating the upper and lower bounds for the fitting. See scipy.optimize.curve_fit for more information. Ordered as ( (center_x_low, center_y_low, center_z_low, sigma_x_low, sigma_y_low, sigma_z_low), (center_x_high, center_y_high, center_z_high, sigma_x_high, sigma_y_high, sigma_z_high))

  • remove_edge_peaks (bool, default = True) – Peak positions at the edge of the image are set to NaN and are removed. If you want to have those positions returned as nan set this to False.

Note

This function uses np.meshgrid and indexing=’ij’ internally.

Returns:

Returns a tuple of 3 arrays:

[0] optimized peak positions as a (M, 3) ndarray. M <= N. Peaks on the edge of the image are removed unless otherwise specified. Then the edge peaks are returned as NAN values. [1] peak intensity value interpolated at the optimized peak position. [2] the local fitting values for each peak.

Return type:

tuple

ncempy.algo.peak_find.generateLatticeFromRefinement(origin, u, v, ab, fraction=(1, 1))[source]

Generate lattice positions from refined output of refineLattice2D. This can be used to generate all positions when fraction is used in refineLattice2D

Parameters:

  • origin (tuple) – Origin. 2-tuple

  • u (tuple) – Initial u vector. 2-tuple

  • v (tuple) – Initial v vector. 2-tuple

  • fraction (tuple) – The fraction used in refineLattice2D. 2-tuple

  • ab (np.ndarray) – The set of positions in terms of u and v lattice vectors. (number, position) (M, 2)

  • fraction – The fractional coordinates for the unit cell. 2-tuple

Returns:

The lattice site positions of the given lattice vectors of shape (M, 2)

Return type:

np.ndarray

ncempy.algo.peak_find.lattice2D(u, v, a, b, origin, num_points)[source]

A modified version of peakFind.lattice2D_norm which can use non normalized u,v,vectors

Parameters:

  • u (tuple) – 2 element vectors defining the lattice directions

  • v (tuple) – 2 element vectors defining the lattice directions

  • a (float) – values to multiply each vector by (if u,v,w are not normalized then set these to 1)

  • b (float) – values to multiply each vector by (if u,v,w are not normalized then set these to 1)

  • origin (tuple) – The origin in the format (x0,y0)

  • num_points (tuple) – 2 element tuple of the number of repeats of the lattice along each direction

Returns:

The set of points in the lattice. Size (num_points[0] * num_points[1], 2)

Return type:

ndarray

ncempy.algo.peak_find.lattice2D_2(u, v, a, b, xy0, numPoints)[source]

A modified version of lattice2D which uses non-normalized u, v vectors

ncempy.algo.peak_find.lattice2D_norm(u, v, a, b, origin, num_points)[source]

Returns a set of points in a lattice according to the u, v unit vectors (vectors are normalized internally) and lengths a,b centered at origin. The lattice has num_points along each u,v vector.

Parameters:

  • u (2-tuple) – 2 element tuples defining the lattice directions as vectors.

  • v (2-tuple) – 2 element tuples defining the lattice directions as vectors.

  • a (float) – values to multiply each vector by (if u,v are not normalized then set these to 1)

  • b (float) – values to multiply each vector by (if u,v are not normalized then set these to 1)

  • origin (2-tuple) – The origin in the format (x0, y0)

  • num_points (2-tuple) – 2 element tuple of the number of repeats of the lattice along each direction

Returns:

The set of points in the lattice. Size (num_points[0] * num_points[1], 2)

Return type:

ndarray

ncempy.algo.peak_find.lattice3D(u, v, w, a, b, c, origin, num_points)[source]

Returns a set of points in a lattice according to the u, v, w vectors and lengths a,b centered at origin. The lattice has num_points along each u,v,w vector.

Parameters:

  • u (tuple or np.ndarray) – 3 element vectors defining the lattice directions

  • v (tuple or np.ndarray) – 3 element vectors defining the lattice directions

  • w (tuple or np.ndarray) – 3 element vectors defining the lattice directions

  • a (float) – Values to multiply each vector by (if u,v,w are not normalized then set these to 1)

  • b (float) – Values to multiply each vector by (if u,v,w are not normalized then set these to 1)

  • c (float) – Values to multiply each vector by (if u,v,w are not normalized then set these to 1)

  • origin (tuple) – The origin in the format (x0,y0,z0)

  • num_points (tuple) – 3 element tuple of the number of repeats of the lattice along each direction

Returns:

xyz – A (N,3) shaped set of coordinates

Return type:

ndarray

ncempy.algo.peak_find.lattice3D_2(u, v, w, a, b, c, xyz0, numPoints)[source]

A modified version of lattice3D which uses non-normalized u,v vectors

ncempy.algo.peak_find.latticeDisplacements(peaks, u, v, origin)[source]

Find the displacements of the experimental peaks to the fitted lattice parameters

Parameters:

  • peaks (ndarray) – The experimental peaks with shape (num_peaks, 2). For example, the output of fit_peaks_gauss2d.

  • u (tuple) – The u and v vectors for the fitted lattice

  • v (tuple) – The u and v vectors for the fitted lattice

  • origin (tuple) – The origin of the fitted lattice for u, v vectors

Returns:

The displacement of each peak from the expected lattice position.

Return type:

ndarray

ncempy.algo.peak_find.match_lattice_peaks(peaks, u, v, origin)[source]

Find the matching lattice points to the experimental peaks. This is useful to generate all fitted lattice points for a set of experimental peaks. This can then be used directly to calculate displacements for example.

Parameters:

  • peaks (ndarray) – The experimental peaks as a (num_peaks, 2) ndarray

  • u (tuple) – The u and v vectors for the fitted lattice

  • v (tuple) – The u and v vectors for the fitted lattice

  • origin (tuple) – The origin of the fitted lattice for u, v vectors

Returns:

An array of shape (num_peaks, 2) where each coordinate is the closest lattice point for each input peak.

Return type:

ndarray

ncempy.algo.peak_find.peak3View(fg, vol, peak_positions)[source]

Plot 3 orthogonal slices and the corresponding peaks in each slice.

Not fully test. Unsure whether the slices and peaks are exactly the same.

todo: move this to viz

Parameters:

  • fg (matplotlib figure) – The figure to use. This allows the user to reuse figures

  • vol (ndarray (3D)) – The volume to slice along each orthogonal direction. Set up for [X,Z,Y] orientation

  • peak_positions (ndarray, list, tuple (1D)) – This selects the point shown in all three slices

Return type:

None

ncempy.algo.peak_find.peakFind2D(image, threshold)[source]

Find peaks in a 2D image based on the roll technique. A threshold is first applied to remove low intensity noisy peaks.

Parameters:

  • image (ndarray) – An 2D ndarray of image intensities with peaks to find.

  • threshold (float) – Threshold [0,1) the image to remove noisy peaks based on max intensity in the image

Returns:

positions – A Nx2 array with the index locations of the n number of peaks

Return type:

array

ncempy.algo.peak_find.peakFind3D(vol, threshold)[source]

Find peaks in a 3D volume based on the roll technique. A threshold is first applied to remove low intensity noisy peaks.

Parameters:

  • vol (ndarray) – An 3D ndarray of image intensities with peaks to find.

  • threshold (float) – Threshold [0,1) the image to remove noisy peaks based on max intensity in the image

Returns:

positions – A Nx3 array with the index locations of the n number of peaks

Return type:

ndarray

ncempy.algo.peak_find.peakPlot3D(X, Y, Z, mkr, myAxes3D)[source]

Plot a set of peaks in a 3D plot using matplotlib. See the example below for how to set up a figure as input to this function using matplotlib Axes3D.

todo: move this to viz

Parameters:

  • X (np.ndarray) – The x positions as a 1D array.

  • Y (np.ndarray) – The y positions as a 1D array.

  • Z (np.ndarray) – The Z positions as a 1D array.

  • mkr (string) – String indicating the marks type and color. Passed directly to pyplot.plt command (ex. ‘go’ for green circles)

  • myAxes3D (mpl_toolkits.mplot3d.Axes3d) – An Axes3D object. (see example below)

Return type:

None

Example

This function requires the input of a Axes3D to plot a set of peaks. See below how to import and set up a figure for use with this function. >> import matplotlib.pyplot as plt >> import mpl_toolkits.mplot3d >> from ncempy.algo import peak_find >> fg1 = plt.figure() >> ax1 = mpl_toolkits.mplot3d.Axes3D(fg1) >> peak_find.peakPlot3D(peakList[:,2], peakList[:,1], peakList[:,0], ‘go’, ax1)

ncempy.algo.peak_find.peaksToImage(peakList, imShape, gaussSigma, gaussSize, indexing='ij')[source]

Place 2D Gaussian at a set of peak positions.

Parameters:

  • peakList (np.ndarray) – Array of peak positions of size (numPeaks, 2).

  • imShape (tuple) – 2 element tuple of the shape of the image containing the peaks

  • gaussSigma (tuple) – 2 element tuple with that sigma parameters passed to the gaussND.gauss2D() function (sigX,sigY)

  • gaussSize (tuple) – 2 element tuple describing the 2D size of the simulated gaussian box. Must be odd.

  • indexing (str, default = 'ij') – ‘ij’ or ‘xy’ indexing to pass to np.meshgrid.

Returns:

A image containing Gaussian peaks at each position indicated in peakList parameter.

Return type:

np.ndarray

ncempy.algo.peak_find.peaksToVolume(peakList, volShape, gaussSigma, gaussSize, indexing='ij')[source]

Place 3D Gaussian at a set of peak positions.

Parameters:

  • peakList (np.ndarray) – Array of peak positions of size (numPeaks, 3).

  • volShape (tuple) – 3 element tuple of the shape of the volume containing the peaks

  • gaussSigma (tuple) – 3 element tuple with that sigma parameters passed to the gaussND.gauss3D() function (sigX,sigY,sigZ)

  • gaussSize (tuple) – 3 element tuple describing the 3D size of the simulated gaussian box. Must be odd.

  • indexing (str) – String to pass to np.meshgrid to indicate which indexing is used. Either ‘ij’ or ‘xy’ are possible. Default is ‘ij’ for this module.

Returns:

A volume containing gaussian peaks at each position indicated in peakList parameter.

Return type:

np.ndarray

ncempy.algo.peak_find.refineLattice2D(or0, u0, v0, pos, fraction=(1, 1), max_iter=30, refine_locally=True, verbose=False, num_unit_cells=(1, 1))[source]

Refine lattice based on measurements and initial guess at lattice vectors. This code is designed to work only with square lattices. Hexagonal and more complex lattice might not work.

Parameters:

  • or0 (tuple) – Initial guess of origin. 2-tuple

  • u0 (tuple) – Initial u vector. Use num_unit_cells to average over several lengths of the lattice vector in this direction. 2-tuple

  • v0 (tuple) – Initial v vector. Use num_unit_cells to average over several lengths of the lattice vector in this direction. 2-tuple

  • pos (np.ndarray) – The set of positions to fit the lattice to. (number, position) (M, 2)

  • refine_locally (bool) – Refine locally near the origin before using all positions Locally is considered 2 time the larger vector of u0 or v0.

  • fraction (tuple) – Site fraction to take into account peak positions inside the unit cell. FCC imaged along [100] for example would need site_fraction = (2, 2).

  • max_iter (int) – The maximum number of iterations to run to refine. This usually converges in a few iterations. Default is 30.

  • num_unit_cells (tuple) – The number of unit cells the initial guess of u0 and v0 extend over. 2-tuple (num_u0, num_v0) with default

  • verbose (bool) – Print out helpful information.

Returns:

Tuple of of 4 np.ndarray (origin, u, v, ab) where ab is the site positions in fractions of u and v.

Return type:

tuple

ncempy.algo.peak_find.refineLattice3D(or0, u0, v0, w0, pos, fraction=(1, 1, 1), max_iter=30, refine_locally=True)[source]

Refine lattice based on measurements and initial guess at lattice vectors

Warning

Tested code but not production yet. This is a work un progress.

Parameters:

  • or0 (3-element tuple) – Origin.

  • u0 (tuple) – Initial u vector.

  • v0 (tuple) – Initial v vector

  • w0 (tuple) – Initial w vector

  • pos (array (number, position) (M,3)) – The set of positions to fit the lattice to.

  • refine_locally (bool) – Refine locally near the origin before using all positions Locally is considered 2 time the larger vector of u0 or v0.

  • fraction (tuple) – Site fraction to take into account peak positions inside the unit cell. FCC imaged along [100] for example would need site_fraction = (2, 2).

  • max_iter (int) – Maximum number of iterations.

Returns:

Tuple of refined origin, u, v optimized values as np.ndarray and the site positions in fractions of u and v.

Return type:

tuple of 4 np.ndarray (origin, u, v, ab)

ncempy.algo.peak_find.remove_xrays(imageOriginal, threshold, size_median_filter=(3, 3))[source]

Find x-ray pixels in TEM images and replace the xray intensity with a local median value.

Parameters:

  • imageOriginal (ndarray) – The image as a 2D ndarray.

  • threshold (float) – Value above which to consider a pixel intensity an x-ray.

  • size_median_filter (list or tuple) – The footprint of the median filter over which to search for a median value.

Returns:

The image with x-ray values replaced with median local value.

Return type:

ndarray

ncempy.algo.peak_find.tripleRoll(vol, vec)[source]

Roll a 3D ndarray (e.g. an volume) along each dimension.

Parameters:

  • vol (np.ndarray) – The 3D array to roll

  • vec (iterable) – The number of time to apply the roll the tuple has the structure (axis0, axis1, axis2). Values in tuple must be int.

Returns:

The rolled volume.

Return type:

ndarray

ncempy.algo.peak_find.writeXYZ(filename, XYZ, element, comment)[source]

Write out a set of XYZ coordinates that can be read by various crystal viewing software such as Vesta.

todo: Move this to io

Parameters:

  • filename (str) – The name of the file to write to.

  • XYZ (np.ndarray) – Atom coordinates in a 2D ndarray with axes [atom number, position]. Should be shape [N, 3]

  • element (tuple) – Element symbol of each coordinate as a string (e.g. ‘C’). Should be length N.

  • comment (str) – A comment to add to the file.

Example

# Write out the peak positions as Carbon atoms: >> writeXYZ(‘name.xyz’, positions, [‘C’,] * len(positions), ‘writeXYZ example carbon atoms’)