Plot overlay images

[TomSlater]

Description of the change

This PR implements a function to provide overlayed images of different colours (for example, for elemental maps). It aims to resolve issue #1812 .

Further improvements could be made by using ipywidgets to select colours and alpha values but this just adds initial functionality.

Progress of the PR

• Change implemented (can be split into several points),
• update docstring (if appropriate),
• update user guide (if appropriate),
• add entry to CHANGES.rst (if appropriate),
• add tests,
• ready for review.

Minimal example of the bug fix or the new feature

import hyperspy.api as hs
import numpy as np
from urllib.request import urlretrieve, urlopen
from zipfile import ZipFile
files = urlretrieve("https://www.dropbox.com/s/ecdlgwxjq04m5mx/HyperSpy_demos_EDS_TEM_files.zip?raw=1./HyperSpy_demos_EDX_TEM_files.zip")
with ZipFile("HyperSpy_demos_EDX_TEM_files.zip") as z:
    z.extractall()
si_EDS = hs.load("core_shell.hdf5")
im = si_EDS.get_lines_intensity()
hs.plot.plot_overlay_images(im, colors=['r','b'], alphas=[1.0,1.0], legend_list=['Fe','Pt'], scalebar=True, axes_decor='off')

[TomSlater]

I've added a basic test for plotting but I can't seem to get pytest to create the plot when running with --mpl-generate-path (it is creating others but not the one I've added). Perhaps someone could help me with this?

[codecov]

Codecov Report

Merging #2599 (4ff43bf) into RELEASE_next_minor (912fc57) will increase coverage by 0.58%.
The diff coverage is 72.85%.

@@                  Coverage Diff                   @@
##           RELEASE_next_minor    #2599      +/-   ##
======================================================
+ Coverage               75.89%   76.48%   +0.58%     
======================================================
  Files                     202      202              
  Lines                   29656    29802     +146     
  Branches                 6455     6517      +62     
======================================================
+ Hits                    22507    22793     +286     
+ Misses                   5330     5197     -133     
+ Partials                 1819     1812       -7     

Impacted Files	Coverage Δ
hyperspy/drawing/utils.py	71.83% <72.85%> (+1.45%)	⬆️
hyperspy/events.py	93.42% <0.00%> (ø)
hyperspy/drawing/image.py	72.43% <0.00%> (ø)
hyperspy/misc/material.py	83.44% <0.00%> (ø)
hyperspy/io_plugins/__init__.py	73.91% <0.00%> (ø)
hyperspy/_components/expression.py	100.00% <0.00%> (ø)
hyperspy/io_plugins/usid_hdf5.py	90.27% <0.00%> (+0.05%)	⬆️
hyperspy/io_plugins/tiff.py	86.91% <0.00%> (+0.08%)	⬆️
hyperspy/component.py	85.02% <0.00%> (+0.17%)	⬆️
hyperspy/models/model2d.py	77.31% <0.00%> (+0.19%)	⬆️
... and 20 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 912fc57...4ff43bf. Read the comment docs.

[ericpre]

I am wondering if it would make sense to incorporate it in plot_images instead of having a separate function?

I've added a basic test for plotting but I can't seem to get pytest to create the plot when running with --mpl-generate-path (it is creating others but not the one I've added). Perhaps someone could help me with this?

Please check that your version of matplotlib and freetype match the one defined in conda_environment_dev.yml (https://hyperspy.readthedocs.io/en/latest/dev_guide/testing.html#plot-testing)

[thomasaarholt]

Please check that your version of matplotlib and freetype match the one defined in conda_environment_dev.yml (https://hyperspy.readthedocs.io/en/latest/dev_guide/testing.html#plot-testing)

It can be useful to create a testing evironment in the same way that @ericpre's nice github actions do it:

From the base hyperspy path, create and update a conda environment like this:

conda env create -f conda_environment.yml # install hyperspy dependencies
conda env update -f conda_environment_dev.yml # install hyperspy testing dependencies
conda activate test_env # test_env is the name set in the yml file
pip install -e . # install hyperspy as a develop install

@ericpre would it be a good idea to add the above to the docs? As an alternative to the first code block in the "Running Tests" section?

[TomSlater]

I am wondering if it would make sense to incorporate it in plot_images instead of having a separate function?

I'm happy to incorporate it in to plot_images with an overlay = True argument or something similar. I don't have a preference really, I'd just followed Francisco's notes in #1812 when porting from my own function. Which do people think makes the most sense?

I'll have another go setting up a testing environment.

[ericpre]

Please check that your version of matplotlib and freetype match the one defined in conda_environment_dev.yml (https://hyperspy.readthedocs.io/en/latest/dev_guide/testing.html#plot-testing)

It can be useful to create a testing evironment in the same way that @ericpre's nice github actions do it:

From the base hyperspy path, create and update a conda environment like this:

conda env create -f conda_environment.yml # install hyperspy dependencies
conda env update -f conda_environment_dev.yml # install hyperspy testing dependencies
conda activate test_env # test_env is the name set in the yml file
pip install -e . # install hyperspy as a develop install

@ericpre would it be a good idea to add the above to the docs? As an alternative to the first code block in the "Running Tests" section?

Maybe a link to https://hyperspy.readthedocs.io/en/latest/user_guide/install.html#installation-in-a-anaconda-minconda-distribution?

[ericpre]

Here is an example:

A few suggestions:

• since there is no need for a colorbar, we can remove the white padding around the image, when axes_decor=off. This is convenient when saving the figure.
• add/remove a map when clicking on the legend, as it is currently done with plot_spectra? This should be possible by putting the for loop in a callback function and adapting the alpha accordingly. This would be used for a future widget adjusting the alpha.
• the fact that there are quite a bit of code which is the same or very similar to the plot_images function convinced me that it should be in the same function. The idea would be to switch overlay on/off simply by changing one parameter.
• the legend_title should be the same as the label parameter of plot_images and there should be possible to find the label automatically from the title. plot_images should be already doing some of it.

[TomSlater]

A few suggestions:

• since there is no need for a colorbar, we can remove the white padding around the image, when axes_decor=off. This is convenient when saving the figure.
• add/remove a map when clicking on the legend, as it is currently done with plot_spectra? This should be possible by putting the for loop in a callback function and adapting the alpha accordingly. This would be used for a future widget adjusting the alpha.
• the fact that there are quite a bit of code which is the same or very similar to the plot_images function convinced me that it should be in the same function. The idea would be to switch overlay on/off simply by changing one parameter.
• the legend_title should be the same as the label parameter of plot_images and there should be possible to find the label automatically from the title. plot_images should be already doing some of it.

I think I've covered almost all of these now, thanks for suggestions @ericpre ! It's incorporated in to plot_images, uses label for the legend and can now add/remove maps by clicking on the legend. You can get an overlay by simply setting overlay=True in the arguments of plot_images.

I'm not quite sure how to get rid of whitespace around the image, I think it may work in some cases but not all now. If anyone has any suggestions that would be very helpful.

[ericpre]

One way to do it would be:

import numpy as np
import matplotlib.pyplot as plt

pixel_number = 500
data = np.arange(pixel_number**2).reshape(pixel_number, pixel_number)
shape = data.shape

dpi = 100
sampling_factor = 10 # adjust the width of single pixel
fig = plt.figure(figsize=[sampling_factor*v/dpi for v in shape], dpi=dpi)

ax = fig.add_axes([0, 0, 1, 1])
ax.axis('off')
ax.imshow(data, cmap='gray')

plt.savefig('test.png')

[ericpre]

This is in good shape, I made suggestions to simplify the code.

[ericpre]

This is getting very nice! I have left a few minor comments. The vmax works well but not the vmin because of the transparency applied to the minimum value.

[ericpre]

A few last details in comments.
What do you want to do for the vmin issue? The simplest would be to ignore it and add a warning to the logger that vmin is ignored.

[ericpre]

The test failures should be fixed in #2603.

[TomSlater]

A few last details in comments.
What do you want to do for the vmin issue? The simplest would be to ignore it and add a warning to the logger that vmin is ignored.

I think you're right. I've just ignored it. In most cases where this is used (elemental maps), it's probably not going to be an issue.

All else should be sorted now.