[ENH] Allow setting vmin in plot_glass_brain and plot_stat_map

doc/changes/latest.rst

@@ -59,6 +59,8 @@ Enhancements
 
 - Improve ``generate_report`` method of maskers by allowing users to pass a cmap argument for plotting image (:gh:`3897` by `Yasmin Mzayek`_)
 
+- Allow setting ``vmin`` in :func:`~nilearn.plotting.plot_glass_brain` and :func:`~nilearn.plotting.plot_stat_map` (:gh:`3993` by `Michelle Wang`_).
+
 Changes
 -------
 

examples/01_plotting/plot_demo_glass_brain_extensive.py

@@ -88,6 +88,36 @@
     stat_img, threshold=3, colorbar=True, plot_abs=False, display_mode="yx"
 )
 
+###############################################################################
+# We can control the limits of the colormap and colorbar by setting ``vmin``
+# and ``vmax``. Note that we use a non-diverging colormap here since the
+# colorbar will not be centered around zero.
+
+# only plot positive values
+plotting.plot_glass_brain(
+    stat_img,
+    colorbar=True,
+    plot_abs=False,
+    display_mode="yz",
+    vmin=0,
+    threshold=2,
+    symmetric_cbar=False,
+    cmap="viridis",
+)
+
+###############################################################################
+# Here we set ``vmin`` to the threshold to use the full color range instead of
+# losing colours due to the thresholding.
+plotting.plot_glass_brain(
+    stat_img,
+    colorbar=True,
+    plot_abs=False,
+    display_mode="yz",
+    vmin=2,
+    threshold=2,
+    symmetric_cbar=False,
+    cmap="viridis",
+)
 
 ###############################################################################
 # Different projections for the left and right hemispheres

nilearn/_utils/docs.py

@@ -879,15 +879,12 @@ def custom_function(vertices):
     "symmetric_cbar"
 ] = """
 symmetric_cbar : :obj:`bool`, or "auto", optional
-    Specifies whether the colorbar should range from `-vmax` to `vmax`
-    or from `vmin` to `vmax`.
-    Setting to `"auto"` will select the latter
-    if the range of the whole image is either positive or negative.
-
-    .. note::
-
-        The colormap will always range from `-vmax` to `vmax`.
-
+    Specifies whether the colorbar and colormap should range from `-vmax` to
+    `vmax` (or from `vmin` to `-vmin` if `-vmin` is greater than `vmax`) or
+    from `vmin` to `vmax`.
+    Setting to `"auto"` will select the former if either 1) `vmin` or `vmax` is
+    None and the image has both positive and negative values, or 2) `vmin` is
+    equal to `-vmax`.
 """
 
 # t_r

nilearn/plotting/displays/_axes.py

@@ -431,6 +431,10 @@
         else:
             data_selection = data
 
+        # take absolute value if needed
+        if self._plot_abs:
+            data_selection = np.abs(data_selection)
+
         # We need to make sure data_selection is not empty in the x axis
         # This should be the case since we expect images in MNI space
         if data_selection.shape[0] == 0:

nilearn/plotting/displays/_slicers.py

@@ -397,16 +397,6 @@
             img = reorder_img(img, resample=resampling_interpolation)
         threshold = float(threshold) if threshold is not None else None
 
-        if threshold is not None:
-            data = _safe_get_data(img, ensure_finite=True)
-            if threshold == 0:
-                data = np.ma.masked_equal(data, 0, copy=False)
-            else:
-                data = np.ma.masked_inside(
-                    data, -threshold, threshold, copy=False
-                )
-            img = new_img_like(img, data, img.affine)
-
         affine = img.affine
         data = _safe_get_data(img, ensure_finite=True)
         data_bounds = get_bounds(data.shape, affine)
@@ -461,15 +451,36 @@
         ims = []
         to_iterate_over = zip(self.axes.values(), data_2d_list)
         for display_ax, data_2d in to_iterate_over:
+            # If data_2d is completely masked, then there is nothing to
+            # plot. Hence, no point to do imshow().
             if data_2d is not None:
-                # If data_2d is completely masked, then there is nothing to
-                # plot. Hence, no point to do imshow().
+                data_2d = self._threshold(
+                    data_2d,
+                    threshold,
+                    vmin=kwargs.get("vmin"),
+                    vmax=kwargs.get("vmax"),
+                )
+
                 im = display_ax.draw_2d(
                     data_2d, data_bounds, bounding_box, type=type, **kwargs
                 )
                 ims.append(im)
         return ims
 
+    def _threshold(self, data, threshold=None, vmin=None, vmax=None):
+        """Threshold the data."""
+        if threshold is not None:
+            data = np.ma.masked_where(
+                np.abs(data) <= threshold,
+                data,
+                copy=False,
+            )
+            if vmin is not None and vmin >= -threshold:
+                data = np.ma.masked_where(data < vmin, data, copy=False)
+            if vmax is not None and vmax <= threshold:
+                data = np.ma.masked_where(data > vmax, data, copy=False)
+        return data
+
     @fill_doc
     def _show_colorbar(
         self, cmap, norm, cbar_vmin=None, cbar_vmax=None, threshold=None

nilearn/plotting/img_plotting.py

@@ -22,6 +22,7 @@
 # delayed, so that the part module can be used without them).
 import numpy as np
 from matplotlib import gridspec as mgs
+from matplotlib.colors import LinearSegmentedColormap
 from nibabel.spatialimages import SpatialImage
 from scipy import stats
 from scipy.ndimage import binary_fill_holes
@@ -62,22 +63,20 @@
 
 def _get_colorbar_and_data_ranges(
     stat_map_data, vmin=None, vmax=None, symmetric_cbar=True,
-    force_min_stat_map_value=None, symmetric_data_range=True,
+    force_min_stat_map_value=None,
 ):
     """Set colormap and colorbar limits.
 
     Used by plot_stat_map, plot_glass_brain and plot_img_on_surf.
 
-    If symmetric_data_range is True, the limits for the colormap will
-    always be set to range from -vmax to vmax. The limits for the colorbar
-    depend on the symmetric_cbar argument, please refer to docstring of
-    plot_stat_map.
+    The limits for the colorbar depend on the symmetric_cbar argument. Please
+    refer to docstring of plot_stat_map.
     """
-    if symmetric_data_range and (vmin is not None):
-        raise ValueError('this function does not accept a "vmin" '
-                         'argument, as it uses a symmetrical range '
-                         'defined via the vmax argument. To threshold '
-                         'the plotted map, use the "threshold" argument')
+    # handle invalid vmin/vmax inputs
+    if (not isinstance(vmin, numbers.Number)) or (not np.isfinite(vmin)):
+        vmin = None
+    if (not isinstance(vmax, numbers.Number)) or (not np.isfinite(vmax)):
+        vmax = None
 
     # avoid dealing with masked_array:
     if hasattr(stat_map_data, '_mask'):
@@ -91,13 +90,13 @@
     stat_map_max = np.nanmax(stat_map_data)
 
     if symmetric_cbar == "auto":
-        if symmetric_data_range or (vmin is None) or (vmax is None):
+        if (vmin is None) or (vmax is None):
             symmetric_cbar = stat_map_min < 0 and stat_map_max > 0
         else:
             symmetric_cbar = np.isclose(vmin, -vmax)
 
     # check compatibility between vmin, vmax and symmetric_cbar
-    if symmetric_cbar or symmetric_data_range:
+    if symmetric_cbar:
         if vmin is None and vmax is None:
             vmax = max(-stat_map_min, stat_map_max)
             vmin = -vmax
@@ -109,28 +108,35 @@
             raise ValueError(
                 "vmin must be equal to -vmax unless symmetric_cbar is False."
             )
-
-    # set vmin/vmax based on data if they are not already set
-    if vmin is None:
-        vmin = stat_map_min
-    if vmax is None:
-        vmax = stat_map_max
+        cbar_vmin = vmin
+        cbar_vmax = vmax
 
     # set colorbar limits
-    if not symmetric_cbar:
+    else:
         negative_range = stat_map_max <= 0
         positive_range = stat_map_min >= 0
         if positive_range:
-            cbar_vmin = 0
-            cbar_vmax = None
+            if vmin is None:
+                cbar_vmin = 0
+            else:
+                cbar_vmin = vmin
+            cbar_vmax = vmax
         elif negative_range:
-            cbar_vmax = 0
-            cbar_vmin = None
+            if vmax is None:
+                cbar_vmax = 0
+            else:
+                cbar_vmax = vmax
+            cbar_vmin = vmin
         else:
-            cbar_vmin = stat_map_min
-            cbar_vmax = stat_map_max
-    else:
-        cbar_vmin, cbar_vmax = None, None
+            # limit colorbar to plotted values
+            cbar_vmin = vmin
+            cbar_vmax = vmax
+
+    # set vmin/vmax based on data if they are not already set
+    if vmin is None:
+        vmin = stat_map_min
+    if vmax is None:
+        vmax = stat_map_max
 
     return cbar_vmin, cbar_vmax, vmin, vmax
 
@@ -1073,20 +1079,30 @@
     """
     if cmap is None:
         cmap = cm.cold_hot if black_bg else cm.cold_white_hot
+        # use only positive half of colormap if plotting absolute values
+        if plot_abs:
+            cmap = LinearSegmentedColormap.from_list(
+                'cmap_pos', cmap(np.linspace(0.5, 1, 256)),
+            )
 
     if stat_map_img:
         stat_map_img = _utils.check_niimg_3d(stat_map_img, dtype='auto')
         if plot_abs:
-            cbar_vmin, cbar_vmax, vmin, vmax = _get_colorbar_and_data_ranges(
-                _safe_get_data(stat_map_img, ensure_finite=True),
-                vmax=vmax,
-                symmetric_cbar=symmetric_cbar,
-                force_min_stat_map_value=0)
+            if vmin is not None and vmin < 0:
+                raise ValueError(
+                    'vmin cannot be negative if plot_abs is True'
+                )
+            force_min_stat_map_value = 0
         else:
-            cbar_vmin, cbar_vmax, vmin, vmax = _get_colorbar_and_data_ranges(
-                _safe_get_data(stat_map_img, ensure_finite=True),
-                vmax=vmax,
-                symmetric_cbar=symmetric_cbar)
+            force_min_stat_map_value = None
+
+        cbar_vmin, cbar_vmax, vmin, vmax = _get_colorbar_and_data_ranges(
+            _safe_get_data(stat_map_img, ensure_finite=True),
+            vmin=vmin,
+            vmax=vmax,
+            symmetric_cbar=symmetric_cbar,
+            force_min_stat_map_value=force_min_stat_map_value,
+        )
     else:
         cbar_vmin, cbar_vmax = None, None
 

nilearn/plotting/surf_plotting.py

@@ -1142,7 +1142,6 @@ def plot_surf_stat_map(surf_mesh, stat_map, bg_map=None,
         vmin=vmin,
         vmax=vmax,
         symmetric_cbar=symmetric_cbar,
-        symmetric_data_range=False,
     )
 
     display = plot_surf(
@@ -1264,7 +1263,6 @@ def _colorbar_from_array(array, vmin, vmax, threshold, symmetric_cbar=True,
         vmin=vmin,
         vmax=vmax,
         symmetric_cbar=symmetric_cbar,
-        symmetric_data_range=False,
     )
     norm = Normalize(vmin=vmin, vmax=vmax)
     cmaplist = [cmap(i) for i in range(cmap.N)]
@@ -1350,11 +1348,8 @@ def plot_img_on_surf(stat_map, surf_mesh='fsaverage5', mask_img=None,
     %(vmin)s
     %(vmax)s
     %(threshold)s
-    symmetric_cbar : :obj:`bool`, or "auto", optional
-        Specifies whether the colorbar should range from `-vmax` to `vmax`
-        (or from `vmin` to `-vmin` if `-vmin` is greater than `vmax`) or
-        from `vmin` to `vmax`.
-        Default=True.
+    %(symmetric_cbar)s
+        Default='auto'.
     %(cmap)s
         Default='cold_hot'.
     kwargs : dict, optional
@@ -1412,7 +1407,6 @@ def plot_img_on_surf(stat_map, surf_mesh='fsaverage5', mask_img=None,
         vmin=vmin,
         vmax=vmax,
         symmetric_cbar=symmetric_cbar,
-        symmetric_data_range=False,
     )
 
     for i, (mode, hemi) in enumerate(itertools.product(modes, hemis)):