Average patterns with nearest neighbours

[hakonanes]

Description

This PR adds averaging of patterns with its nearest neighbours. The user can decide:

• kernel size (both symmetrical and asymmetrical)
• kernel coefficients

So far, all neighbouring patterns are averaged equally. However, it should be fairly easy to add weighted averaging.

Type of change

• New feature (non-breaking change which adds functionality)

Progress

• Divide summed intensities by number of nearest neighbours
• Figure out conversion between data types: back to initial intensities after averaging? Perhaps a user option.
• Figure out warning or error messages when un-allowed scans, e.g. too small scans like (2 x 2) pattern scans, are passed
• Docstrings updated
• Code is commented, particularly in hard-to-understand areas
• Documentation and/or user guide updated
• Tests have been written
• Ready for review!

How has this been tested?

• Expected output intensities
• Expected warnings
• Expected errors

Minimal example of the bug fix or new feature

>>>import numpy as np
>>> import kikuchipy as kp
>>> s = kp.signals.EBSD(np.ones((4, 4, 2, 2), dtype=np.uint8))
>>> k = 1
>>> for i in range(4):
        for j in range(4):
            s.inav[j, i].data *= k
            k += 1
>>> print(s.mean(s.axes_manager.signal_axes).data)
array([[ 1.,  2.,  3.,  4.],
       [ 5.,  6.,  7.,  8.],
       [ 9., 10., 11., 12.],
       [13., 14., 15., 16.]])
>>> s.average_neighbour_patterns(kernel="rectangular", kernel_size=(3, 3))
>>> print(s.mean(s.axes_manager.signal_axes).data)
array([[ 3.5,  4. ,  5. ,  5.5],
       [ 5.5,  6. ,  7. ,  7.5],
       [ 9.5, 10. , 11. , 11.5],
       [11.5, 12. , 13. , 13.5]])

References

Implemented using scipy.ndimage.correlate, taking a queue from Stack Overflow user Evan Davis' solution. Also use Dask's overlapping computations functionality.

Addresses #13.

[coveralls]

Coverage remained the same at 100.0% when pulling dc8bea2 on hakonanes:pattern-averaging into 247851f on kikuchipy:master.

[tinabe]

This looks great. :)
I only added a couple of comments in regards of the clarity of documentation at specific points.

[hakonanes]

I realised that my implementation, with a few tweaks, can be made a lot more general, with options for the user to:

• use whichever kernel coefficients they want among the ones listed here (https://docs.scipy.org/doc/scipy/reference/generated/scipy.signal.windows.get_window.html#scipy.signal.windows.get_window), in addition to a circular one, similar to the boxcar (or rectangular) but with kernel corners excluded (like before). This circular kernel will be the default. Guess we should allow for a general kernel created by the user also.
• whichever kernel size (odd/even) they want, e.g. longer in slow scan direction and shorter in fast scan direction.

Have also created a simple drawing tool to plot the kernel and its coefficients, with this output for a Gaussian kernel with std=1:

[hakonanes]

A natural continuation of this averaging would be to implement different coefficients for each pattern, e.g. ones determined by similarity between the pattern at the kernel origin and its nearest neighbours in e.g. a (5 x 5) window like the ones used in the NLPAR method (https://github.com/USNavalResearchLaboratory/NLPAR).

This is actually pretty easy with Dask's map_blocks!

[hakonanes]

I again realise that my implementation should be even more generalised, in that a kernel class should be made! Kernel objects can then be obtained for pattern averaging, or for detection of peaks in the Hough/Radon transform. These are the two use cases I can think of so far...

I will implement the kernel class to work for pattern averaging now, with plans for generalising and/or extending it for peak detection in the future. Have therefore reverted this PR to work in progress.

[hakonanes]

The macOS build fails because it cannot find pytest, although it is listed among installed packages... Don't know why, but all tests pass on Linux and Windows.

[hakonanes]

Note that Travis macOS with pip fails here, however it is fixed in #143.

[tinabe]

This looks great - the documentation well explains the functionality, and there are several good examples. I have no major comments. You have done a great job on this!

[hakonanes]

Updated the documentation with your suggested explanation @tinabe (via personal correspondance, thanks a lot!). Also clarified the docstring for make_circular(). Left the Kernel methods is_valid() and scan_compatible() public, because why not. They are tested, and what they return, whether a kernel is valid or a kernel is compatible with an EBSD scan, will not change.

[hakonanes]

Tests fail on all Travis builds because of intensity comparisons for static and dynamic background corrections to predefined answers which apparently are not correct anymore, although they were correct yesterday... Because the data type used in those corrections were changed in PR #148, I will merge this since all other tests pass.