Repository: nilearn/nilearn

Issue:
Add a See Also section to plotting.plot_img 
**Original Title:** plotting.plot_img should be a private function

`plotting.plot_img` is not supposed to be directly called by users and should be a private function.

What version of Nilearn are you using?
Master, 0.5.2

What were you trying to do?
Used `plotting.plot_img` like I do `plotting.view_img`

What did you expect will happen?
That instead of an interactive view, I'll get a same looking static image.

What actually happened?
The image had no background.
Inconsistent and undocument return types for plot_stat_map (and probably other such API)
- Stuff returned by  `plot_stat_map` is no documented (it seems a Slicer object is returned by default)
- if output_file is passed, then a None object is returned instead

It would be nice to have the return type documented, and also we should always return the same object type (e.g a Slicer).



Discussion:
I think that it depends on what you want to do. 
If you are looking at raw MRI data you certainly don't want a background.
In this case wouldn't you use either `plot_anat` or `plot_epi` depending on the type of data?
We need a ruling on this one.
`plot_img` is used directly in a couple of examples:

02_decoding/plot_haxby_searchlight.py
plot_nilearn_101.py

that would make it a public function. but we could add a line to the docstring stating that it is a rather low-level one and for most usecases other functions might be easier to use, with a `see also` section pointing to plot_stat_map, plot_anat, and so on
Maybe the see also thing is sufficient. i'm worried of trying to issue complicated messages in docstrings.
There is something in the html doc somewhere, have you checked?

I don't understand the remark. I'm talking about function docstrings.

> I don't understand the remark. I'm talking about function docstrings.

Not everything has to be documented in the docstring. If you feel strongly about adding a 'Returns' section for all the plotting functions saying that it returns a display object, feel free to open a PR.

By the way the html doc explains all that [here](http://nilearn.github.io/manipulating_visualizing/plotting.html#adding-overlays-edges-and-contours) in some details.

On Tue, Dec 15, 2015 at 6:34 PM, Loïc Estève notifications@github.com
wrote:

> I don't understand the remark. I'm talking about function docstrings.
> 
> Not everything has to be documented in the docstring
> 
> This doesn't address the problem. How can you justify missing doc by
> pointing to some html page ? Do you mean users can't figure out what a
> function takes-in, outputs, etc. without having internet connection and
> going over the project webpage, etc. ?
> 
> If you feel strongly about adding a 'Returns' section for all the plotting
> functions saying that it returns a display object, feel free to open a PR.
> 
> If this if it's not apparent that this is an issue (inhomogeneous return
> types / value + undocumented return types / value), please feel free to
> close it.
> 
> By the way the html doc explains all that here
> http://nilearn.github.io/manipulating_visualizing/plotting.html#adding-overlays-edges-and-contours
> in some details.
> 
> —
> Reply to this email directly or view it on GitHub
> https://github.com/nilearn/nilearn/issues/911#issuecomment-164834027.

## 

Elvis Dohmatob,
_sent from my  potato..._
http://dohmatob.blogspot.fr/, https://team.inria.fr/parietal/elvis/,
https://github.com/dohmatob

I think that this kind of high-level and probably highly-used function should be well-documented.
@dohmatob can you issue a PR ?

I would like to agree that a) consistency across plotting API and b) mentionning the output variable type in the docstring appears reasonable.

I agree about documenting the return.

With regard to not returning the display object when the file is saved,
this is by design. Indeed, these duisplay objects can accumulate and
create memory leakage. We are trying to garbage collect them ASAP when
they are not needed. It's actually the sole goal of the output_file
argument.

> This doesn't address the problem. How can you justify missing doc by pointing to some html page ? Do you mean users can't figure out what a function takes-in, outputs, etc. without having internet connection and going over the project webpage, etc. ?

I am just saying that you have to find the right trade-off between what you put in docstrings and what you put in your online doc. In this particular case, adding a 'Returns' section sounds reasonable. IMHO having some detailed explanation in the docstring similarly to http://nilearn.github.io/manipulating_visualizing/plotting.html#displaying-or-saving-to-an-image-file, not that much.

I can work on this

