index_dataset_with_template_rotation#

pyxem.utils.calibration.index_dataset_with_template_rotation(signal, library, phases=None, n_best=1, frac_keep=1.0, n_keep=None, delta_r=1.0, delta_theta=1.0, max_r=None, intensity_transform_function=None, normalize_images=False, normalize_templates=True, chunks='auto', parallel_workers='auto', target='cpu', scheduler='threads', precision=<class 'numpy.float64'>)[source]#

Index a dataset with template_matching while simultaneously optimizing in-plane rotation angle of the templates

Parameters:

signal (hyperspy.signals.Signal2D) – The 4D-STEM dataset.
library (diffsims.libraries.diffraction_library.DiffractionLibrary) – The library of simulated diffraction patterns.
phases (list, optional) – Names of phases in the library to do an indexation for. By default this is all phases in the library.
n_best (int, optional) – Number of best solutions to return, in order of descending match.
frac_keep (float, optional) – Fraction (between 0-1) of templates to do a full matching on. By default all templates will be fully matched. See notes for details.
n_keep (int, optional) – Number of templates to do a full matching on. Overrides frac_keep.
delta_r (float, optional) – The sampling interval of the radial coordinate in pixels.
delta_theta (float, optional) – The sampling interval of the azimuthal coordinate in degrees. This will determine the maximum accuracy of the in-plane rotation angle.
max_r (float, optional) – Maximum radius to consider in pixel units. By default it is the distance from the center of the patterns to a corner of the image.
intensity_transform_function (Callable, optional) – Function to apply to both image and template intensities on an element by element basis prior to comparison. Note that the function is performed on the CPU.
normalize_images (bool, optional) – Normalize the images in the correlation coefficient calculation
normalize_templates (bool, optional) – Normalize the templates in the correlation coefficient calculation
chunks (string or 4-tuple, optional) – Internally the work is done on dask arrays and this parameter determines the chunking of the original dataset. If set to None then no re-chunking will happen if the dataset was loaded lazily. If set to “auto” then dask attempts to find the optimal chunk size.
parallel_workers (int, optional) – The number of workers to use in parallel. If set to “auto”, the number of physical cores will be used when using the CPU. For GPU calculations the workers is determined based on the VRAM capacity, but it is probably better to choose a lower number.
target (string, optional) – Use “cpu” or “gpu”. If “gpu” is selected, the majority of the calculation intensive work will be performed on the CUDA enabled GPU. Fails if no such hardware is available.
scheduler (string) – The scheduler used by dask to compute the result. “processes” is not recommended.
precision (np.float32 or np.float64) – The level of precision to work with on internal calculations

Returns:

result (dict) – Results dictionary containing keys: phase_index, template_index, orientation, correlation, and mirrored_template. phase_index is the phase map, with each unique integer representing a phase. template_index are the best matching templates for the respective phase. orientation is the best matching orientations expressed in Bunge convention Euler angles. Correlation is the matching correlation indices. mirrored template represents whether the original template best fits (False) or the mirror image (True). Each is a numpy array of shape (scan_y, scan_x, n_best) except orientation is of shape (scan_y, scan_x, n_best, 3).
phase_key_dict (dictionary) – A small dictionary to translate the integers in the phase_index array to phase names in the original template library.

Notes

It is possible to run the indexation using a subset of the templates. This two-stage procedure is controlled through n_keep or frac_keep. If one of these parameters is set, the azimuthally integrated patterns are compared to azimuthally integrated templates in a first stage, which is very fast. The top matching patterns are passed to a second stage of full matching, whereby the in-plane angle is determined. Setting these parameters can usually achieve the same answer faster, but it is also possible an incorrect match is found.