Repository: nilearn/nilearn

Issue:
Globbing should be advertised in doc/examples.



Discussion:
It is already in doc/manipulating_visualizing/manipulating_images.rst. Mentioning where it could be added would help.

> It is already in doc/manipulating_visualizing/manipulating_images.rst. Mentioning where it could be added would help.

+1 ;)

@GaelVaroquaux, have you some specific location in mind?

> It is already in doc/manipulating_visualizing/manipulating_images.rst.
> Mentioning where it could be added would help.

Maybe in the "Getting started", where we talk about plotting, say, in a
sidebar.

We need to put ourselves in the shoes of the user. How does the user
discover this feature? I am not saying that it is easy to figure this
out, but we need to think about it.

Reviving this discussion, I think [this introductory example](https://nilearn.github.io/stable/auto_examples/00_tutorials/plot_3d_and_4d_niimg.html) would be a good candidate.

As of now, the plotting is shown on a single file fetched from neurovault, but to glob we need to fetch several files, for example, with [`nilearn.datasets.fetch_mixed_gambles`](https://nilearn.github.io/stable/modules/generated/nilearn.datasets.fetch_mixed_gambles.html#nilearn-datasets-fetch-mixed-gambles). So if this sounds good I could:

- swap the [`datasets.fetch_neurovault_motor_task`](https://nilearn.github.io/stable/modules/generated/nilearn.datasets.fetch_neurovault_motor_task.html#nilearn.datasets.fetch_neurovault_motor_task) with [`datasets.fetch_mixed_gambles`](https://nilearn.github.io/stable/modules/generated/nilearn.datasets.fetch_mixed_gambles.html#nilearn-datasets-fetch-mixed-gambles) for `n` subjects.
- show possibility of globbing over these subjects (other than the dictionary the fetcher already returns) with `image.mean_img` and plotting this mean stat map.
That sounds good though "a bit abstract" (sorry I have not had my second coffee yet), so maybe open a quick draft PR to show what you mean.
Yes, on it!

Resolving patch:
diff --git a/examples/00_tutorials/plot_nilearn_101.py b/examples/00_tutorials/plot_nilearn_101.py
--- a/examples/00_tutorials/plot_nilearn_101.py
+++ b/examples/00_tutorials/plot_nilearn_101.py
@@ -59,17 +59,49 @@
 more_smooth_anat_img = image.smooth_img(smooth_anat_img, fwhm=3)
 plotting.plot_img(more_smooth_anat_img)
 
+
+# %%
+# Globbing over multiple 3D volumes
+# ---------------------------------
+# Nilearn also supports reading multiple volumes at once,
+# using glob-style patterns.
+# For instance, we can smooth volumes from many subjects
+# at once and get a 4D image as output.
+
+# %%
+# First let's fetch Haxby dataset for subject 1 and 2
+from nilearn import datasets
+
+haxby = datasets.fetch_haxby(subjects=[1, 2])
+
+# %%
+# Now we can find the anatomical images from both
+# subjects using the `*` wildcard
+from pathlib import Path
+
+anats_all_subjects = (
+    Path(datasets.get_data_dirs()[0]) / "haxby2001" / "subj*" / "anat*"
+)
+
+# %%
+# Now we can smooth all the anatomical images at once
+anats_all_subjects_smooth = image.smooth_img(anats_all_subjects, fwhm=5)
+
+# %%
+# This is a 4D image containing one volume per subject
+print(anats_all_subjects_smooth.shape)
+
 # %%
 # Saving results to a file
 # -------------------------
 #
 # We can save any in-memory object as follows:
-from pathlib import Path
-
 output_dir = Path.cwd() / "results" / "plot_nilearn_101"
 output_dir.mkdir(exist_ok=True, parents=True)
 print(f"Output will be saved to: {output_dir}")
-more_smooth_anat_img.to_filename(output_dir / "more_smooth_anat_img.nii.gz")
+anats_all_subjects_smooth.to_filename(
+    output_dir / "anats_all_subjects_smooth.nii.gz"
+)
 
 # %%
 # Finally, calling plotting.show() is necessary to display the figure
@@ -81,8 +113,9 @@
 #
 # ______
 #
-# To recap, all the nilearn tools can take data as filenames or in-memory
-# objects, and return brain volumes as in-memory objects. These can be
+# To recap, all the nilearn tools can take data as filenames or
+# glob-style patterns or in-memory objects, and return brain
+# volumes as in-memory objects. These can be
 # passed on to other nilearn tools, or saved to disk.
 
 # sphinx_gallery_dummy_images=1


Test patch: