nilearn · Remi-Gau · May 21, 2025 · May 15, 2025 · May 15, 2025 · May 15, 2025
diff --git a/doc/changes/latest.rst b/doc/changes/latest.rst
@@ -119,4 +119,8 @@ Changes
 
 - :bdg-danger:`Deprecation` For version >=0.13.2 :func:`~nilearn.interfaces.bids.parse_bids_filename` will return a dictionary whose keys correspond to valid BIDS terms. (:gh:`5320` by `Rémi Gau`_).
 
+- :bdg-danger:`Deprecation` Using the transform method of nifti maskers on 3D images now returns 1D arrays. Similarly, using the transform method of surface maskers on 1D surface images now returns 1D arrays.  (:gh:`5381` by `Rémi Gau`_).
+
+- :bdg-danger:`Deprecation` Using the inverse_transform method of surface maskers on 1D arrays now returns surface images  (:gh:`5381` by `Rémi Gau`_).
+
 - :bdg-danger:`Deprecation` The default for ``slice_time_ref`` in :func:`~nilearn.glm.first_level.first_level_from_bids` was changed to ``None`` (:gh:`5382` by `Rémi Gau`_).
diff --git a/doc/manipulating_images/manipulating_images.rst b/doc/manipulating_images/manipulating_images.rst
@@ -1,8 +1,8 @@
 .. _data_manipulation:
 
-=====================================================================
+=============================================================
 Manipulating images: resampling, smoothing, masking, ROIs...
-=====================================================================
+=============================================================
 
 This chapter discusses how nilearn can be used to do simple operations on
 brain images.
@@ -11,7 +11,7 @@ brain images.
 .. _preprocessing_functions:
 
 Functions for data preparation and image transformation
-=========================================================
+=======================================================
 
 Nilearn comes with many simple functions for simple data preparation and
 transformation. Note that if you want to perform these operations while
@@ -106,7 +106,7 @@ of the transformation matrix (i.e., affine).
   :ref:`An example illustrating affine transforms on data and bounding boxes <sphx_glr_auto_examples_06_manipulating_images_plot_affine_transformation.py>`
 
 Accessing individual volumes in 4D images
-===========================================
+=========================================
 
 * :func:`nilearn.image.index_img`: selects one or more volumes in a 4D
   image.
@@ -139,7 +139,7 @@ Accessing individual volumes in 4D images
 .. _computing_and_applying_mask:
 
 Computing and applying spatial masks
-=====================================
+====================================
 
 Relevant functions:
 
@@ -157,7 +157,7 @@ Relevant functions:
 
 
 Extracting a brain mask
-------------------------
+-----------------------
 
 If we do not have a spatial mask of the target regions, a brain mask
 can be computed from the data:
@@ -183,7 +183,7 @@ can be computed from the data:
 .. _mask_4d_2_3d:
 
 Masking data: from 4D Nifti images to 2D data arrays
----------------------------------------------------------------
+----------------------------------------------------
 
 :term:`fMRI` data is usually represented as a 4D block of data: 3 spatial
 dimensions and one time dimension. In practice, we are usually
@@ -211,7 +211,7 @@ do it manually below:
 
 
 Image operations: creating a ROI mask manually
-===============================================
+==============================================
 
 A region of interest (ROI) mask can be computed for instance with a
 statistical test. This requires a chain of image

diff --git a/doc/manipulating_images/masker_objects.rst b/doc/manipulating_images/masker_objects.rst
@@ -1,8 +1,8 @@
 .. _masker_objects:
 
-=====================================================================
+================================================================
 From neuroimaging volumes to data matrices: the masker objects
-=====================================================================
+================================================================
 
 This chapter introduces the maskers: objects that go from
 neuroimaging volumes, on the disk or in memory, to data matrices, eg of
@@ -24,10 +24,10 @@ the raw neuroimaging data in 3D space into the units of observation
 relevant for the research questions at hand.
 
 .. tip::
-    Masker objects can transform both 3D and 4D image objects.
-    Transforming a 4D image produces a 2D (samples x features) matrix.
-    Currently, transforming a 3D image also produces a 2D (1 x features) matrix,
-    but starting in version 0.12, it will produce a 1D (features) array.
+    Masker objects can transform both 3D and 4D image objects :
+
+    - transforming a 3D image produces a 1D (features,) array,
+    - transforming a 4D image produces a 2D (samples, features) array.
 
 
 .. |niimgs| image:: ../images/niimgs.jpg
