[ENH] Colorbar ticks at threshold values

doc/changes/latest.rst

@@ -28,6 +28,7 @@ Fixes
 
 - Relax the :func:`~nilearn.interfaces.fmriprep.load_confounds` confounds selection on `cosine` as not all confound files contained the variables (:gh:`3816` by `Hao-Ting Wang`_).
 
+
 Enhancements
 ------------
 
@@ -39,6 +40,9 @@ Enhancements
 
 - Make return key names in the description file of destrieux surface consistent with :func:`~datasets.fetch_atlas_surf_destrieux` (:gh:`3774` by `Tarun Samanta`_).
 
+- When plotting thresholded statistical maps with a colorbar, the threshold value(s) will now be displayed as tick labels on the colorbar (:gh:`#2833` by `Nicolas Gensollen`_).
+
+
 Changes
 -------
 

nilearn/plotting/displays/_slicers.py

@@ -529,11 +529,7 @@
             self._colorbar_ax.set_axis_bgcolor("w")
 
         our_cmap = plt.get_cmap(cmap)
-        # edge case where the data has a single value
-        # yields a cryptic matplotlib error message
-        # when trying to plot the color bar
-        nb_ticks = 5 if cbar_vmin != cbar_vmax else 1
-        ticks = np.linspace(cbar_vmin, cbar_vmax, nb_ticks)
+        ticks = _get_cbar_ticks(norm.vmin, norm.vmax, offset, nb_ticks=5)
         bounds = np.linspace(cbar_vmin, cbar_vmax, our_cmap.N)
 
         # some colormap hacking
@@ -805,6 +801,35 @@
         )
 
 
+def _get_cbar_ticks(vmin, vmax, offset, nb_ticks=5):
+    """Help for BaseSlicer."""
+    # edge case where the data has a single value yields a cryptic
+    # matplotlib error message when trying to plot the color bar
+    if vmin == vmax:
+        return np.linspace(vmin, vmax, 1)
+
+    # If a threshold is specified, we want two of the ticks to
+    # correspond to -thresold and +threshold on the colorbar.
+    # If the threshold is very small compared to vmax, we use
+    # a simple linspace as the result would be very difficult to see.
+    ticks = np.linspace(vmin, vmax, nb_ticks)
+    if offset is not None and offset / vmax > 0.12:
+        diff = [abs(abs(tick) - offset) for tick in ticks]
+        # Edge case where the thresholds are exactly at
+        # the same distance to 4 ticks
+        if diff.count(min(diff)) == 4:
+            idx_closest = np.sort(np.argpartition(diff, 4)[:4])
+            idx_closest = np.in1d(ticks, np.sort(ticks[idx_closest])[1:3])
+        else:
+            # Find the closest 2 ticks
+            idx_closest = np.sort(np.argpartition(diff, 2)[:2])
+            if 0 in ticks[idx_closest]:
+                idx_closest = np.sort(np.argpartition(diff, 3)[:3])
+                idx_closest = idx_closest[[0, 2]]
+        ticks[idx_closest] = [-offset, offset]
+    return ticks
+
+
 class OrthoSlicer(BaseSlicer):
     """Class to create 3 linked axes for plotting orthogonal \
     cuts of 3D maps.

nilearn/plotting/img_plotting.py

@@ -223,6 +223,42 @@
     return display
 
 
+def _get_cropped_cbar_ticks(cbar_vmin, cbar_vmax,
+                            threshold=None, n_ticks=5):
+    """Helper function for _crop_colobar.
+    Returns ticks for cropped colorbars.
+
+        cbar_tick_locs = cbar.locator.locs
+        new_tick_locs = _get_cropped_cbar_ticks(
+        cbar_vmin, cbar_vmax, threshold,
+        n_ticks=len(cbar_tick_locs))
+        cbar.set_ticks(new_tick_locs, update_ticks=True)
+    """
+    new_tick_locs = np.linspace(cbar_vmin, cbar_vmax, n_ticks)
+    if threshold is not None:
+        # Case where cbar is either all positive or all negative
+        if 0 <= cbar_vmin <= cbar_vmax or cbar_vmin <= cbar_vmax <= 0:
+            idx_closest = np.argmin([abs(abs(new_tick_locs) - threshold)
+                                     for tick in new_tick_locs])
+            new_tick_locs[idx_closest] = threshold
+        else:
+            # Case where we do a symmetric thresholding within an
+            # asymmetric cbar and both threshold values are within bounds
+            if cbar_vmin <= -threshold <= threshold <= cbar_vmax:
+                from .displays import _get_cbar_ticks
+                new_tick_locs = _get_cbar_ticks(
+                    cbar_vmin, cbar_vmax, threshold,
+                    nb_ticks=len(new_tick_locs))
+            # Case where one of the threshold values is out of bounds
+            else:
+                idx_closest = np.argmin([abs(new_tick_locs - threshold)
+                                         for tick in new_tick_locs])
+                new_tick_locs[idx_closest] = (
+                    -threshold if threshold > cbar_vmax else threshold)
+    return new_tick_locs
+
+
+
 @fill_doc
 def plot_img(img, cut_coords=None, output_file=None, display_mode='ortho',
              figure=None, axes=None, title=None, threshold=None,

nilearn/plotting/surf_plotting.py

@@ -7,6 +7,9 @@
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import numpy as np
+import warnings
+
+
 from matplotlib import gridspec
 from matplotlib.cm import ScalarMappable
 from matplotlib.colorbar import make_axes
@@ -414,8 +417,8 @@
     if cbar_tick_format == "%i" and vmax - vmin < n_ticks - 1:
         ticks = np.arange(vmin, vmax + 1)
     else:
-        # remove duplicate ticks when vmin == vmax, or almost
-        ticks = np.unique(np.linspace(vmin, vmax, n_ticks))
+        from nilearn.plotting.displays import _get_cbar_ticks
+        ticks = _get_cbar_ticks(vmin, vmax, threshold, nb_ticks)
     return ticks
 
 
@@ -428,6 +431,10 @@
     norm = Normalize(vmin=vmin, vmax=vmax)
     cmaplist = [our_cmap(i) for i in range(our_cmap.N)]
     if threshold is not None:
+        if cbar_tick_format == "%i" and int(threshold) != threshold:
+            warnings.warn("You provided a non integer threshold "
+                            "but configured the colorbar to use "
+                            "integer formatting.")
         # set colors to grey for absolute values < threshold
         istart = int(norm(-threshold, clip=True) * (our_cmap.N - 1))
         istop = int(norm(threshold, clip=True) * (our_cmap.N - 1))
@@ -597,6 +604,7 @@
                                           cbar_tick_format)
             our_cmap, norm = _get_cmap_matplotlib(cmap, vmin, vmax, threshold)
             bounds = np.linspace(cbar_vmin, cbar_vmax, our_cmap.N)
+
             # we need to create a proxy mappable
             proxy_mappable = ScalarMappable(cmap=our_cmap, norm=norm)
             proxy_mappable.set_array(surf_map_faces)

nilearn/plotting/tests/test_img_plotting/test_img_plotting.py

@@ -244,3 +244,64 @@ def test_plotting_functions_radiological_view(
     result = plotting_func(testdata_3d_for_plotting["img"], radiological=True)
     assert result.axes.get("y").radiological is True
     plt.close()
+
+
+import nibabel
+
+from nilearn import plotting
+
+functions = [plotting.plot_stat_map, plotting.plot_img]
+EXPECTED = [(i, ["-10", "-5", "0", "5", "10"]) for i in [0, 0.1, 0.9, 1]]
+EXPECTED += [
+    (i, ["-10", f"-{i}", "0", f"{i}", "10"]) for i in [1.3, 2.5, 3, 4.9, 7.5]
+]
+EXPECTED += [(i, [f"-{i}", "-5", "0", "5", f"{i}"]) for i in [7.6, 8, 9.9]]
+
+
+@pytest.mark.parametrize(
+    "plot_func, threshold, expected_ticks",
+    [(f, e[0], e[1]) for e in EXPECTED for f in functions],
+)
+def test_plot_symmetric_colorbar_threshold(
+    tmp_path, plot_func, threshold, expected_ticks
+):
+    img_data = np.zeros((10, 10, 10))
+    img_data[4:6, 2:4, 4:6] = -10
+    img_data[5:7, 3:7, 3:6] = 10
+    img = nibabel.Nifti1Image(img_data, affine=np.eye(4))
+    display = plot_func(img, threshold=threshold, colorbar=True)
+    plt.savefig(tmp_path / "test.png")
+    assert [
+        tick.get_text() for tick in display._cbar.ax.get_yticklabels()
+    ] == expected_ticks
+    plt.close()
+
+
+functions = [plotting.plot_stat_map]
+EXPECTED2 = [(0, ["0", "2.5", "5", "7.5", "10"])]
+EXPECTED2 += [(i, [f"{i}", "2.5", "5", "7.5", "10"]) for i in [0.1, 0.3, 1.2]]
+EXPECTED2 += [
+    (i, ["0", f"{i}", "5", "7.5", "10"]) for i in [1.3, 1.9, 2.5, 3, 3.7]
+]
+EXPECTED2 += [(i, ["0", "2.5", f"{i}", "7.5", "10"]) for i in [3.8, 4, 5, 6.2]]
+EXPECTED2 += [(i, ["0", "2.5", "5", f"{i}", "10"]) for i in [6.3, 7.5, 8, 8.7]]
+EXPECTED2 += [(i, ["0", "2.5", "5", "7.5", f"{i}"]) for i in [8.8, 9, 9.9]]
+
+
+@pytest.mark.parametrize(
+    "plot_func, threshold, expected_ticks",
+    [(f, e[0], e[1]) for e in EXPECTED2 for f in functions],
+)
+def test_plot_asymmetric_colorbar_threshold(
+    tmp_path, plot_func, threshold, expected_ticks
+):
+    img_data = np.zeros((10, 10, 10))
+    img_data[4:6, 2:4, 4:6] = 5
+    img_data[5:7, 3:7, 3:6] = 10
+    img = nibabel.Nifti1Image(img_data, affine=np.eye(4))
+    display = plot_func(img, threshold=threshold, colorbar=True)
+    plt.savefig(tmp_path / "test.png")
+    assert [
+        tick.get_text() for tick in display._cbar.ax.get_yticklabels()
+    ] == expected_ticks
+    plt.close()