units argument to plot_stim (and callers)

Replaces `extent_key`, but serves the same purpose. Can put in either:
- `pixels` (syn: `px`, `pix`)
- `degrees` (syn: `deg`)
- another str  that is a key in `stim`-dict, like current `extent_key` arg

Closes #9

stimupy/components/__init__.py

@@ -248,7 +248,7 @@ def overview(skip=False):
     return stimuli
 
 
-def plot_overview(mask=False, save=None, extent_key="shape"):
+def plot_overview(mask=False, save=None, units="deg"):
     """Plot overview of examples in this module (and submodules)
 
     Parameters
@@ -259,15 +259,16 @@ def plot_overview(mask=False, save=None, extent_key="shape"):
     save : None or str, optional
         If None (default), do not save the plot.
         If string is provided, save plot under this name.
-    extent_key : str, optional
-        Key to extent which will be used for plotting.
-        Default is "shape", using the image size in pixels as extent.
+    units : "px", "deg" (default), or str
+        what units to put on the axes, by default degrees visual angle ("deg").
+        If a str other than "deg"(/"degrees") or "px"(/"pix"/"pixels") is passed,
+        it must be the key to a tuple in stim
 
     """
     from stimupy.utils import plot_stimuli
 
     stims = overview(skip=True)
-    plot_stimuli(stims, mask=mask, extent_key=extent_key, save=save)
+    plot_stimuli(stims, mask=mask, units=units, save=save)
 
 
 if __name__ == "__main__":

stimupy/noises/__init__.py

@@ -41,7 +41,7 @@ def overview(skip=False):
     return stimuli
 
 
-def plot_overview(mask=False, save=None, extent_key="shape"):
+def plot_overview(mask=False, save=None, units="deg"):
     """Plot overview of examples in this module (and submodules)
 
     Parameters
@@ -52,15 +52,16 @@ def plot_overview(mask=False, save=None, extent_key="shape"):
     save : None or str, optional
         If None (default), do not save the plot.
         If string is provided, save plot under this name.
-    extent_key : str, optional
-        Key to extent which will be used for plotting.
-        Default is "shape", using the image size in pixels as extent.
+    units : "px", "deg" (default), or str
+        what units to put on the axes, by default degrees visual angle ("deg").
+        If a str other than "deg"(/"degrees") or "px"(/"pix"/"pixels") is passed,
+        it must be the key to a tuple in stim
 
     """
     from stimupy.utils import plot_stimuli
 
     stims = overview(skip=True)
-    plot_stimuli(stims, mask=mask, extent_key=extent_key, save=save)
+    plot_stimuli(stims, mask=mask, units=units, save=save)
 
 
 if __name__ == "__main__":

stimupy/papers/modelfest.py

@@ -2351,5 +2351,5 @@ def compare_all():
     from stimupy.utils import plot_stimuli
 
     stims = gen_all(skip=True)
-    plot_stimuli(stims, mask=False, extent_key="visual_size")
+    plot_stimuli(stims, mask=False, units="visual_size")
     # compare_all()

stimupy/stimuli/__init__.py

@@ -57,7 +57,7 @@ def overview(skip=False):
     return stimuli
 
 
-def plot_overview(mask=False, save=None, extent_key="shape"):
+def plot_overview(mask=False, save=None, units="deg"):
     """Plot overview of examples in this module (and submodules)
 
     Parameters
@@ -68,15 +68,16 @@ def plot_overview(mask=False, save=None, extent_key="shape"):
     save : None or str, optional
         If None (default), do not save the plot.
         If string is provided, save plot under this name.
-    extent_key : str, optional
-        Key to extent which will be used for plotting.
-        Default is "shape", using the image size in pixels as extent.
+    units : "px", "deg" (default), or str
+        what units to put on the axes, by default degrees visual angle ("deg").
+        If a str other than "deg"(/"degrees") or "px"(/"pix"/"pixels") is passed,
+        it must be the key to a tuple in stim
 
     """
     from stimupy.utils import plot_stimuli
 
     stims = overview(skip=True)
-    plot_stimuli(stims, mask=mask, extent_key=extent_key, save=save)
+    plot_stimuli(stims, mask=mask, units=units, save=save)
 
 
 if __name__ == "__main__":

stimupy/utils/plotting.py

@@ -4,6 +4,8 @@
 import matplotlib.pyplot as plt
 import numpy as np
 
+from stimupy.utils import resolution
+
 __all__ = [
     "compare_plots",
     "plot_stim",
@@ -37,7 +39,7 @@ def plot_stim(
     vmin=0,
     vmax=1,
     save=None,
-    extent_key="shape",
+    units="deg",
 ):
     """
     Utility function to plot stimulus array (key: "img") from stim dict and mask (optional)
@@ -60,32 +62,37 @@ def plot_stim(
     save : None or str, optional
         If None (default), do not save the plot.
         If string is provided, save plot under this name.
-    extent_key : str, optional
-        Key to extent which will be used for plotting.
-        Default is "shape", using the image size in pixels as extent.
+    units : "px", "deg" (default), or str
+        what units to put on the axes, by default degrees visual angle ("deg").
+        If a str other than "deg"(/"degrees") or "px"(/"pix"/"pixels") is passed,
+        it must be the key to a tuple in stim
 
     Returns
     -------
     ax : Axis object
         If ax was passed and plotting is None, returns updated Axis object.
 
     """
-    print("Plotting:", stim_name)
-
     single_plot = False
     if ax is None:
         ax = plt.gca()
         single_plot = True
 
-    if extent_key in stim.keys():
-        if len(stim[extent_key]) == 2:
-            extent = [0, stim[extent_key][1], 0, stim[extent_key][0]]
-        elif len(stim[extent_key]) == 4:
-            extent = stim[extent_key]
+    # Figure out what units need to go on axes
+    if units in ["px", "pix", "pixels"]:
+        extent = [0, stim["img"].shape[1], 0, stim["img"].shape[0]]
+    elif units in ["deg", "degrees"]:
+        visual_size = resolution.validate_visual_size(stim["visual_size"])
+        extent = [0, visual_size.width, 0, visual_size.height]
+    elif units in stim.keys():
+        if len(stim[units]) == 2:
+            extent = [0, stim[units][1], 0, stim[units][0]]
+        elif len(stim[units]) == 4:
+            extent = stim[units]
         else:
             raise ValueError("extent should either contain 2 or 4 values")
     else:
-        warnings.warn("extent_key does not exist in dict, using pixel-extent")
+        warnings.warn("units does not exist in dict, using pixel-extent")
         extent = [0, stim["img"].shape[1], 0, stim["img"].shape[0]]
 
     if not mask:
@@ -155,7 +162,7 @@ def plot_stimuli(
     vmin=0,
     vmax=1,
     save=None,
-    extent_key="shape",
+    units="deg",
 ):
     """
     Utility function to plot multuple stimuli (key: "img") from stim dicts and mask (optional)
@@ -174,10 +181,10 @@ def plot_stimuli(
     save : None or str, optional
         If None (default), do not save the plot.
         If string is provided, save plot under this name.
-    extent_key : str, optional
-        Key to extent which will be used for plotting.
-        Default is "shape", using the image size in pixels as extent.
-
+    units : "px", "deg" (default), or str
+        what units to put on the axes, by default degrees visual angle ("deg").
+        If a str other than "deg"(/"degrees") or "px"(/"pix"/"pixels") is passed,
+        it must be the key to a tuple in stim
     """
 
     # Plot each stimulus+mask
@@ -193,7 +200,7 @@ def plot_stimuli(
             vmin=vmin,
             vmax=vmax,
             save=None,
-            extent_key=extent_key,
+            units=units,
         )
 
     plt.tight_layout()