@@ -294,8 +294,6 @@ properties, before conversion to :term:`voxel` signals.
    :func:`nilearn.signal.clean`
 
 
-
-
 Resampling: resizing and changing resolutions of images
 .......................................................
 
@@ -343,9 +341,10 @@ an excerpt of :ref:`the example performing Anova-SVM on the Haxby data
 |
 
 .. tip::
-    Masker objects can inverse-transform both 1D and 2D arrays.
-    Inverse-transforming a 2D array produces a 4D (X x Y x Z x samples) image,
-    while inverse-transforming a 1D array produces a 3D (X x Y x Z) image.
+    Masker objects can inverse-transform both 1D and 2D arrays :
+
+    - inverse-transforming a 2D array produces a 4D (X x Y x Z x samples) image,
+    - inverse-transforming a 1D array produces a 3D (X x Y x Z) image.
 
 .. topic:: **Examples to better understand the NiftiMasker**
 
@@ -445,8 +444,17 @@ as to facilitate the computation of :term:`voxel` signals in multi-subjects sett
 While :class:`NiftiMasker`, :class:`NiftiLabelsMasker` and
 :class:`NiftiMapsMasker` work with 3D inputs (single brain volume) or 4D inputs
 (sequence of brain volumes in time for one subject), :class:`MultiNiftiMasker`,
-:class:`MultiNiftiLabelsMasker` and :class:`MultiNiftiMapsMasker` expect 5D
-inputs (list of sequences of brain volumes).
+:class:`MultiNiftiLabelsMasker` and :class:`MultiNiftiMapsMasker`
+can also handle list of 3D or 4D image objects.
+
+.. tip::
+    MultiMasker objects can transform both 3D, 4D,
+    as well as list of 3D or 4D image objects :
+
+    - transforming a 3D image produces a 1D (features,) array,
+    - transforming a 4D image produces a 2D (samples, features) array,
+    - transforming a list of 3D image produces a list of 1D (features,) array,
+    - transforming a list of 4D image produces a list of 2D (samples, features) array.
 
 :class:`MultiNiftiMasker` Usage
 -------------------------------
@@ -470,7 +478,7 @@ for each subject.
     * :ref:`sphx_glr_auto_examples_03_connectivity_plot_atlas_comparison.py`
 
 :class:`MultiNiftiMapsMasker` Usage
--------------------------------------
+-----------------------------------
 
 :class:`MultiNiftiMapsMasker` extracts signals regions defined by maps
 for each subject.
@@ -504,3 +512,27 @@ seed position is used.
 .. topic:: **Examples**
 
   * :ref:`sphx_glr_auto_examples_03_connectivity_plot_sphere_based_connectome.py`
+
+
+Extraction of signals from surface images\  :class:`SurfaceMasker`, :class:`SurfaceLabelsMasker`, :class:`SurfaceMapsMasker`
+============================================================================================================================
+
+The purpose of :class:`SurfaceMasker`, :class:`SurfaceLabelsMasker`, :class:`SurfaceMapsMasker`
+is to mirror the capabilities of
+:class:`NiftiMasker`, :class:`NiftiLabelsMasker` and :class:`NiftiMapsMasker`
+but to extract data from :class:`~nilearn.surface.SurfaceImage`.
+
+They can perform data extraction from 1D surface data (n_vertices),
+2D surface data (n_vertices x samples)
-2D surface data (n_vertices x samples)
+2D surface data (n_vertices, samples)
-2D surface data (n_vertices x samples)
+2D surface data (n_vertices, samples)
+as well as list of 1D or 2D surface data with the same underlying mesh.
+
+.. tip::
+    Surface masker objects can transform both 1D, 2D,
+    as well as list of 1D or 2D surface image objects.
+    Transforming a 1D image produces a 1D (features,) array.
+    All other input will produce a 1D (samples, features) array..
-    All other input will produce a 1D (samples, features) array..
+    All other input will produce a 1D (samples, features) array.
-    All other input will produce a 1D (samples, features) array..
+    All other input will produce a 1D (samples, features) array.
+
+    Surface masker objects can inverse-transform both 1D and 2D arrays :
+
+    - inverse-transforming a 1D array produces a 1D (n_vertices,) image,
+    - inverse-transforming a 2D array produces a 2D (n_vertices, samples) image.
diff --git a/nilearn/_utils/docs.py b/nilearn/_utils/docs.py
@@ -973,6 +973,19 @@ def custom_function(vertices):
     "mask_img :", "mask :"
 )
 
+# signals for inverse transform
+docdict["signals_inv_transform"] = """
+signals : 1D/2D :obj:`numpy.ndarray`
+    Extracted signal.
+    If a 1D array is provided,
+    then the shape should be (number of elements,).
+    If a 2D array is provided,
+    then the shape should be (number of scans, number of elements).
+"""
+docdict["region_signals_inv_transform"] = docdict["signals_inv_transform"]
+docdict["x_inv_transform"] = docdict["signals_inv_transform"]
+
+
 # smoothing_fwhm
 docdict["smoothing_fwhm"] = """
 smoothing_fwhm : :obj:`float` or :obj:`int` or None, optional.
@@ -1239,7 +1252,7 @@ def custom_function(vertices):
 
 ##############################################################################
 #
-# Other values definitions
+# Other values definitions: return values, attributes...
 #
 
 # atlas_type
@@ -1358,6 +1371,29 @@ def custom_function(vertices):
 
 """
 
+# image returned Nifti maskers by inverse_transform
+docdict["img_inv_transform_nifti"] = """img : :obj:`nibabel.nifti1.Nifti1Image`
+        Transformed image in brain space.
+        Output shape for :
+
+        - 1D array : 3D :obj:`nibabel.nifti1.Nifti1Image` will be returned.
+        - 2D array : 4D :obj:`nibabel.nifti1.Nifti1Image` will be returned.
+
+        See :ref:`extracting_data`.
+        """
+# image returned surface maskers by inverse_transform
+docdict[
+    "img_inv_transform_surface"
+] = """img : :obj:`~nilearn.surface.SurfaceImage`
+        Signal for each vertex projected on the mesh.
+        Output shape for :
+
+        - 1D array : 1D :obj:`~nilearn.surface.SurfaceImage` will be returned.
+        - 2D array : 2D :obj:`~nilearn.surface.SurfaceImage` will be returned.
+
+        See :ref:`extracting_data`.
+        """
+
 # atlas labels
 docdict["labels"] = """'labels' : :obj:`list` of :obj:`str`
         List of the names of the regions."""
@@ -1380,6 +1416,47 @@ def custom_function(vertices):
         Formatted according to 'dseg.tsv' format from
         `BIDS <https://bids-specification.readthedocs.io/en/latest/derivatives/imaging.html#common-image-derived-labels>`_."""
 
