pyextal.larbed.analysis

Extraction of LARBED rocking curves from a raw 4D-STEM stack.

Classes

LARBEDAnalysis

Turns a raw EMPAD scan into one rocking curve per reflection.

Module Contents

class pyextal.larbed.analysis.LARBEDAnalysis(file_name)

Turns a raw EMPAD scan into one rocking curve per reflection.

The usual sequence is load_data(), average_data() (or align_data()), assign_gvector(), calculate_grid_vectors(), calculate_g_vectors(), and IntegrateLarbed(). The result can then be handed to the refinement stage with to_dinfo() or save_h5(), or written as loose .npy files with save_larbed().

Variables:

  • file_name (str) – Path to the raw .raw file.

  • data (np.ndarray) – The 4D stack (scan_x, scan_y, det_x, det_y).

  • center (tuple[float, float]) – Direct-beam position on the detector.

  • IntRadius (int) – Aperture half-width used by align_data() and ZeroLarbed().

  • grid (list) – Reciprocal-lattice nodes as (index, pixel) pairs.

  • g_vectors (list) – Miller index of each grid node.

  • Store_Larbed (list) – Integrated intensity map per reflection.

  • Store_LarbedVariance (list) – Propagated variance per reflection.

  • Store_bkg (list) – Subtracted background per reflection.

  • Store_bkg_info (list) – With a fitted background, n_fit (fit pixels) and noise_gain per reflection.

  • noise (dict) – The detector noise model measured by estimate_noise().

file_name
data = []
average_raw = None
average_aligned = None
aligned = False
g_grid = None
g_vectors = None
Larbed = []
LarbedDeconvolved = []
gg_pixels = []
mtf_2d = None
mixing = None
center = (64, 64)
IntRadius = 4
IntZero = []
noise = None
property detector_shape

Detector shape (det_x, det_y) of the loaded stack.

Type:

tuple[int, int]

load_data(type=0)

Reads the raw file and centres the direct beam on the detector midpoint.

Parameters:

type (int, optional) – Detector layout, passed to pyextal.larbed.empad.ReadRaw(). Defaults to 0.

align_data(iterations=3)

Aligns the stack on the direct beam and stores before/after averages.

Parameters:

iterations (int, optional) – Number of alignment passes. Defaults to 3.

deconv_DPstack(mtf_2d, background=0, niter=100, varB=6.29, delta=0, A=1, g=580, m=None)

Deconvolves every diffraction pattern in the stack against the MTF.

Parameters:

  • mtf_2d (np.ndarray) – The modulation transfer function.

  • background (float, optional) – Pattern background. Defaults to 0.

  • niter (int, optional) – Lucy-Richardson iterations. Defaults to 100.

  • varB (float, optional) – Background variance. Defaults to 6.29.

  • delta (float, optional) – Squared percentage gain error. Defaults to 0.

  • A (float, optional) – Fano/conversion-gain parameter. Defaults to 1.

  • g (float, optional) – Detector gain. Defaults to 580.

  • m (float, optional) – Mixing factor. Derived from mtf_2d when None. Defaults to None.

deconv_Larbedstack(background=0, niter=100, varB=6.29, delta=0.0, A=1, g=1, mtf_2d=None, pad_size=None, m=1)

Deconvolves the integrated rocking curves against the MTF.

Note

Legacy. Because the rocking curves are already integrated over an aperture, deconvolution mainly adds noise; this step is normally skipped. It also discards the propagated variance.

Parameters:

  • background (float, optional) – Background level. Defaults to 0.

  • niter (int, optional) – Lucy-Richardson iterations. Defaults to 100.

  • varB (float, optional) – Background variance. Defaults to 6.29.

  • delta (float, optional) – Squared percentage gain error. Defaults to 0.0.

  • A (float, optional) – Fano/conversion-gain parameter. Defaults to 1.

  • g (float, optional) – Detector gain. Defaults to 1.

  • mtf_2d (np.ndarray, optional) – MTF to use. Falls back to self.mtf_2d. Defaults to None.

  • pad_size (int, optional) – Edge padding applied before deconvolution. Defaults to None (no padding).

  • m (float, optional) – Mixing factor. Defaults to 1.

average_data()

Averages the stack without aligning it.

assign_gvector(g1, g2, g3=None, g4=None)

Records the detector pixel positions of the basis reflections.

Supply two basis vectors for a zone-axis grid, or four to include HOLZ reflections.

