Table of Contents
Shortcuts

slideflow.Heatmap

class Heatmap(slide: str | WSI, model: str, stride_div: int | None = None, batch_size: int = 32, num_threads: int | None = None, num_processes: int | None = None, img_format: str = 'auto', generate: bool = True, generator_kwargs: Dict[str, Any] | None = None, device: torch.device | None = None, load_method: str | None = None, **wsi_kwargs)[source]

Generate a heatmap of predictions across a whole-slide image.

This interface is designed to be used with tile-based models, and does not support multiple-instance learning models. Attention heatmaps of multiple-instance learning models can be generated using slideflow.mil.predict_slide().

Initialize a heatmap from a path to a slide or a slideflow.WSI.

Examples

Create a heatmap from a path to a slide.

model_path = 'path/to/saved_model'
heatmap = sf.Heatmap('slide.svs', model_path)

Create a heatmap, with grayspace filtering disabled.

heatmap = sf.Heatmap(..., grayspace_fraction=1)

Create a heatmap from a sf.WSI object.

# Load a slide
wsi = sf.WSI(tile_px=299, tile_um=302)

# Apply Otsu's thresholding to the slide,
# so heatmap is only generated on areas with tissue.
wsi.qc('otsu')

# Generate the heatmap
heatmap = sf.Heatmap(wsi, model_path)
Parameters:

  • slide (str) – Path to slide.

  • model (str) – Path to Tensorflow or PyTorch model.

  • stride_div (int, optional) – Divisor for stride when convoluting across slide. Defaults to 2.

  • roi_dir (str, optional) – Directory in which slide ROI is contained. Defaults to None.

  • rois (list, optional) – List of paths to slide ROIs. Alternative to providing roi_dir. Defaults to None.

  • roi_method (str) – Either ‘inside’, ‘outside’, ‘auto’, or ‘ignore’. Determines how ROIs are used to extract tiles. If ‘inside’ or ‘outside’, will extract tiles in/out of an ROI, and raise errors.MissingROIError if an ROI is not available. If ‘auto’, will extract tiles inside an ROI if available, and across the whole-slide if no ROI is found. If ‘ignore’, will extract tiles across the whole-slide regardless of whether an ROI is available. Defaults to ‘auto’.

  • batch_size (int, optional) – Batch size for calculating predictions. Defaults to 32.

  • num_threads (int, optional) – Number of tile worker threads. Cannot supply both num_threads (uses thread pool) and num_processes (uses multiprocessing pool). Defaults to CPU core count.

  • num_processes (int, optional) – Number of child processes to spawn for multiprocessing pool. Defaults to None (does not use multiprocessing).

  • enable_downsample (bool, optional) – Enable the use of downsampled slide image layers. Defaults to True.

  • img_format (str, optional) – Image format (png, jpg) to use when extracting tiles from slide. Must match the image format the model was trained on. If ‘auto’, will use the format logged in the model params.json. Defaults to ‘auto’.

  • generate (bool) – Generate the heatmap after initialization. If False, heatmap will need to be manually generated by calling :meth:Heatmap.generate().

  • generator_kwargs (dict, optional) – Keyword arguments passed to the slideflow.WSI.build_generator().

  • device (torch.device, optional) – PyTorch device. Defaults to initializing a new CUDA device.

:keyword Any keyword argument accepted by slideflow.WSI.:

Methods

add_inset(self, x: Tuple[int, int], y: Tuple[int, int], zoom: int = 5, loc: int = 1, mark1: int = 2, mark2: int = 4, axes: bool = True) → Inset

Adds a zoom inset to the heatmap.

clear_insets(self) → None

Removes zoom insets.

generate(self, asynchronous: bool = False, **kwargs) → Tuple[ndarray, Thread] | None

Manually generate the heatmap.

This function is automatically called when creating the heatmap if the heatmap was initialized with generate=True (default behavior).

Parameters:

  • asynchronous (bool, optional) – Generate heatmap in a separate thread, returning the numpy array which is updated in realtime with heatmap predictions and the heatmap thread. Defaults to False, returning None.

  • callback (Callable, optional) – Callback function to call each time the heatmap grid updated. The callback function should accept a single argument: a list of nested (x_idx, y_idx) lists, indicating the grid indices updated. Defaults to None.

Returns:

None if threaded=False, otherwise returns a tuple containing

grid: Numpy array containing updated in realtime with heatmap predictions as they are calculated.

Thread: Thread in which heatmap is generated.

load(self, path: str) → None

Load heatmap predictions and uncertainty from .npz file.

This function is an alias for slideflow.Heatmap.load_npz().

Parameters:

path (str, optional) – Source .npz file. Must have ‘predictions’ key and optionally ‘uncertainty’.

Returns:

None

load_npz(self, path: str) → None

Load heatmap predictions and uncertainty from .npz file.

Loads predictions from 'predictions' in .npz file, and uncertainty from 'uncertainty' if present, as generated from slideflow.Heatmap.save_npz()`(). This function is the same as calling heatmap.load().

Parameters:

path (str, optional) – Source .npz file. Must have ‘predictions’ key and optionally ‘uncertainty’.

Returns:

None

plot(self, class_idx: int, heatmap_alpha: float = 0.6, cmap: str = 'coolwarm', interpolation: str = 'none', vmin: float = 0, vmax: float = 1, vcenter: float = 0.5, ax: Axes | None = None, **thumb_kwargs) → None

Plot a predictive heatmap.

If in a Jupyter notebook, the heatmap will be displayed in the cell output. If running via script or shell, the heatmap can then be shown on screen using matplotlib plt.show():

import slideflow as sf
import matplotlib.pyplot as plt

heatmap = sf.Heatmap(...)
heatmap.plot()
plt.show()
Parameters:

  • class_idx (int) – Class index to plot.

  • heatmap_alpha (float, optional) – Alpha of heatmap overlay. Defaults to 0.6.

  • show_roi (bool, optional) – Overlay ROIs onto heatmap image. Defaults to True.

  • cmap (str, optional) – Matplotlib heatmap colormap. Defaults to ‘coolwarm’.

  • interpolation (str, optional) – Interpolation strategy to use for smoothing heatmap. Defaults to ‘none’.

  • vmin (float) – Minimimum value to display on heatmap. Defaults to 0.

  • vcenter (float) – Center value for color display on heatmap. Defaults to 0.5.

  • vmax (float) – Maximum value to display on heatmap. Defaults to 1.

  • ax (matplotlib.axes.Axes, optional) – Figure axis. If not supplied, will prepare a new figure axis.

Keyword Arguments:

  • show_roi (bool, optional) – Overlay ROIs onto heatmap image. Defaults to True.

  • roi_color (str) – ROI line color. Defaults to ‘k’ (black).

  • linewidth (int) – Width of ROI line. Defaults to 5.

plot_thumbnail(self, show_roi: bool = False, roi_color: str = 'k', linewidth: int = 5, width: int | None = None, mpp: float | None = None, ax: Axes | None = None) → plt.image.AxesImage

Plot a thumbnail of the slide, with or without ROI.

Parameters:

  • show_roi (bool, optional) – Overlay ROIs onto heatmap image. Defaults to True.

  • roi_color (str) – ROI line color. Defaults to ‘k’ (black).

  • linewidth (int) – Width of ROI line. Defaults to 5.

  • ax (matplotlib.axes.Axes, optional) – Figure axis. If not supplied, will prepare a new figure axis.

Returns:

Result from ax.imshow().

Return type:

plt.image.AxesImage

plot_with_logit_cmap(self, logit_cmap: Callable | Dict, interpolation: str = 'none', ax: Axes | None = None, **thumb_kwargs) → None

Plot a heatmap using a specified logit colormap.

Parameters:

  • logit_cmap (obj, optional) – Either function or a dictionary use to create heatmap colormap. Each image tile will generate a list of predictions of length O, where O is the number of outcomes. If logit_cmap is a function, then the logit prediction list will be passed to the function, and the function is expected to return [R, G, B] values for display. If logit_cmap is a dictionary, it should map ‘r’, ‘g’, and ‘b’ to indices; the prediction for these outcome indices will be mapped to the RGB colors. Thus, the corresponding color will only reflect up to three outcomes. Example mapping prediction for outcome 0 to the red colorspace, 3 to green, etc: {‘r’: 0, ‘g’: 3, ‘b’: 1}

  • interpolation (str, optional) – Interpolation strategy to use for smoothing heatmap. Defaults to ‘none’.

  • ax (matplotlib.axes.Axes, optional) – Figure axis. If not supplied, will prepare a new figure axis.

Keyword Arguments:

  • show_roi (bool, optional) – Overlay ROIs onto heatmap image. Defaults to True.

  • roi_color (str) – ROI line color. Defaults to ‘k’ (black).

  • linewidth (int) – Width of ROI line. Defaults to 5.

plot_uncertainty(self, heatmap_alpha: float = 0.6, cmap: str = 'coolwarm', interpolation: str = 'none', ax: Axes | None = None, **thumb_kwargs)

Plot heatmap of uncertainty.

Parameters:

  • heatmap_alpha (float, optional) – Alpha of heatmap overlay. Defaults to 0.6.

  • cmap (str, optional) – Matplotlib heatmap colormap. Defaults to ‘coolwarm’.

  • interpolation (str, optional) – Interpolation strategy to use for smoothing heatmap. Defaults to ‘none’.

  • ax (matplotlib.axes.Axes, optional) – Figure axis. If not supplied, will prepare a new figure axis.

Keyword Arguments:

  • show_roi (bool, optional) – Overlay ROIs onto heatmap image. Defaults to True.

  • roi_color (str) – ROI line color. Defaults to ‘k’ (black).

  • linewidth (int) – Width of ROI line. Defaults to 5.

save(self, outdir: str, show_roi: bool = True, interpolation: str = 'none', logit_cmap: Callable | Dict | None = None, roi_color: str = 'k', linewidth: int = 5, **kwargs) → None

Saves calculated predictions as heatmap overlays.

Parameters:

  • outdir (str) – Path to directory in which to save heatmap images.

  • show_roi (bool, optional) – Overlay ROIs onto heatmap image. Defaults to True.

  • interpolation (str, optional) – Interpolation strategy to use for smoothing heatmap. Defaults to ‘none’.

  • logit_cmap (obj, optional) – Either function or a dictionary use to create heatmap colormap. Each image tile will generate a list of predictions of length O, where O is the number of outcomes. If logit_cmap is a function, then the logit prediction list will be passed to the function, and the function is expected to return [R, G, B] values for display. If logit_cmap is a dictionary, it should map ‘r’, ‘g’, and ‘b’ to indices; the prediction for these outcome indices will be mapped to the RGB colors. Thus, the corresponding color will only reflect up to three outcomes. Example mapping prediction for outcome 0 to the red colorspace, 3 to green, etc: {‘r’: 0, ‘g’: 3, ‘b’: 1}

  • roi_color (str) – ROI line color. Defaults to ‘k’ (black).

  • linewidth (int) – Width of ROI line. Defaults to 5.

Keyword Arguments:

  • cmap (str, optional) – Matplotlib heatmap colormap. Defaults to ‘coolwarm’.

  • vmin (float) – Minimimum value to display on heatmap. Defaults to 0.

  • vcenter (float) – Center value for color display on heatmap. Defaults to 0.5.

  • vmax (float) – Maximum value to display on heatmap. Defaults to 1.

save_npz(self, path: str | None = None) → str

Save heatmap predictions and uncertainty in .npz format.

Saves heatmap predictions to 'predictions' in the .npz file. If uncertainty was calculated, this is saved to 'uncertainty'. A Heatmap instance can load a saved .npz file with slideflow.Heatmap.load().

Parameters:

path (str, optional) – Destination filename for .npz file. Defaults to {slidename}.npz

Returns:

Path to .npz file.

Return type:

str

view(self)

Load the Heatmap into Slideflow Studio for interactive view.

See Slideflow Studio: Live Visualization for more information.