+# signals returned Nifti maskers by transform, fit_transform...
+docdict["signals_transform_nifti"] = """signals : :obj:`numpy.ndarray`
+        Signal for each :term:`voxel`.
+        Output shape for :
+
+        - 3D images: (number of elements,) array
+        - 4D images: (number of scans, number of elements) array
+        """
+# signals returned Mulit Nifti maskers by transform, fit_transform...
+docdict[
+    "signals_transform_multi_nifti"
+] = """signals : :obj:`list` of :obj:`numpy.ndarray` or :obj:`numpy.ndarray`
+        Signal for each :term:`voxel`.
+        Output shape for :
+
+        - 3D images: (number of elements,) array
+        - 4D images: (number of scans, number of elements) array
+        - list of 3D images: list of (number of elements,) array
+        - list of 4D images: list of (number of scans, number of elements)
+          array
+        """
+# signals returned Mulit Nifti maskers by transform, fit_transform...
+docdict[
+    "signals_transform_imgs_multi_nifti"
+] = """signals : :obj:`list` of :obj:`numpy.ndarray`
+        Signal for each :term:`voxel`.
+        Output shape for :
+
+        - list of 3D images: list of (number of elements,) array
+        - list of 4D images: list of (number of scans, number of elements)
+          array
        """
+# signals returned surface maskers by transform, fit_transform...
+docdict["signals_transform_surface"] = """signals : :obj:`numpy.ndarray`
+        Signal for each element.
+        Output shape for :
+
+        - 1D images: (number of elements,) array
+        - 2D images: (number of scans, number of elements) array
+        """
+
 # template
 docdict["template"] = """'template' : :obj:`str`
         The standardized space of analysis