Repository: nilearn/nilearn

Issue:
control of background image intensity in plotting.plot_stat_map
currently there does not appear to be a way to control the intensity of the background image when using plot_stat_map - this leads to background images that are often too dark. it would be nice to have a separate knob to control intensity of the bg image.



Discussion:
I've encountered this issue several time when preparing slides; So far the official solution was to use the 'backstage' function _plot_img_with_bg, and use the bg_vmax argument like in the following script:

``` python
from nilearn.plotting.img_plotting import _plot_img_with_bg, _load_anat
bg_img, black_bg, bg_vmin, bg_vmax = _load_anat(
        anat_img, dim=True, black_bg='auto')
display = _plot_img_with_bg(
        img=os.path.join(write_dir, 'weight_%03d.nii' % n_subjects),
        bg_img=bg_img,
        display_mode='z', 
        cut_coords=[0],
        threshold=0,
        figure=fig, vmax=3., bg_vmax=.8, bg_vmin=bg_vmin,
        black_bg=black_bg, resampling_interpolation='continuous')
```

The question is to have a compromise between a simple API on the one hand and allowing these tweaks for nice rendering. Given that plot_stat_map API is fairly complex already, your request is not a big change though.

thanks! yes, I think it would be good to add it into the plot_stat_map function directly
cheers
rp

> On Sep 9, 2015, at 1:18 PM, bthirion notifications@github.com wrote:
> 
> I've encountered this issue several time when preparing slides; So far the official solution was to use the 'backstage' function _plot_img_with_bg, and use the bg_vmax argument like in the following script:
> 
> from nilearn.plotting.img_plotting import plot_img_with_bg, _load_anat
> bg_img, black_bg, bg_vmin, bg_vmax = _load_anat(
> anat_img, dim=True, black_bg='auto')
> display = _plot_img_with_bg(
> img=os.path.join(write_dir, 'weight%03d.nii' % n_subjects),
> bg_img=bg_img,
> display_mode='z', 
> cut_coords=[0],
> threshold=0,
> figure=fig, vmax=3., bg_vmax=.8, bg_vmin=bg_vmin,
> black_bg=black_bg, resampling_interpolation='continuous')
> 
> The question is to have a compromise between a simple API on the one hand and allowing these tweaks for nice rendering. Given that plot_stat_map API is fairly complex already, your request is not a big change through.
> 
> —
> Reply to this email directly or view it on GitHub https://github.com/nilearn/nilearn/issues/778#issuecomment-139034518.

—
Russell A. Poldrack
Professor of Psychology
Bldg. 420, Jordan Hall
Stanford University
Stanford, CA 94305

poldrack@stanford.edu
http://www.poldracklab.org/

We should do this during the sprint.

I can do that one  i think.

Hm, I've just realized that the `dim` parameter simply does the trick.  I'm just going to add relevant documentation.

But dim also affects the anat i.e reducing the contrast in the anat, doesn't it?

> But dim also affects the anat i.e reducing the contrast in the anat,
> doesn't it?

It affects only the anat, but I think that this is what we want here.


Resolving patch:
diff --git a/examples/manipulating_visualizing/plot_dim_plotting.py b/examples/manipulating_visualizing/plot_dim_plotting.py
new file mode 100644
--- /dev/null
+++ b/examples/manipulating_visualizing/plot_dim_plotting.py
@@ -0,0 +1,54 @@
+"""
+Controling the contrast of the background when plotting
+=========================================================
+
+The `dim` argument controls the contrast of the background.
+
+*dim* modifies the contrast of this image: dim=0 leaves the image
+unchanged, negative values of *dim* enhance it, and positive values
+decrease it (dim the background).
+
+This *dim* argument may also be useful for the plot_roi function used to
+display ROIs on top of a background image.
+"""
+
+# Retrieve the data: the localizer dataset with contrast maps
+
+from nilearn import datasets
+
+localizer_dataset = datasets.fetch_localizer_contrasts(
+    ["left vs right button press"],
+    n_subjects=2,
+    get_anats=True,
+    get_tmaps=True)
+localizer_anat_filename = localizer_dataset.anats[1]
+localizer_tmap_filename = localizer_dataset.tmaps[1]
+
+# Plotting: vary the 'dim' of the background
+from nilearn import plotting
+
+plotting.plot_stat_map(localizer_tmap_filename,
+                       bg_img=localizer_anat_filename,
+                       cut_coords=(36, -27, 66),
+                       threshold=3, title="dim=-.5",
+                       dim=-.5)
+
+plotting.plot_stat_map(localizer_tmap_filename,
+                       bg_img=localizer_anat_filename,
+                       cut_coords=(36, -27, 66),
+                       threshold=3, title="dim=0",
+                       dim=0)
+
+plotting.plot_stat_map(localizer_tmap_filename,
+                       bg_img=localizer_anat_filename,
+                       cut_coords=(36, -27, 66),
+                       threshold=3, title="dim=.5",
+                       dim=.5)
+
+plotting.plot_stat_map(localizer_tmap_filename,
+                       bg_img=localizer_anat_filename,
+                       cut_coords=(36, -27, 66),
+                       threshold=3, title="dim=1",
+                       dim=1)
+
+plotting.show()


Test patch: