Pattern Matching: Compare experimental with simulated data

[onatlandsmyr]

Matching diffraction patterns

Compare experimental and simulated patterns and return keep_n sorted match results. The match result consists of simulation indices and metric results having the shape; (nx*ny, keep_n).

The functions use dask functionality but accept both dask and numpy arrays as inputs. It is possible to divide the computation by slicing up simulations regardless of inputs being dask or numpy arrays. This is achieved by passing n_slices as keyword to pattern_match.

Mainly to be used by StaticDictionaryIndexing and DynamicDictionaryIndexing and not directly by the user.

This PR depends on #231 .

Progress of the PR

• Docstrings for all functions
• Unit tests with pytest for all lines
• Clean style in as per black

Minimal example of the bug fix or new feature

>>> import kikuchipy as kp
>>> import numpy as np
>>> from kikuchipy.indexing import pattern_match
>>> s = kp.signals.EBSD(np.zeros((10, 10, 10, 10)))
>>> s = kp.signals.EBSD(np.zeros((10, 10, 10, 10)))
>>> simulated = np.zeros((1000, 10, 10))
>>> simulation_indices, metric_results = pattern_match(s.data, simulated, keep_n=30, metric="zncc")
>>> s_best_match = kp.signals.EBSD(simulated[simulation_indices[:, 0]].reshape(10,10))

For reviewers

• Check that the PR title is short, concise, and will make sense 1 year
  later.
• Check that new functions are imported in corresponding __init__.py.
• Check that new features, API changes, and deprecations are mentioned in
  the unreleased section in doc/changelog.rst.

[hakonanes]

I think we should rename this submodule to pattern matching, because many notable resources use "template matching" for describing finding a smaller image template in a larger image:

• Wikipedia: https://en.wikipedia.org/wiki/Template_matching
• the OpenCV library: https://docs.opencv.org/master/d4/dc6/tutorial_py_template_matching.html

Further, I think renaming patterns -> experimental and templates -> simulated should be done.

What do you think, @onatlandsmyr?

[onatlandsmyr]

That sounds better and more clear. I guess I should also change patterns and templates throughout SimilarityMetric/#231, for consistency. Pattern matching is probably better since we have an implicit understanding of it being diffraction patterns. Out of context, they both would be the same thing for me. "Simulation matching" may be an alternative, but I'll stick with pattern matching for now.

[hakonanes]

That sounds better and more clear. I guess I should also change patterns and templates throughout SimilarityMetric/#231, for consistency. Pattern matching is probably better since we have an implicit understanding of it being diffraction patterns. Out of context, they both would be the same thing for me. "Simulation matching" may be an alternative, but I'll stick with pattern matching for now.

I agree that simulation matching would be equally descriptive. Pattern matching is used in the literature by e.g. Gert Nolze, Aimo Winkelmann, Angus Wilkinson, and others. Therefore I think it is safe to call it that!

[hakonanes]

I've closed one review comment and re-commented on the remaining three. I'll go over the PR one more time after these are resolved, and then we'll see if anything remains.

I'll update this branch with master and solve any potential conflicts now.

[hakonanes]

Great work, @onatlandsmyr!

I'm touching up formatting and API reference now, will then approve and we'll let the checks pass a last time before merging.

[onatlandsmyr]

Thank you, @hakonanes, for a great review and putting the finishing touch! It's a pleasure contributing to kikuchipy.

[hakonanes]

Thank you, @hakonanes, for a great review and putting the finishing touch! It's a pleasure contributing to kikuchipy.

Thanks, that's nice to hear (:

[hakonanes]

I see that two tests where you divide by zero throw warnings:

kikuchipy/indexing/tests/test_pattern_matching.py::TestPatternMatching::test_pattern_match_one_to_one
  /home/hakon/kode/kikuchipy/kikuchipy/indexing/similarity_metrics.py:402: RuntimeWarning: invalid value encountered in true_divide
    expt /= (expt ** 2).sum(axis=expt_sum_axis, keepdims=True) ** 0.5

kikuchipy/indexing/tests/test_pattern_matching.py::TestPatternMatching::test_pattern_match_one_to_one
  /home/hakon/kode/kikuchipy/kikuchipy/indexing/similarity_metrics.py:403: RuntimeWarning: invalid value encountered in true_divide
    sim /= (sim ** 2).sum(axis=sim_sum_axis, keepdims=True) ** 0.5

I would like to be warned when there are zero-intensities in my patterns, so I think this is okay. However, the tests shouldn't throw these I think, so I'll just add a np.errstate catch.