Parameters:

  • g1 (tuple[float, float]) – Pixel position of the first basis reflection.

  • g2 (tuple[float, float]) – Pixel position of the second.

  • g3 (tuple[float, float], optional) – Pixel position of the third. Defaults to None.

  • g4 (tuple[float, float], optional) – Pixel position of the fourth. Defaults to None.

calculate_g_vectors(g1, g2, g3=None, g4=None)

Assigns a Miller index to every node of the pixel grid.

The number of basis vectors must match what was passed to assign_gvector().

Parameters:

  • g1 (tuple[int, int, int]) – Miller index of the first basis reflection.

  • g2 (tuple[int, int, int]) – Miller index of the second.

  • g3 (tuple[int, int, int], optional) – Miller index of the third. Defaults to None.

  • g4 (tuple[int, int, int], optional) – Miller index of the fourth. Defaults to None.

calculate_grid_vectors(crop=1, order=3, Adjust=True)

Builds the reciprocal-space grid of reflections on the detector.

Dispatches on how many basis vectors assign_gvector() was given: four selects the HOLZ grid, two selects either the peak-snapped or the plain lattice grid depending on Adjust.

Parameters:

  • crop (int, optional) – Half-width of the peak search window used when Adjust is True. Defaults to 1.

  • order (int | tuple[int, int, int, int], optional) – Grid extent. Must be a 4-tuple for the HOLZ grid, an int otherwise. Defaults to 3.

  • Adjust (bool, optional) – Snap each two-vector grid node onto the nearest observed peak. Defaults to True.

plot_averages(ratio=0.2)

Plots the stack average before and after alignment.

Parameters:

ratio (float, optional) – Fraction of the maximum used as the display ceiling. Defaults to 0.2.

ZeroLarbed(ratio=1)

Integrates and plots the rocking curve of the direct beam.

Parameters:

ratio (float, optional) – Fraction of the maximum used as the display ceiling. Defaults to 1.

plot_grid_vectors(ratio=0.2)

Overlays the reflection grid on the stack average.

Parameters:

ratio (float, optional) – Fraction of the maximum used as the display ceiling. Defaults to 0.2.

IntegrateLarbed(ri=4, ro=(0, 0), g=1, m=1, DQE=1, varB=0.0, Variance=False, bkg_fit=None, mask_neighbours=True, clip=True, rho=None)

Integrates each reflection into a rocking curve.

Reflections whose background-subtracted sum is nowhere positive are dropped from grid and g_vectors as well as from the output.

By default the background is the mean of the ro annulus. That mean is biased high next to a bright reflection, whose convex tail runs through the annulus, and the clipping at zero then wipes out much of a weak rocking curve. With bkg_fit set, a polynomial surface is fitted instead, for each reflection on each frame, to the annulus pixels that are outside the aperture and (with mask_neighbours) away from the other reflections; the fitted surface summed under the aperture is what gets subtracted. See pyextal.larbed.empad.BackgroundFitWeights().

Parameters:

  • ri (int, optional) – Aperture half-width in pixels. Defaults to 4.

  • ro (tuple[int, int], optional) – Inner and outer radii of the background annulus. (0, 0) disables background subtraction. Defaults to (0, 0).

  • g (float, optional) – Detector gain. Defaults to 1.

  • m (float, optional) – Mixing factor. Defaults to 1.

  • DQE (float, optional) – Detective quantum efficiency. Defaults to 1.

  • varB (float, optional) – Per-pixel background variance. Defaults to 0.0.

  • Variance (bool, optional) – Also propagate the counting variance. Defaults to False.

  • bkg_fit (int, optional) – Fit the background as a polynomial of order 0 (constant), 1 (plane) or 2 (quadratic) instead of using the annulus mean. Order 2 needs an annulus spanning a range of radii that stays clear of the neighbouring reflections, e.g. ri=3, ro=(4, 6). Defaults to None (annulus mean).

  • mask_neighbours (bool, optional) – With bkg_fit, leave pixels within ri of the other grid reflections out of the fit. Defaults to True.

  • clip (bool, optional) – Set negative intensities to zero. Passing False keeps the noise around zero unbiased; note that the jaxGeo oversub model and pyextal.acom.quality were written for clipped data. Defaults to True.

  • rho (np.ndarray, optional) – Inter-pixel noise correlation kernel from estimate_noise(). The variance then includes the covariance between neighbouring pixels, both inside the aperture and between the aperture and the background-fit pixels. Needs bkg_fit or no background. Defaults to None (independent pixels).

Raises:

ValueError – If bkg_fit is set without a background annulus, or rho with the annulus-mean background.

estimate_noise(**kwargs)

Measures the detector noise model from the scan itself.

