[DOC] link surface terms to glossary

doc/connectivity/connectome_extraction.rst

@@ -28,7 +28,7 @@ Functional connectivity can be obtained by estimating a covariance
 (or correlation) matrix for signals from different brain
 regions decomposed, for example on :term:`resting-state` or naturalistic-stimuli datasets.
 The same information can be represented as a weighted graph,
-vertices being brain regions, weights on edges being covariances
+:term:`vertices<vertex>` being brain regions, weights on edges being covariances
 (gaussian graphical model). However, coefficients in a covariance matrix
 reflect direct as well as indirect connections. Covariance matrices form
 very dense brain connectomes, and it is rather difficult to extract from

doc/glossary.rst

@@ -90,6 +90,10 @@ If you wish to add a missing term, please
         Erosion uses a structuring element for probing and reducing the shapes
         contained in the input image.
 
+    faces
+        When referring to surface data, a face corresponds to one of the triangles
+        of a triangular :term:`mesh`.
+
     FDR correction
         `False discovery rate`_ controlling procedures are designed to control
         the expected proportion of "discoveries" (rejected null hypotheses)
@@ -170,6 +174,16 @@ If you wish to add a missing term, please
         brain activity by recording magnetic fields produced by electrical currents
         occurring naturally in the brain.
 
+    mesh
+        In the context of brain surface data, a mesh refers to a 3D representation
+        of the brain's surface geometry.
+        It is a collection of vertices, edges, and faces
+        that define the shape and structure of the brain's outer surface.
+        Each :term:`vertex` represents a point in 3D space,
+        and edges connect these vertices to form a network.
+        :term:`Faces<faces>` are then created by connecting
+        three or more vertices to form triangles.
+
     MNI
         MNI stands for "Montreal Neurological Institute". Usually, this is
         used to reference the MNI space/template. The current standard MNI
@@ -310,6 +324,11 @@ If you wish to add a missing term, please
         `Voxel-Based Morphometry`_ measures differences in local concentrations of brain
         tissue, through a voxel-wise comparison of multiple brain images.
 
+    vertex
+        A vertex (plural vertices) represents the coordinate
+        of an angle of :term:`face<faces>`
+        on a triangular :term:`mesh` in 3D space.
+
     voxel
         A voxel represents a value on a regular grid in 3D space.
 

examples/01_plotting/plot_3d_map_to_surface_projection.py

@@ -26,11 +26,11 @@
 fsaverage = datasets.fetch_surf_fsaverage()
 
 # %%
-# Use mesh curvature to display useful anatomical information
+# Use :term:`mesh` curvature to display useful anatomical information
 # on inflated meshes
 #
 # Here, we load the curvature map of the hemisphere under study,
-# and define a surface map whose value for a given vertex is
+# and define a surface map whose value for a given :term:`vertex` is
 # 1 if the curvature is positive, -1 if the curvature is negative.
 
 import numpy as np

examples/01_plotting/plot_surf_atlas.py

@@ -88,9 +88,10 @@
 # Display connectome from surface parcellation
 #
 # The following code extracts 3D coordinates of surface parcels (a.k.a. labels
-# in the Freesurfer naming convention). To do so we load the pial surface
-# of fsaverage subject, get the vertices contained in each parcel and compute
-# the mean location to obtain the coordinates.
+# in the Freesurfer naming convention).
+# To do so we load the pial surface of fsaverage subject,
+# get the :term:`vertices<vertex>` contained in each parcel
+# and compute the mean location to obtain the coordinates.
 
 import numpy as np
 

examples/01_plotting/plot_surf_stat_map.py

@@ -136,9 +136,9 @@
 )
 
 # %%
-# Using a flat mesh can be useful in order to easily locate the area
+# Using a flat :term:`mesh` can be useful in order to easily locate the area
 # of interest on the cortex. To make this plot easier to read,
-# we use the mesh curvature as a background map.
+# we use the :term:`mesh` curvature as a background map.
 
 bg_map = np.sign(surface.load_surf_data(fsaverage['curv_left']))
 # np.sign yields values in [-1, 1]. We rescale the background map

examples/04_glm_first_level/plot_localizer_surface_analysis.py

@@ -17,7 +17,7 @@
 The result of the analysis are statistical maps that are defined on the brain
 mesh. We display them using Nilearn capabilities.
 
