Static pattern matching framework, orientation similarity map and crystal map merging

[ona-lab]

Static pattern matching and Orientation Similarity Map

Indexing against pre-computed dictionaries with simulated patterns from for example EMsoft's EMEBSD.f90 program or, hopefully soon, our own sampling from master patterns.
Produce a CrystalMap for each dictionary with scores and simulated_indices as properties. A merged CrystalMap and orientation similarity maps as property osm if wanted.

Depends on #233 and #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 numpy as np
>>> from orix.crystal_map import CrystalMap
>>> from orix.quaternion import Rotation
>>> import kikuchipy as kp
>>> from kikuchipy.indexing import orientation_similarity_map, merge_crystal_maps
>>> data = np.random.random(10000)
>>> s = kp.signals.EBSD(data.reshape((10,) * 4))
>>> s_sim_fe = kp.signals.EBSD(data.reshape((100, 10, 10)))
>>> s_sim_fe._xmap = CrystalMap(Rotation(np.zeros((100, 4))))  # Dummy
>>> s_sim_fe._xmap.phases[0].name = "ferrite"
>>> s_sim_au = kp.signals.EBSD(data.reshape((100, 10, 10)))
>>> s_sim_au._xmap = CrystalMap(Rotation(np.zeros((100, 4))))
>>> s_sim_au._xmap.phases[0].name = "austenite"
>>> xmap_fe, xmap_au = s.match_patterns([s_sim_fe, s_sim_au])  # Keep 50 best
[########################################] | 100% Completed |  0.1s  # Dask progressbar
[########################################] | 100% Completed |  0.1s
>>> xmap = merge_crystal_maps([xmap_fe, xmap_au], mean_n_best=3)
>>> xmap.osm = orientation_similarity_map(xmap, n_best=20).flatten()

Taking more control of the matching parameters

>>> xmap_au2, xmap_fe2, xmap_merged = s.match_patterns(
    simulations=[s_sim_au, s_sim_fe],
    metric=kp.indexing.similarity_metrics.ndp,  # Normalized dot product
    keep_n=30,
    n_slices=10,
    return_merged_crystal_map=True,
    get_orientation_similarity_map=True
)
Matching austenite patterns: 100%|██████████| 10/10 [00:00<00:00, 65.39slice/s, mem=50.2%]  # tqdm progressbar
Matching ferrite patterns: 100%|██████████| 10/10 [00:00<00:00, 65.83slice/s, mem=50.2%]

Note that the progressbar shows the phase name and memory used.

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've done several changes, including:

• Public API: kikuchipy.indexing:
  • merge_crystal_maps
  • orientation_similarity_map
  • similarity_metrics
    • make_similarity_metric
    • MetricScope
  • StaticDictionaryIndexing
• merge_crystalmaps -> merge_crystal_maps
• osm -> orientation_similarity_map
• StaticDictionaryIndexing.index() -> StaticDictionaryIndexing.call() (will have to see if this is best, not decided yet!)
• merge_crystal_maps:
  • Allow merging of maps with only a single score per point (e.g. the case when I refine only the top matching simulation in EMsoft's EMFitOrientation.f90 program)
  • Verbose commenting to explain shapes, axes, reshaping etc. (mainly for myself to understand what I've done!)
  • Best scores and corresponding simulation indices, restricted to one phase per point (not combined), are included among the merged map's properties
  • Combined best scores and corresponding combined simulated indices (incremented for the second, third, fourth etc. map/phase to make each simulated index unique across all maps/phases) are also included among the merged map's properties. The latter allows us to calculate a orientation similarity map from the merged map (across phase boundaries, that is)

Minor docstring changes. Haven't updated the tests, so they will fail.

[hakonanes]

@onatlandsmyr, do you have any comments to the changes I've made?

I think what's left now is

• touching up the orientation similarity map for for the documentation
• tests

I continue on this now, if that's okay with you.

Edit: add touching up the StaticDictionaryIndexing class and docstrings to the list.

[hakonanes]

Have tested merge_crystal_maps() thoroughly now, will look at testing of StaticDictionaryIndexing class next.

[hakonanes]

I just want to note that EMsoft now supports both NDP and NCC: EMsoft-org/EMsoft@9b56e35.

Edit: I actually think we should call it NCC instead of ZNCC, what do you think @onatlandsmyr?

Edit2: It seems like NCC was added to EMsoft for computing similarities between experimental/simulated Kossel patterns.

[hakonanes]

I've made all the docstring, test and code structure changes I plan to do now.

Since I'm the one who've made the last changes, I would appreciate it if you @onatlandsmyr could go over it, and make or suggest any changes you would like, and then we can merge!

Edit: I suggest also having a look at the API reference for any changes you may want: https://kikuchipy--234.org.readthedocs.build/en/234/reference.html#module-kikuchipy.indexing

Edit2: We should decide if we want to call it

• zero-mean normalized cross-correlation (ZNCC) or just normalized cross-correlation (NCC). Both Winkelmann and De Graef call it NCC, and I've only seen ZNCC being used on Wikipedia, not in the literature I've read.
• EBSD.dictionary_indexing() or EBSD.pattern_matching()/EBSD.match_patterns(), and similarity StaticDictionaryIndexing() or StaticPatternMatching()?

[hakonanes]

I have updated the top comment to reflect the pattern matching progressbar updates.

[ona-lab]

All the changes look very good and promising, thank you very much @hakonanes. I agree with all the refactoring of names and I like the new additional progress bar. When it comes to naming things, I generally trust you more than me seeing you have more experience in the field.

EDIT:
I like EBSD.match_patterns() and StaticPatternMatching.

[hakonanes]

I like EBSD.match_patterns() and StaticPatternMatching.

These names are now used, with the dictionary indexing references to Chen et al. (2015), Marquardt et al. (2017) and Jackson et al. (2019) kept.

[hakonanes]

I'll merge when you give me the green light, @onatlandsmyr!