Description

This is a summary of some inspection of the codebase to see how multichannel is typically handled. It seems the most common default is multichannel=False, but this is not always the case. There are a few functions that default to None and then try to guess True or False based on the data shape (i.e. if the last axis is size 3 (or 4), assume it is multi-channel). A couple of segmentation routines default to multichannel=True instead.

It would be helpful going forward to have a clear guideline of the expected behaviour for new PRs. I believe based on feedback in my prior PRs that multichannel=False is the preferred default, at least for n-dimensional routines.

Updated List as of July 2020
Progress has been made since this issue was originally opened and a number of functions were updated to default to False.

Notably, it seems that gaussian_filter and difference_of_gaussians are the only nD functions that still try to guess whether the data is multichannel based on its shape. hog also infers its multichannel status based on shape, but it is a 2D-only function, so that seems less problematic.

This is the current status (see details above for the original list). The values in parentheses are the number of spatial dimensions supported by the function:

default=True

• skimage.segmentation.felzenszwalb (2D)
• skimage.segmentation.slic: (2D or 3D)
• skimage.draw.random_shapes (creates synthetic data, so different rules may apply)

default=False

• skimage.exposure.match_histograms (nD)
• skimage.filters.unsharp_mask (nD)
• skimage.measure.structural_similarity (nD)
• skimage.restoration.cycle_spin (nD)
• skimage.restoration.denoise_bilateral (2D or 3D)
• skimage.restoration.denoise_nl_means (2D or 3D)
• skimage.restoration.denoise_tv_bregman (2D or 3D)
• skimage.restoration.denoise_tv_chambolle (nD)
• skimage.restoration.denoise_wavelet (nD)
• skimage.restoration.estimate_sigma (nD)
• skimage.restoration.inpaint_biharmonic (nD)
• skimage.segmentation.random_walker (2D or 3D)
• skimage.transform.pyramid_expand (nD)
• skimage.transform.pyramid_gaussian (nD)
• skimage.transform.pyramid_laplacian (nD)
• skimage.transform.pyramid_reduce (nD)
• skimage.transform.rescale (nD)
• skimage.transform.warp_polar (2D)
• skimage.util.montage (3D)

default=None (and guesses based on shape)

• skimage.feature.hog (2D)

    if multichannel is None:
        multichannel = (image.ndim == 3)

• skimage.filters.gaussian_filter (nD)
• skimage.filters.difference_of_gaussians (nD)

        calls a `_guess_spatial_dimensions helper`
        (does issue a warning when guessing)