napari parameter sweeps

napari is a fast, interactive, multi-dimensional image viewer for python. It uses Qt for the GUI, so it’s easy to extend napari with small, composable widgets created with magicgui. Here, we demonstrate how to build a interactive widget that lets you immediately see the effect of changing one of the parameters of your function.

For napari-specific magicgui documentation, see the napari docs


See also: Some of this tutorial overlaps with topics covered in the napari image arithmetic example


This example demonstrates how to:

⬇️ Create a magicgui widget that can be used in another program (napari)

⬇️ Automatically call our function when a parameter changes

⬇️ Provide magicgui with a custom widget for a specific argument

⬇️ Use the choices option to create a dropdown

⬇️ Connect some event listeners to create interactivity.


Code follows, with explanation below… You can also get this example at github.

 1import napari
 3import skimage.filters
 4from napari.types import ImageData
 6from magicgui import magicgui
 9# turn the gaussian blur function into a magicgui
10# - `auto_call` tells magicgui to call the function when a parameter changes
11# - we use `widget_type` to override the default "float" widget on sigma,
12#   and provide a maximum valid value.
13# - we contstrain the possible choices for `mode`
15    auto_call=True,
16    sigma={"widget_type": "FloatSlider", "max": 6},
17    mode={"choices": ["reflect", "constant", "nearest", "mirror", "wrap"]},
18    layout='horizontal'
20def gaussian_blur(layer: ImageData, sigma: float = 1.0, mode="nearest") -> ImageData:
21    """Apply a gaussian blur to ``layer``."""
22    if layer is not None:
23        return skimage.filters.gaussian(layer, sigma=sigma, mode=mode)
25# create a viewer and add some images
26viewer = napari.Viewer()
27viewer.add_image(, name="astronaut")
28viewer.add_image("float"), name="grass")
30# Add it to the napari viewer
32# update the layer dropdown menu when the layer list changes


We’re going to go a little out of order so that the other code makes more sense. Let’s start with the actual function we’d like to write to apply a gaussian filter to an image.

the function

Our function is a very thin wrapper around skimage.filters.gaussian. It takes a napari Image layer, a sigma to control the blur radius, and a mode that determines how edges are handled.

def gaussian_blur(layer: Image, sigma: float = 1, mode="nearest") -> Image:
    return filters.gaussian(, sigma=sigma, mode=mode)

The reasons we are wrapping it here are:

  1. filters.gaussian accepts a numpy array, but we want to work with napari layers that store the data in a attribute. So we need an adapter.

  2. We’d like to add some type annotations to the signature that were not provided by filters.gaussian

type annotations

As described in the image arithmetic tutorial, we take advantage of napari’s built in support for magicgui by annotating our function parameters and return value as napari Layer types. napari will then tell magicgui what to do with them, creating a dropdown with a list of current layers for our layer parameter, and automatically adding the result of our function to the viewer when called.

For documentation on napari types with magicgui, see the napari docs

the magic part

Finally, we decorate the function with @magicgui and provide some options.

    sigma={"widget_type": "FloatSlider", "max": 6},
    mode={"choices": ["reflect", "constant", "nearest", "mirror", "wrap"]},
def gaussian_blur(layer: ImageData, sigma: float = 1.0, mode="nearest") -> ImageData:
    """Apply a gaussian blur to ``layer``."""
    if layer is not None:
        return skimage.filters.gaussian(layer, sigma=sigma, mode=mode)
  • auto_call=True makes it so that the gaussian_blur function will be called whenever one of the parameters changes (with the current parameters set in the GUI).

  • We then use parameter-specific options to modify the look & behavior of sigma and mode:

    • "widget_type": "FloatSlider" tells magicgui not to use the standard (float) widget for the sigma widget, but rather to use a slider widget.

    • we then set an upper limit on the slider values for sigma.

  • finally, we specify valid choices for the mode argument. This turns that parameter into a categorical/dropdown type widget, and sets the options.

connecting events

As described in the image arithmetic tutorial, we can also connect any callback to the gaussian_blur.called signal that will receive the result of our decorated function anytime it is called.