Repository: nilearn/nilearn

Issue:
Deprecate darkness in surf_plotting functions
This is a follow-up issue from #3173.

We should start a deprecation cycle for `darkness` in all functions in `plotting.surf_plotting`.
Indeed, this parameter is currently used to set a maximum value to a scaled background map (ie whose values are in [0,1]): `bg_map = darkness * bg_map`.
In the future, background maps will no longer be scaled by `nilearn`, so it no longer makes sense to have a `darkness` parameter.


Discussion:
I can work on this!
@alishakodibagkar I assigned you to it.
Let me know if you need help

Resolving patch:
diff --git a/nilearn/plotting/html_surface.py b/nilearn/plotting/html_surface.py
--- a/nilearn/plotting/html_surface.py
+++ b/nilearn/plotting/html_surface.py
@@ -2,6 +2,7 @@
 
 import collections.abc
 import json
+from warnings import warn
 
 import matplotlib as mpl
 import matplotlib.pyplot as plt
@@ -80,6 +81,13 @@ def _get_vertexcolor(surf_map, cmap, norm,
 
     if darkness is not None:
         bg_data *= darkness
+        warn(
+            (
+                "The `darkness` parameter will be deprecated in release 0.13. "
+                "We recommend setting `darkness` to None"
+            ),
+            DeprecationWarning,
+        )
 
     bg_colors = plt.get_cmap('Greys')(bg_data)
 
diff --git a/nilearn/plotting/surf_plotting.py b/nilearn/plotting/surf_plotting.py
--- a/nilearn/plotting/surf_plotting.py
+++ b/nilearn/plotting/surf_plotting.py
@@ -2,6 +2,7 @@
 import itertools
 import math
 from collections.abc import Sequence
+from warnings import warn
 
 import matplotlib as mpl
 import matplotlib.pyplot as plt
@@ -460,6 +461,13 @@ def _compute_facecolors_matplotlib(bg_map, faces, n_vertices,
 
     if darkness is not None:
         bg_faces *= darkness
+        warn(
+            (
+                "The `darkness` parameter will be deprecated in release 0.13. "
+                "We recommend setting `darkness` to None"
+            ),
+            DeprecationWarning,
+        )
 
     face_colors = plt.cm.gray_r(bg_faces)
 


Test patch:
diff --git a/nilearn/plotting/tests/test_html_surface.py b/nilearn/plotting/tests/test_html_surface.py
--- a/nilearn/plotting/tests/test_html_surface.py
+++ b/nilearn/plotting/tests/test_html_surface.py
@@ -61,6 +61,17 @@ def test_get_vertexcolor():
         bg_map=bg_map_scaled)
     assert len(vertexcolors_manually_rescaled) == len(mesh[0])
     assert vertexcolors_manually_rescaled != vertexcolors_auto_normalized
+    with pytest.warns(
+        DeprecationWarning,
+        match=(
+            "The `darkness` parameter will be deprecated in release 0.13. "
+            "We recommend setting `darkness` to None"
+        ),
+    ):
+        vertexcolors = html_surface._get_vertexcolor(
+            surf_map, colors['cmap'], colors['norm'],
+            absolute_threshold=colors['abs_threshold'],
+            bg_map=bg_map, darkness=0.5)
 
 
 def test_check_mesh():
diff --git a/nilearn/plotting/tests/test_surf_plotting.py b/nilearn/plotting/tests/test_surf_plotting.py
--- a/nilearn/plotting/tests/test_surf_plotting.py
+++ b/nilearn/plotting/tests/test_surf_plotting.py
@@ -1105,3 +1105,18 @@ def test_compute_facecolors_matplotlib():
     assert not np.allclose(
         facecolors_manually_rescaled, facecolors_auto_normalized
     )
+
+    with pytest.warns(
+        DeprecationWarning,
+        match=(
+            "The `darkness` parameter will be deprecated in release 0.13. "
+            "We recommend setting `darkness` to None"
+        ),
+    ):
+        facecolors_manually_rescaled = _compute_facecolors_matplotlib(
+            bg_map_scaled,
+            mesh[1],
+            len(mesh[0]),
+            0.5,
+            alpha,
+        )