Heatmaps

dplabtools offers a dedicated heatmap class for visualizing WSI inference results performed by the WSIInference class.

WSIHeatmap class features include:

  • Configurable color map, data range, and transparency for visualized data.

  • Configurable color or transparency for image background.

  • Saving in different image formats, along with embedded resolution information.

  • Saving as overlays with a cut-off point.

  • Support for custom drawing functions for labels or watermarks added to saved images.

Basic usage

Assuming that the variable inference represents a WSIInference object:

from dplabtools.slides.processing import WSIHeatmap

heatmap = WSIHeatmap(heatmap_data=inference.classes_array[0], wsi_file=None)
heatmap.save_image("heatmap1.png")

Output (heatmap1.png):

Heatmap1

Class details

class dplabtools.slides.processing.WSIHeatmap(...)

Class for visualizing inference results.

Parameters:

  • heatmap_data (str or object) – NumPy array (file or object), or classes_array property from WSIInference representing just one class.

  • wsi_file (str or None) – WSI file (name or path) that the heatmap is generated for. Value None will disable the following class features: heatmap dimensions checks, overlay generation, saving as a TIF image (unless custom downsample_factor is provided).

  • overlay (bool, default=False) – When True, the heatmap will overlay the tissue image.

  • background_color (str, default="white") – Color representing heatmap image background. None will produce a transparent background.

  • color_map (str, default="jet") – Color map used for visualizing data. Colormap names are defined in: https://matplotlib.org/stable/users/explain/colors/colormaps.html

  • alpha (float, default=1) – Value representing the heatmap image transparency (for visualized data only, the heatmap background color is not affected).

  • vmin (float, optional) – Lower bound of the color map range for the heatmap.

  • vmax (float, optional) – Upper bound of the color map range for the heatmap.

  • cutoff (float, optional) – Heatmap data values below the cutoff value will be ignored. This allows for the elimination of low probability values.

save_colorbar_image(image_file, interpolation='none', dpi=300, draw_fn=None, draw_args=(), **savefig_kwargs)

Save the heatmap as an image with color bar.

Parameters:

  • image_file (str) – File name or path for saving the image file. File extension will determine the image format.

  • interpolation (str, default="none") – An interpolation method used internally by matplotlib.pyplot.imshow

  • dpi (int, default=300) – Saved image resolution in dots per inch.

  • draw_fn (function, optional) – Custom function to draw on the heatmap image canvas.

  • draw_args (tuple, optional) – Arguments for the custom draw function.

  • savefig_kwargs – Additional keyword parameters passed to the internal save image function. Reference: https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.savefig.html

save_image(image_file, draw_fn=None, draw_args=(), **save_kwargs)

Save the heatmap as an image.

Parameters:

  • image_file (str) – File name or path for saving the image file. File extension will determine the image format.

  • draw_fn (function, optional) – Custom function to draw on the heatmap image canvas.

  • draw_args (tuple, optional) – Arguments for the custom draw function.

  • save_kwargs – Additional keyword parameters passed to the internal save image function. Reference: https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save

save_tif(tif_file, downsample_factor=None, allow_compression=True, draw_fn=None, draw_args=())

Save the heatmap as a TIF image with embedded resolution information.

Parameters:

  • tif_file (str) – File name or path for saving the TIF file.

  • downsample_factor (float, optional) – Downsample factor used for resolution information. If not provided, the value will be determined based on the heatmap data size.

  • allow_compression (bool, default: True) – If True, JPEG compression will be applied automatically when transparency is not used and when the image background is defined.

  • draw_fn (function, optional) – Custom function to draw on the heatmap image canvas.

  • draw_args (tuple, optional) – Arguments for the custom draw function.

Note

Technically it is possible to feed any input data into the WSIHeatmap class. Such data needs to be a two-dimensional NumPy array with one restriction: values representing background pixels (i.e. pixels not processed by the model) should be encoded as NumPy nan (not a number) values.

Warning

When generating heatmaps for a larger collection of images in one experiment, a color map range should be specified (using vmin and vmax), otherwise the same color will represent different values for different images.

Examples

Heatmap2 Heatmap3 Heatmap4 Heatmap5

Custom drawing

Custom drawing is implemented by passing two additional parameters (draw_fn and draw_args) to all image saving functions. However the implementation details are not the same for each saving function. Assuming the variable inference represents a WSIInference object, the following example will add a custom label to the image saved using save_png:

from PIL import ImageFont
from dplabtools.slides.processing import WSIHeatmap

def draw_function(drawing_conext, *args):
    x, y, label, size = args
    font_path = "/tmp/DejaVuSans.ttf"
    font = ImageFont.truetype(font_path, size)
    drawing_conext.text((x, y), label, font=font, fill=(0,0,0))

heatmap = WSIHeatmap(heatmap_data=inference.classes_array[0], wsi_file=None,
                     alpha=1, background_color="yellow")
heatmap.save_image("heatmap6.png", draw_fn=draw_function, draw_args=(50, 50, "Image label", 300))

Output:

Heatmap6