From c421d5063a5cd9fc1166573a24a87693318f8ffa Mon Sep 17 00:00:00 2001
From: Scott Huberty <scott.huberty@mail.mcgill.ca>
Date: Mon, 2 Oct 2023 17:13:28 -0400
Subject: [PATCH] FIX, DOC: Code suggestions from eric and mne.utils.doc
 addition

- I added a new entry into the doc_dict in mne.utils.doc for the matplotlib cmap parameter, which I believe could prove to be useful elsewhere, for example in mne.viz.misc.plot_csd. FWIW The cmap_topo docstring that was already in the doc_dict says that if None is passed then "reds" will be used. But For any mne functions that have cmap=None as the default, if None is passed into the matplotlib function, the default will actually be whatever matplotlib's default is, which is usually viridis.
---
 mne/utils/docs.py                             |  8 +++++
 mne/viz/eyetracking/heatmap.py                | 32 +++++++------------
 .../visualization/30_eyetracking_heatmap.py   |  4 +--
 3 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/mne/utils/docs.py b/mne/utils/docs.py
index 9367562c7a1..6fc20f1e950 100644
--- a/mne/utils/docs.py
+++ b/mne/utils/docs.py
@@ -771,6 +771,14 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
     otherwise defaults to 'RdBu_r'.
 """
 
+docdict[
+    "cmap_simple"
+] = """
+cmap : matplotlib colormap | str | None
+        The :class:`~matplotlib.colors.Colormap` to use. Defaults to ``None``, meaning
+        the colormap will default to matplotlib's default.
+"""
+
 docdict[
     "cnorm"
 ] = """
diff --git a/mne/viz/eyetracking/heatmap.py b/mne/viz/eyetracking/heatmap.py
index 37439e98820..fe512c21101 100644
--- a/mne/viz/eyetracking/heatmap.py
+++ b/mne/viz/eyetracking/heatmap.py
@@ -7,7 +7,7 @@
 
 
 from ..utils import plt_show
-from ...utils import _validate_type, logger, fill_doc
+from ...utils import _ensure_int, _validate_type, logger, fill_doc
 
 
 @fill_doc
@@ -19,8 +19,7 @@ def plot_gaze(
     sigma=25,
     cmap=None,
     alpha=1.0,
-    vmin=None,
-    vmax=None,
+    vlim=(None, None),
     axes=None,
     show=True,
 ):
@@ -41,22 +40,11 @@ def plot_gaze(
     sigma : float | None
         The amount of Gaussian smoothing applied to the heatmap data (standard
         deviation in pixels). If ``None``, no smoothing is applied. Default is 25.
-    cmap : matplotlib colormap | str | None
-        The :class:`~matplotlib.colors.Colormap` to use. Defaults to ``None``, meaning
-        the colormap will default to matplotlib's default.
+    %(cmap_simple)s
     alpha : float
         The opacity of the heatmap (default is 1).
-    vmin : float | None
-        The minimum value for the colormap. The unit is seconds, for dwell time
-        to the bin coordinate. If ``None``, the minimum value is set to the
-        minimum value of the heatmap. Default is ``None``.
-    vmax : float | None
-        The maximum value for the colormap. The unit is seconds, for dwell time
-        to the bin coordinate. If ``None``, the maximum value is set to the
-        maximum value of the heatmap. Default is ``None``.
-    axes : matplotlib.axes.Axes | None
-        The axes to plot on. If ``None``, a new figure and axes are created.
-        Default is ``None``.
+    %(vlim_plot_topomap)s
+    %(axes_plot_topomap)s
     %(show)s
 
     Returns
@@ -72,6 +60,10 @@ def plot_gaze(
     from mne._fiff.pick import _picks_to_idx
 
     _validate_type(epochs, BaseEpochs, "epochs")
+    _validate_type(alpha, "numeric", "alpha")
+    _validate_type(sigma, ("numeric", None), "sigma")
+    _ensure_int(width, "width")
+    _ensure_int(width, "height")
 
     pos_picks = _picks_to_idx(epochs.info, "eyegaze")
     gaze_data = epochs.get_data(picks=pos_picks)
@@ -106,8 +98,8 @@ def plot_gaze(
         height=height,
         cmap=cmap,
         alpha=alpha,
-        vmin=vmin,
-        vmax=vmax,
+        vmin=vlim[0],
+        vmax=vlim[1],
         axes=axes,
         show=show,
     )
@@ -160,6 +152,6 @@ def _plot_heatmap_array(
     )
 
     # Prepare the colorbar
-    fig.colorbar(im, ax=ax, label="Dwell time (seconds)")
+    fig.colorbar(im, ax=ax, shrink=0.6, label="Dwell time (seconds)")
     plt_show(show)
     return fig
diff --git a/tutorials/visualization/30_eyetracking_heatmap.py b/tutorials/visualization/30_eyetracking_heatmap.py
index d7d8ab174f5..11ab5b9eac0 100644
--- a/tutorials/visualization/30_eyetracking_heatmap.py
+++ b/tutorials/visualization/30_eyetracking_heatmap.py
@@ -94,7 +94,7 @@ def plot_images(image_paths, ax, titles=None):
     epochs["natural"],
     width=px_width,
     height=px_height,
-    sigma=5,
+    sigma=50,
     cmap="jet",
     axes=ax[0],
     show=False,
@@ -104,7 +104,7 @@ def plot_images(image_paths, ax, titles=None):
     epochs["scrambled"],
     width=px_width,
     height=px_height,
-    sigma=5,
+    sigma=50,
     cmap="jet",
     axes=ax[1],
     show=False,