-The projection of :term:`fMRI` data onto a given brain mesh requires
+The projection of :term:`fMRI` data onto a given brain :term:`mesh` requires
 that both are initially defined in the same space.
 
 * The functional data should be coregistered to the anatomy from which the mesh
@@ -59,9 +59,11 @@
 # Project the :term:`fMRI` image to the surface
 # ---------------------------------------------
 #
-# For this we need to get a mesh representing the geometry of the surface. We
-# could use an individual mesh, but we first resort to a standard mesh, the
-# so-called fsaverage5 template from the FreeSurfer software.
+# For this we need to get a :term:`mesh`
+# representing the geometry of the surface.
+# We could use an individual :term:`mesh`,
+# but we first resort to a standard :term:`mesh`,
+# the so-called fsaverage5 template from the FreeSurfer software.
 import nilearn
 
 fsaverage = nilearn.datasets.fetch_surf_fsaverage()

examples/07_advanced/plot_surface_bids_analysis.py

@@ -10,7 +10,8 @@
 1. Download an :term:`fMRI` :term:`BIDS` dataset
 with two language conditions to contrast.
 2. Project the data to a standard mesh, fsaverage5,
-aka the Freesurfer template mesh downsampled to about 10k nodes per hemisphere.
+aka the Freesurfer template :term:`mesh` downsampled
+to about 10k nodes per hemisphere.
 3. Run the first level model objects.
 4. Fit a second level model on the fitted first level models.
 

maint_tools/check_glossary_term.py

@@ -12,6 +12,8 @@
 from docstring_parser.common import DocstringStyle
 from rich import print
 
+SEARCH = ["faces", "vertex", "mesh", "vertices"]
+
 
 def root_dir() -> Path:
     """Return path to root directory."""
@@ -25,6 +27,9 @@ def glossary_file() -> Path:
 
 def get_terms_in_glossary() -> list[str]:
     """Return list of terms in glossary.rst."""
+    if len(SEARCH) > 0:
+        return SEARCH
+
     terms = []
 
     track = False

nilearn/datasets/atlas.py

@@ -1766,9 +1766,10 @@ def fetch_atlas_surf_destrieux(
             - 'map_left': :class:`numpy.ndarray` of :obj:`int`, maps each
               vertex on the left hemisphere of the fsaverage5 surface to its
               index into the list of label name.
-            - 'map_right': :class:`numpy.ndarray` of :obj:`int`, maps each
-              vertex on the right hemisphere of the fsaverage5 surface to its
-              index into the list of label name.
+            - 'map_right': :class:`numpy.ndarray` of :obj:`int`,
+              maps each :term:`vertex` on the right hemisphere
+              of the fsaverage5 surface to its index
+              into the list of label name.
             - 'description': :obj:`str`, description of the dataset.
 
     See Also

nilearn/datasets/struct.py

@@ -875,7 +875,8 @@ def fetch_surf_fsaverage(mesh="fsaverage5", data_dir=None):
     Parameters
     ----------
     mesh : str, default='fsaverage5'
-        Which mesh to fetch. Should be one of the following values:
+        Which :term:`mesh` to fetch.
+        Should be one of the following values:
         %(fsaverage_options)s
     %(data_dir)s
 
@@ -887,21 +888,26 @@ def fetch_surf_fsaverage(mesh="fsaverage5", data_dir=None):
          - 'area_right': Gifti file, right hemisphere area data
          - 'curv_left': Gifti file, left hemisphere curvature data
          - 'curv_right': Gifti file, right hemisphere curvature data
-         - 'flat_left': Gifti file, left hemisphere flat surface mesh
-         - 'flat_right': Gifti file, right hemisphere flat surface mesh
-         - 'pial_left': Gifti file, left hemisphere pial surface mesh
-         - 'pial_right': Gifti file, right hemisphere pial surface mesh
-         - 'infl_left': Gifti file, left hemisphere inflated pial surface mesh
+         - 'flat_left': Gifti file, left hemisphere flat surface :term:`mesh`
+         - 'flat_right': Gifti file, right hemisphere flat surface :term:`mesh`
+         - 'pial_left': Gifti file, left hemisphere pial surface :term:`mesh`
+         - 'pial_right': Gifti file, right hemisphere pial surface :term:`mesh`
+         - 'infl_left': Gifti file, left hemisphere inflated pial surface
+           :term:`mesh`
          - 'infl_right': Gifti file, right hemisphere inflated pial
-                         surface mesh
-         - 'sphere_left': Gifti file, left hemisphere sphere surface mesh
-         - 'sphere_right': Gifti file, right hemisphere sphere surface mesh
+                         surface :term:`mesh`
+         - 'sphere_left': Gifti file, left hemisphere sphere surface
+           :term:`mesh`
+         - 'sphere_right': Gifti file, right hemisphere sphere surface
+           :term:`mesh`
          - 'sulc_left': Gifti file, left hemisphere sulcal depth data
          - 'sulc_right': Gifti file, right hemisphere sulcal depth data
          - 'thick_left': Gifti file, left hemisphere cortical thickness data
          - 'thick_right': Gifti file, right hemisphere cortical thickness data
-         - 'white_left': Gifti file, left hemisphere white surface mesh
-         - 'white_right': Gifti file, right hemisphere white surface mesh
+         - 'white_left': Gifti file, left hemisphere
+           white surface :term:`mesh`
+         - 'white_right': Gifti file, right hemisphere*
+           white surface :term:`mesh`
 
     References
     ----------

nilearn/experimental/surface/_surface_image.py

@@ -14,7 +14,8 @@
 
 
 class Mesh(abc.ABC):
-    """A surface mesh, having vertex coordinates and faces(triangles)."""
+    """A surface :term:`mesh` having vertex, \
+    coordinates and faces (triangles)."""
 
     n_vertices: int
 

nilearn/mass_univariate/permuted_least_squares.py

@@ -348,9 +348,9 @@ def permuted_ols(
         to the explanatory and confounding variates.
 
         In a group-level analysis, the samples will typically be voxels
-        (for volumetric data) or vertices (for surface data), while the
-        descriptors will generally be images, such as run-wise z-statistic
-        maps.
+        (for volumetric data) or :term:`vertices<vertex>` (for surface data),
+        while the descriptors will generally be images,
+        such as run-wise z-statistic maps.
 
     confounding_vars : array-like, shape=(n_samples, n_covars), optional
         Confounding variates (covariates), fitted but not tested.

nilearn/plotting/html_surface.py

@@ -333,26 +333,27 @@ def view_surf(surf_mesh, surf_map=None, bg_map=None, threshold=None,
     Parameters
     ----------
     surf_mesh : str or list of two numpy.ndarray
-        Surface mesh geometry, can be a file (valid formats are
-        .gii or Freesurfer specific files such as .orig, .pial,
-        .sphere, .white, .inflated) or
+        Surface :term:`mesh` geometry, can be a file
+        (valid formats are .gii or Freesurfer specific files
+        such as .orig, .pial, .sphere, .white, .inflated) or
         a list of two Numpy arrays, the first containing the x-y-z coordinates
-        of the mesh vertices, the second containing the indices
-        (into coords) of the mesh faces.
+        of the :term:`mesh` vertices, the second containing the indices
+        (into coords) of the :term:`mesh` :term:`faces`.
 
     surf_map : str or numpy.ndarray, optional
-        Data to be displayed on the surface mesh. Can be a file (valid formats
-        are .gii, .mgz, .nii, .nii.gz, or Freesurfer specific files such as
+        Data to be displayed on the surface :term:`mesh`.
+        Can be a file (valid formats are .gii, .mgz, .nii, .nii.gz,
+        or Freesurfer specific files such as
         .thickness, .area, .curv, .sulc, .annot, .label) or
         a Numpy array
 
     bg_map : str or numpy.ndarray, default=None
-        Background image to be plotted on the mesh underneath the
-        surf_data in greyscale, most likely a sulcal depth map for
+        Background image to be plotted on the :term:`mesh` underneath
+        the surf_data in greyscale, most likely a sulcal depth map for
         realistic shading.
-        If the map contains values outside [0, 1], it will be
-        rescaled such that all values are in [0, 1]. Otherwise,
-        it will not be modified.
+        If the map contains values outside [0, 1],
+        it will be rescaled such that all values are in [0, 1].
+        Otherwise, it will not be modified.
 
     %(bg_on_data)s
 

nilearn/plotting/js_plotting_utils.py

@@ -129,7 +129,7 @@ def decode(b, dtype):
 
 
 def mesh_to_plotly(mesh):
-    """Convert a mesh to plotly format."""
+    """Convert a :term:`mesh` to plotly format."""
     mesh = surface.load_surf_mesh(mesh)
     x, y, z = map(encode, np.asarray(mesh[0].T, dtype='<f4'))
     i, j, k = map(encode, np.asarray(mesh[1].T, dtype='<i4'))