See pyextal.larbed.empad.EstimatePixelNoise(). Pass the result to IntegrateLarbed() as m=noise['gm'] / g and rho=noise['rho'].

Parameters:

**kwargs – Passed to pyextal.larbed.empad.EstimatePixelNoise().

Returns:

gm, rho, gain_sum and n_pixels; also stored as self.noise.

Return type:

dict

plot_IntegratedLarbed(index, Variance=False)

Plots one integrated rocking curve, or all of them.

Parameters:

  • index (int | str) – Index of the reflection, or 'all'.

  • Variance (bool, optional) – Plot the variance map instead. Defaults to False.

deconvolve_image(index, niter=100, varB=6.29, delta=0, A=1, g=580)

Deconvolves a single integrated rocking curve against the MTF.

Parameters:

  • index (int) – Index of the reflection.

  • niter (int, optional) – Lucy-Richardson iterations. Defaults to 100.

  • varB (float, optional) – Background variance. Defaults to 6.29.

  • delta (float, optional) – Squared percentage gain error. Defaults to 0.

  • A (float, optional) – Fano/conversion-gain parameter. Defaults to 1.

  • g (float, optional) – Detector gain. Defaults to 580.

Returns:

The deconvolved rocking curve.

Return type:

np.ndarray

plot_larbed(rotation=-22, order_option=1, order=6, Circle_radius=8, a_expansion=1.6, ratio=0.2, Variance=False)

Plots every rocking curve at the position of its reflection.

Parameters:

  • rotation (float, optional) – Rotation applied to each rocking curve in degrees, aligning the tilt-scan axes with the pattern. Defaults to -22.

  • order_option (int, optional) – 0 filters reflections by the largest Miller index, 1 by the length of the g-vector. Defaults to 1.

  • order (int, optional) – Cutoff for the filter above. Defaults to 6.

  • Circle_radius (float, optional) – Radius of each rocking-curve disk. Defaults to 8.

  • a_expansion (float, optional) – Scaling applied to the disk positions. Defaults to 1.6.

  • ratio (float, optional) – Fraction of the display maximum used as the ceiling. Defaults to 0.2.

  • Variance (bool, optional) – Plot variance maps instead of intensities. Defaults to False.

stack()

Packs the integrated results into the arrays the refinement stage wants.

Returns:

The intensity stack shaped (n_beams, ny, nx), the matching variance stack (None if IntegrateLarbed() was run with Variance=False), and the Miller indices shaped (n_beams, 3).

Return type:

tuple[np.ndarray, np.ndarray | None, np.ndarray]

Raises:

RuntimeError – If IntegrateLarbed() has not been run.

to_dinfo(datpath, thickness, gl, tiltX=0.0, tiltY=0.0)

Builds a pyextal.dinfo.LARBEDDiffractionInfo from the results.

This is the direct handoff into the refinement stage, replacing a save_larbed() / np.load round-trip.

Parameters:

  • datpath (str | pathlib.Path) – Path to the crystal .dat file.

  • thickness (float) – Initial sample thickness estimate in Angstroms.

  • gl (float) – Tilt step size, as the number of steps spanning the x-axis reflection. See LARBED_Calibration.md.

  • tiltX (float, optional) – Initial tilt about x in degrees. Defaults to 0.0.

  • tiltY (float, optional) – Initial tilt about y in degrees. Defaults to 0.0.

Returns:

Ready to pass to pyextal.roi.LARBEDROI.

Return type:

pyextal.dinfo.LARBEDDiffractionInfo

save_h5(h5path, *, prefix='', crystal_dat='', date='')

Writes the integrated results into the /raw group of an HDF5 file.

This is the same file the pre-refinement and JAX refinement stages append to, so one dataset lives in one file end to end.

Parameters:

  • h5path (str | pathlib.Path) – Path to the HDF5 file, created if absent.

  • prefix (str, optional) – Acquisition prefix recorded as provenance. Defaults to “”.

  • crystal_dat (str, optional) – Name of the crystal .dat file recorded as provenance. Defaults to “”.

  • date (str, optional) – Acquisition date. Defaults to today.

save_larbed(filename)

Writes the integrated results as loose .npy files.

Parameters:

filename (str) – Path prefix. Four files are written, suffixed _Store_Larbed.npy, _Store_LarbedDeconvolved.npy, _Store_LarbedVariance.npy, and _g_vectors.npy.

out_larbed()

Returns the integrated results as Python lists.

Returns:

(Store_Larbed, Store_bkg, Store_LarbedVariance, g_vectors).

Return type:

tuple