Resolving patch:
diff --git a/nilearn/plotting/img_plotting.py b/nilearn/plotting/img_plotting.py
--- a/nilearn/plotting/img_plotting.py
+++ b/nilearn/plotting/img_plotting.py
@@ -175,6 +175,13 @@ def _plot_img_with_bg(img, bg_img=None, cut_coords=None,
     display_factory : function, default=get_slicer
         Takes a display_mode argument and return a display class.
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoSlicer` or \
+        :class:`~nilearn.plotting.displays.OrthoProjector` or None
+        An instance of the OrthoSlicer or OrthoProjector class depending on the
+        function defined in ``display_factory``. If ``output_file`` is defined,
+        None is returned.
     """
     show_nan_msg = False
     if vmax is not None and np.isnan(vmax):
@@ -295,6 +302,29 @@ def plot_img(img, cut_coords=None, output_file=None, display_mode='ortho',
     kwargs : extra keyword arguments, optional
         Extra keyword arguments passed to matplotlib.pyplot.imshow.
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoSlicer` or None
+        An instance of the OrthoSlicer class. If ``output_file`` is defined,
+        None is returned.
+
+    .. note::
+
+        This is a low-level function. For most use cases, other plotting
+        functions might be more appropriate and easier to use.
+
+    .. seealso::
+
+        :func:`~nilearn.plotting.plot_anat`
+            To simply plot anatomical images
+        :func:`~nilearn.plotting.plot_epi`
+            To simply plot raw EPI images
+        :func:`~nilearn.plotting.plot_roi`
+            To simply plot max-prob atlases (3D images)
+        :func:`~nilearn.plotting.plot_prob_atlas`
+            To simply plot probabilistic atlases (4D images)
+        :mod:`nilearn.plotting`
+            See API reference for other options
     """
     display = _plot_img_with_bg(
         img, cut_coords=cut_coords,
@@ -484,6 +514,12 @@ def plot_anat(anat_img=MNI152TEMPLATE, cut_coords=None,
     %(vmin)s
     %(vmax)s
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoSlicer` or None
+        An instance of the OrthoSlicer class. If ``output_file`` is defined,
+        None is returned.
+
     Notes
     -----
     Arrays should be passed in numpy convention: (x, y, z) ordered.
@@ -548,6 +584,12 @@ def plot_epi(epi_img=None, cut_coords=None, output_file=None,
     %(vmax)s
     %(radiological)s
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoSlicer` or None
+        An instance of the OrthoSlicer class. If ``output_file`` is defined,
+        None is returned.
+
     Notes
     -----
     Arrays should be passed in numpy convention: (x, y, z) ordered.
@@ -671,6 +713,12 @@ def plot_roi(roi_img, bg_img=MNI152TEMPLATE, cut_coords=None,
         Default=2.5.
     %(radiological)s
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoSlicer` or None
+        An instance of the OrthoSlicer class. If ``output_file`` is defined,
+        None is returned.
+
     Notes
     -----
     A small threshold is applied by default to eliminate numerical
@@ -792,6 +840,12 @@ def plot_prob_atlas(maps_img, bg_img=MNI152TEMPLATE, view_type='auto',
         Alpha sets the transparency of the color inside the filled contours.
     %(radiological)s
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoSlicer` or None
+        An instance of the OrthoSlicer class. If ``output_file`` is defined,
+        None is returned.
+
     See Also
     --------
     nilearn.plotting.plot_roi : To simply plot max-prob atlases (3D images)
@@ -947,6 +1001,12 @@ def plot_stat_map(stat_map_img, bg_img=MNI152TEMPLATE, cut_coords=None,
         Default='continuous'.
     %(radiological)s
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoSlicer` or None
+        An instance of the OrthoSlicer class. If ``output_file`` is defined,
+        None is returned.
+
     Notes
     -----
     Arrays should be passed in numpy convention: (x, y, z) ordered.
@@ -1057,7 +1117,13 @@ def plot_glass_brain(stat_map_img,
     %(resampling_interpolation)s
         Default='continuous'.
     %(radiological)s 
-        
+
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoProjector` or None
+        An instance of the OrthoProjector class. If ``output_file`` is defined,
+        None is returned.
+
     Notes
     -----
     Arrays should be passed in numpy convention: (x, y, z) ordered.
@@ -1192,6 +1258,12 @@ def plot_connectome(adjacency_matrix, node_coords,
         Default=False.
     %(radiological)s
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoProjector` or None
+        An instance of the OrthoProjector class. If ``output_file`` is defined,
+        None is returned.
+
     See Also
     --------
     nilearn.plotting.find_parcellation_cut_coords : Extraction of node
@@ -1287,6 +1359,11 @@ def plot_markers(node_values, node_coords, node_size='auto',
         Default=True.
     %(radiological)s
 
+    Returns
+    -------
+    display : :class:`~nilearn.plotting.displays.OrthoProjector` or None
+        An instance of the OrthoProjector class. If ``output_file`` is defined,
+        None is returned.
     """
     node_values = np.array(node_values).flatten()
     node_coords = np.array(node_coords)


Test patch: