[ENH] Allow setting vmin in plot_glass_brain and plot_stat_map

doc/changes/latest.rst

@@ -19,5 +19,7 @@ Fixes
 Enhancements
 ------------
 
+- 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

@@ -87,6 +87,36 @@
     stat_img, threshold=3, colorbar=True, plot_abs=True, 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

@@ -871,16 +871,13 @@ def custom_function(vertices):
 docdict[
     "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`.
-
+symmetric_cbar : :obj:`bool`, or "auto", default="auto"
+    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"` (the default) will select the former if either
+    `vmin` or `vmax` is `None` and the image has both positive and negative
+    values.
 """
 
 # t_r

nilearn/plotting/displays/_slicers.py

@@ -398,16 +398,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)
@@ -462,15 +452,37 @@
         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
 
+    @classmethod
+    def _threshold(cls, 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
 
@@ -945,7 +951,6 @@
 
         Default=`plt.cm.cold_hot`.
     %(symmetric_cbar)s
-        Default='auto'.
     %(dim)s
         Default='auto'.
     %(vmin)s
@@ -1061,7 +1066,6 @@
         :ref:`sphx_glr_auto_examples_01_plotting_plot_demo_glass_brain_extensive.py` # noqa
         for examples. Default=True.
     %(symmetric_cbar)s
-        Default='auto'.
     %(resampling_interpolation)s
         Default='continuous'.
     %(radiological)s 
@@ -1073,20 +1077,31 @@
     """
     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:
+                warnings.warn(
+                    'vmin is negative but plot_abs is True',
+                    category=UserWarning,
+                )
+            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

@@ -1086,7 +1086,6 @@ def plot_surf_stat_map(surf_mesh, stat_map, bg_map=None,
     %(vmin)s
     %(vmax)s
     %(symmetric_cbar)s
-        Default='auto'.
     %(bg_on_data)s
 
     %(darkness)s
@@ -1142,7 +1141,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 +1262,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 +1347,7 @@ 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
     %(cmap)s
         Default='cold_hot'.
     kwargs : dict, optional
@@ -1412,7 +1405,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)):

nilearn/plotting/tests/test_displays.py

@@ -375,3 +375,22 @@ def test_add_graph_with_node_color_as_string(node_color):
     node_coords = [[-53.60, -62.80, 36.64], [23.87, 0.31, 69.42]]
     lzry_projector.add_graph(matrix, node_coords, node_color=node_color)
     lzry_projector.close()
+
+
+@pytest.mark.parametrize(
+    "threshold,vmin,vmax,expected_results",
+    [
+        (None, None, None, [[-2, -1, 0], [0, 1, 2]]),
+        (0.5, None, None, [[-2, -1, np.nan], [np.nan, 1, 2]]),
+        (1, 0, None, [[np.nan, np.nan, np.nan], [np.nan, np.nan, 2]]),
+        (1, None, 1, [[-2, np.nan, np.nan], [np.nan, np.nan, np.nan]]),
+        (0, 0, 0, [[np.nan, np.nan, np.nan], [np.nan, np.nan, np.nan]]),
+    ],
+)
+def test_threshold(threshold, vmin, vmax, expected_results):
+    """Tests for ``OrthoSlicer._threshold``."""
+    data = np.array([[-2, -1, 0], [0, 1, 2]], dtype=float)
+    assert np.ma.allequal(
+        OrthoSlicer._threshold(data, threshold, vmin, vmax),
+        np.ma.masked_invalid(expected_results),
+    )