EXA: plot.UTSStat

doc/conf.py

@@ -112,6 +112,7 @@ def section_order(self):
     ],
     'plots': [
         'boxplot.py',
+        'utsstat.py',
         'colors.py',
         'colormaps.py',
         'customizing.py',

eelbrain/plot/_styles.py

@@ -15,7 +15,7 @@
 from matplotlib.colors import LinearSegmentedColormap, to_rgb, to_rgba
 
 from .._colorspaces import LocatedListedColormap, lch_to_rgb, rgb_to_lch, oneway_colors, twoway_colors, symmetric_cmaps
-from .._data_obj import CategorialVariable, Factor, Interaction, CellArg
+from .._data_obj import Factor, Interaction, CellArg
 from .._exceptions import KeysMissing
 from .._utils import LazyProperty
 
@@ -26,7 +26,12 @@
 
 @dataclass
 class Style:
-    """Control color/pattern by category"""
+    """Control color/pattern by category
+
+    Examples
+    --------
+    - :ref:`exa-utsstat`
+    """
     color: Any = (0, 0, 0)
     marker: str = None
     hatch: str = ''

eelbrain/plot/_uts.py

@@ -119,6 +119,10 @@ class UTSStat(LegendMixin, XAxisMixin, YLimMixin, EelFigure):
     ...
         Also accepts :ref:`general-layout-parameters`.
 
+    Examples
+    --------
+    - :ref:`exa-utsstat`
+
     Notes
     -----
     Navigation:

examples/plots/utsstat.py

@@ -0,0 +1,61 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: sphinx
+#       format_version: '1.1'
+#       jupytext_version: 1.10.2
+#   kernelspec:
+#     display_name: Python 3
+#     language: python
+#     name: python3
+# ---
+
+"""
+.. _exa-utsstat:
+
+UTS-statistics plot (``UTSStat``)
+=================================
+
+"""
+# sphinx_gallery_thumbnail_number = 3
+from eelbrain import *
+
+
+ds = datasets.simulate_erp(snr=1)
+# add an orthogonal variable
+ds['length'] = Factor(ds['n_chars'] > 4, labels={True: 'long', False: 'short'})
+# smooth the data to make plots nicer
+ds['cz'] = ds["eeg"].sub(sensor='Cz').smooth('time', 0.05)
+
+ds.summary()
+
+###############################################################################
+# Plot the mean and SEM of all trials.
+
+p = plot.UTSStat('cz', ds=ds, frame='t')
+
+###############################################################################
+# Split within and between plots.
+
+p = plot.UTSStat('cz', 'cloze_cat', 'length', ds=ds, frame='t')
+
+###############################################################################
+# Colors can also be set using the within-plot category only.
+
+colors = plot.colors_for_oneway(['high', 'low'])
+p = plot.UTSStat("cz", 'cloze_cat', 'length', ds=ds, colors=colors, frame='t', legend=False)
+legend = plot.ColorList(colors)
+
+###############################################################################
+# Plot all categories in the same plot. Make lines more distinguishable through line-style.
+
+colors = {
+    ('high', 'long'): plot.Style((1, 0, 0)),
+    ('high', 'short'): plot.Style((1, 0.5, 0.5), linestyle='--'),
+    ('low', 'long'): plot.Style((0, 0, 1)),
+    ('low', 'short'): plot.Style((0.5, 0.5, 1), linestyle='--'),
+}
+
+p = plot.UTSStat("cz", 'cloze_cat % length', ds=ds, colors=colors, frame='t')