code: def plot_surf_stat_map(
      surf_mesh,
      stat_map,
      bg_map=None,
      hemi="left",
      view="lateral",
      engine="matplotlib",
      threshold=None,
      alpha="auto",
      vmin=None,
      vmax=None,
      cmap="cold_hot",
      colorbar=True,
      symmetric_cbar="auto",
      cbar_tick_format="auto",
      bg_on_data=False,
      darkness=0.7,
      title=None,
      title_font_size=18,
      output_file=None,
      axes=None,
      figure=None,
      **kwargs,
  ):
      """Plot a stats map on a surface :term:`mesh` with optional background.
  
      .. versionadded:: 0.3
  
      Parameters
      ----------
      surf_mesh : str or list of two numpy.ndarray or Mesh
          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 :term:`mesh` :term:`vertices<vertex>`,
          the second containing the indices (into coords)
          of the :term:`mesh` :term:`faces`,
          or a Mesh object with "coordinates" and "faces" attributes.
  
      stat_map : str or numpy.ndarray
          Statistical map 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 with a value for each :term:`vertex` of the `surf_mesh`.
  
      bg_map : str or numpy.ndarray, optional
          Background image to be plotted on the :term:`mesh` underneath
          the stat_map 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.
  
      %(hemi)s
      %(view)s
      engine : {'matplotlib', 'plotly'}, default='matplotlib'
  
          .. versionadded:: 0.9.0
  
          Selects which plotting engine will be used by ``plot_surf_stat_map``.
          Currently, only ``matplotlib`` and ``plotly`` are supported.
  
          .. note::
              To use the ``plotly`` engine you need to
              have ``plotly`` installed.
  
          .. note::
              To be able to save figures to disk with the ``plotly``
              engine you need to have ``kaleido`` installed.
  
          .. warning::
              The ``plotly`` engine is new and experimental.
              Please report bugs that you may encounter.
  
  
      threshold : a number or None, optional
          If None is given, the image is not thresholded.
          If a number is given, it is used to threshold the image,
          values below the threshold (in absolute value) are plotted
          as transparent.
      %(cmap)s
      %(cbar_tick_format)s
          Default="auto" which will select:
  
              - '%%.2g' (scientific notation) with ``matplotlib`` engine.
              - '.1f' (rounded floats) with ``plotly`` engine.
  
          .. versionadded:: 0.7.1
  
      %(colorbar)s
  
          .. note::
              This function uses a symmetric colorbar for the statistical map.
  
          Default=True.
  
      alpha : float or 'auto', default='auto'
          Alpha level of the :term:`mesh` (not the stat_map).
          If 'auto' is chosen, alpha will default to .5 when no bg_map is
          passed and to 1 if a bg_map is passed.
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      %(vmin)s
      %(vmax)s
      %(symmetric_cbar)s
      %(bg_on_data)s
  
      %(darkness)s
          Default=1.
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      %(title)s
      title_font_size : :obj:`int`, default=18
          Size of the title font.
  
          .. versionadded:: 0.9.0
  
      %(output_file)s
      axes : instance of matplotlib axes, None, optional
          The axes instance to plot to. The projection must be '3d' (e.g.,
          `figure, axes = plt.subplots(subplot_kw={'projection': '3d'})`,
          where axes should be passed.).
          If None, a new axes is created.
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      %(figure)s
  
          .. note::
              This option is currently only implemented for the
              ``matplotlib`` engine.
  
      kwargs : dict, optional
          Keyword arguments passed to :func:`nilearn.plotting.plot_surf`.
  
      See Also
      --------
      nilearn.datasets.fetch_surf_fsaverage: For surface data object to be
          used as background map for this plotting function.
  
      nilearn.plotting.plot_surf: For brain surface visualization.
  
      nilearn.surface.vol_to_surf : For info on the generation of surfaces.
  
      """
      loaded_stat_map = load_surf_data(stat_map)
  
      # Call get_colorbar_and_data_ranges to derive symmetric vmin, vmax
      # And colorbar limits depending on symmetric_cbar settings
      cbar_vmin, cbar_vmax, vmin, vmax = get_colorbar_and_data_ranges(
          loaded_stat_map,
          vmin=vmin,
          vmax=vmax,
          symmetric_cbar=symmetric_cbar,
      )
  
      display = plot_surf(
          surf_mesh,
          surf_map=loaded_stat_map,
          bg_map=bg_map,
          hemi=hemi,
          view=view,
          engine=engine,
          avg_method="mean",
          threshold=threshold,
          cmap=cmap,
          symmetric_cmap=True,
          colorbar=colorbar,
          cbar_tick_format=cbar_tick_format,
          alpha=alpha,
          bg_on_data=bg_on_data,
          darkness=darkness,
          vmax=vmax,
          vmin=vmin,
          title=title,
          title_font_size=title_font_size,
          output_file=output_file,
          axes=axes,
          figure=figure,
          cbar_vmin=cbar_vmin,
          cbar_vmax=cbar_vmax,
          **kwargs,
      )
      return display
  
imports: import itertools
  import math
  from collections.abc import Sequence
  from warnings import warn
  import matplotlib
  import matplotlib.pyplot
  import numpy
  from matplotlib import gridspec
  from matplotlib.cm import ScalarMappable
  from matplotlib.colorbar import make_axes
  from matplotlib.colors import LinearSegmentedColormap, Normalize, to_rgba
  from matplotlib.patches import Patch
  from mpl_toolkits.mplot3d.art3d import Poly3DCollection
  from nilearn import image, surface
  from nilearn._utils import check_niimg_3d, compare_version, fill_doc
  from nilearn._utils.helpers import is_kaleido_installed, is_plotly_installed
  from nilearn.plotting.cm import cold_hot, mix_colormaps
  from nilearn.plotting.displays._slicers import _get_cbar_ticks
  from nilearn.plotting.html_surface import get_vertexcolor
  from nilearn.plotting.img_plotting import get_colorbar_and_data_ranges
  from nilearn.plotting.js_plotting_utils import colorscale
  from nilearn.surface import load_surf_data, load_surf_mesh, vol_to_surf
  from nilearn.surface.surface import check_mesh
label_desc: Use image node_id 21 for calling a global function with example usage: plot_surf_stat_map(surf_mesh, stat_map, bg_map, hemi, view, engine, threshold, alpha, vmin, vmax, cmap, colorbar, symmetric_cbar, cbar_tick_format, bg_on_data, darkness, title, title_font_size, output_file, axes, figure) and returns: display