plopp 25.9.0__py3-none-any.whl → 25.11.0__py3-none-any.whl

plopp/graphics/colormapper.py

@@ -15,6 +15,7 @@ from matplotlib.colors import Colormap, LinearSegmentedColormap, LogNorm, Normal
 from ..backends.matplotlib.utils import fig_to_bytes
 from ..core.limits import find_limits, fix_empty_range
 from ..core.utils import maybe_variable_to_number, merge_masks
+from ..utils import parse_mutually_exclusive
 
 
 def _shift_color(color: float, delta: float) -> float:
@@ -102,18 +103,29 @@ class ColorMapper:
         a colormap with that single color will be used.
     mask_cmap:
         The name of the colormap for masked data.
-    norm:
-        The colorscale normalization.
-    vmin:
+    cmin:
         The minimum value for the colorscale range. If a number (without a unit) is
         supplied, it is assumed that the unit is the same as the data unit.
-    vmax:
+    cmax:
         The maximum value for the colorscale range. If a number (without a unit) is
         supplied, it is assumed that the unit is the same as the data unit.
+    logc:
+        If ``True``, use a logarithmic colorscale.
     nan_color:
         The color used for representing NAN values.
     figsize:
         The size of the figure next to which the colorbar will be displayed.
+    norm:
+        The colorscale normalization. This is an old parameter name.
+        Prefer using ``logc`` instead.
+    vmin:
+        The minimum value for the colorscale range. If a number (without a unit) is
+        supplied, it is assumed that the unit is the same as the data unit.
+        This is an old parameter name. Prefer using ``cmin`` instead.
+    vmax:
+        The maximum value for the colorscale range. If a number (without a unit) is
+        supplied, it is assumed that the unit is the same as the data unit.
+        This is an old parameter name. Prefer using ``cmax`` instead.
     """
 
     def __init__(
@@ -122,26 +134,44 @@ class ColorMapper:
         cbar: bool = True,
         cmap: str | Colormap = 'viridis',
         mask_cmap: str | Colormap = 'gray',
-        norm: Literal['linear', 'log'] = 'linear',
-        vmin: sc.Variable | float | None = None,
-        vmax: sc.Variable | float | None = None,
+        mask_color: str | None = None,
+        cmin: sc.Variable | float | None = None,
+        cmax: sc.Variable | float | None = None,
+        logc: bool | None = None,
+        clabel: str | None = None,
         nan_color: str | None = None,
         figsize: tuple[float, float] | None = None,
+        norm: Literal['linear', 'log', None] = None,
+        vmin: sc.Variable | float | None = None,
+        vmax: sc.Variable | float | None = None,
     ):
+        cmin = parse_mutually_exclusive(vmin=vmin, cmin=cmin)
+        cmax = parse_mutually_exclusive(vmax=vmax, cmax=cmax)
+        logc = parse_mutually_exclusive(norm=norm, logc=logc)
+
         self._canvas = canvas
         self.cax = self._canvas.cax if hasattr(self._canvas, 'cax') else None
         self.cmap = _get_cmap(cmap, nan_color=nan_color)
-        self.mask_cmap = _get_cmap(mask_cmap, nan_color=nan_color)
-        self.user_vmin = vmin
-        self.user_vmax = vmax
-        self._vmin = np.inf
-        self._vmax = -np.inf
-        self.norm = norm
+        self.mask_cmap = _get_cmap(
+            mask_cmap if mask_color is None else mask_color, nan_color=nan_color
+        )
+
+        # Inside the autoscale, we need to distinguish between a min value that was set
+        # by the user and one that was found by looping over all the data.
+        # So we basically always need to keep a backup of the user-set value.
+        self._cmin = {"data": np.inf}
+        self._cmax = {"data": -np.inf}
+        if cmin is not None:
+            self._cmin["user"] = cmin
+        if cmax is not None:
+            self._cmax["user"] = cmax
+        self._clabel = clabel
+        self._logc = False if logc is None else logc
         self.set_colors_on_update = True
 
-        # Note that we need to set vmin/vmax for the LogNorm, if not an error is
+        # Note that we need to set cmin/cmax for the LogNorm, if not an error is
         # raised when making the colorbar before any call to update is made.
-        self.normalizer = _get_normalizer(self.norm)
+        self.normalizer = _get_normalizer('log' if self._logc else 'linear')
         self.colorbar = None
         self._unit = None
         self.empty = True
@@ -157,6 +187,8 @@ class ColorMapper:
                 self.cax = fig.add_axes([0.05, 0.02, 0.2, 0.98])
             self.colorbar = ColorbarBase(self.cax, cmap=self.cmap, norm=self.normalizer)
             self.cax.yaxis.set_label_coords(-0.9, 0.5)
+            if self._clabel is not None:
+                self.cax.set_ylabel(self._clabel)
 
     def add_artist(self, key: str, artist: Any):
         self.artists[key] = artist
@@ -201,41 +233,47 @@ class ColorMapper:
         Re-compute the global min and max range of values by iterating over all the
         artists and adjust the limits.
         """
+        if ("user" in self._cmin) and ("user" in self._cmax):
+            if self._cmin["user"] >= self._cmax["user"]:
+                raise ValueError('User-set limits: cmin must be smaller than cmax.')
+            self._cmin["data"] = self._cmin["user"]
+            self._cmax["data"] = self._cmax["user"]
+            self.apply_limits()
+            return
+
         limits = [
-            fix_empty_range(find_limits(artist._data, scale=self.norm))
+            fix_empty_range(
+                find_limits(artist._data, scale='log' if self._logc else 'linear')
+            )
             for artist in self.artists.values()
         ]
-        vmin = reduce(min, [v[0] for v in limits])
-        vmax = reduce(max, [v[1] for v in limits])
-        if self.user_vmin is not None:
-            self._vmin = self.user_vmin
+        if "user" not in self._cmin:
+            self._cmin["data"] = reduce(min, [v[0] for v in limits]).value
         else:
-            self._vmin = vmin.value
-        if self.user_vmax is not None:
-            self._vmax = self.user_vmax
+            self._cmin["data"] = self._cmin["user"]
+        if "user" not in self._cmax:
+            self._cmax["data"] = reduce(max, [v[1] for v in limits]).value
         else:
-            self._vmax = vmax.value
+            self._cmax["data"] = self._cmax["user"]
 
-        if self._vmin >= self._vmax:
-            if self.user_vmax is not None:
-                self._vmax = self.user_vmax
-                self._vmin = self.user_vmax - abs(self.user_vmax) * 0.1
+        if self._cmin["data"] >= self._cmax["data"]:
+            if "user" in self._cmax:
+                self._cmin["data"] = self._cmax["data"] - abs(self._cmax["data"]) * 0.1
             else:
-                self._vmin = self.user_vmin
-                self._vmax = self.user_vmin + abs(self.user_vmin) * 0.1
+                self._cmax["data"] = self._cmin["data"] + abs(self._cmin["data"]) * 0.1
 
         self.apply_limits()
 
     def apply_limits(self):
         # Synchronize the underlying normalizer limits to the current state.
-        # Note that the order matters here, as for a normalizer vmin cannot be set above
-        # the current vmax.
-        if self._vmin >= self.normalizer.vmax:
-            self.normalizer.vmax = self._vmax
-            self.normalizer.vmin = self._vmin
+        # Note that the order matters here, as for a normalizer cmin cannot be set above
+        # the current cmax.
+        if self._cmin["data"] >= self.normalizer.vmax:
+            self.normalizer.vmax = self._cmax["data"]
+            self.normalizer.vmin = self._cmin["data"]
         else:
-            self.normalizer.vmin = self._vmin
-            self.normalizer.vmax = self._vmax
+            self.normalizer.vmin = self._cmin["data"]
+            self.normalizer.vmax = self._cmax["data"]
 
         if self.colorbar is not None:
             self._update_colorbar_widget()
@@ -252,24 +290,48 @@ class ColorMapper:
     def vmin(self) -> float:
         """
         Get or set the minimum value of the colorbar.
+        This is an old property name. Prefer using ``cmin`` instead.
         """
-        return self._vmin
+        return self.cmin
 
     @vmin.setter
-    def vmin(self, vmin: sc.Variable | float):
-        self._vmin = maybe_variable_to_number(vmin, unit=self._unit)
-        self.apply_limits()
+    def vmin(self, value: sc.Variable | float):
+        self.cmin = value
 
     @property
     def vmax(self) -> float:
         """
         Get or set the maximum value of the colorbar.
+        This is an old property name. Prefer using ``cmax`` instead.
         """
-        return self._vmax
+        return self.cmax
 
     @vmax.setter
-    def vmax(self, vmax: sc.Variable | float):
-        self._vmax = maybe_variable_to_number(vmax, unit=self._unit)
+    def vmax(self, value: sc.Variable | float):
+        self.cmax = value
+
+    @property
+    def cmin(self) -> float:
+        """
+        Get or set the minimum value of the colorbar.
+        """
+        return self._cmin.get("user", self._cmin["data"])
+
+    @cmin.setter
+    def cmin(self, value: sc.Variable | float):
+        self._cmin["user"] = maybe_variable_to_number(value, unit=self._unit)
+        self.apply_limits()
+
+    @property
+    def cmax(self) -> float:
+        """
+        Get or set the maximum value of the colorbar.
+        """
+        return self._cmax.get("user", self._cmax["data"])
+
+    @cmax.setter
+    def cmax(self, value: sc.Variable | float):
+        self._cmax["user"] = maybe_variable_to_number(value, unit=self._unit)
         self.apply_limits()
 
     @property
@@ -282,34 +344,70 @@ class ColorMapper:
     @unit.setter
     def unit(self, unit: str | None):
         self._unit = unit
-        if self.user_vmin is not None:
-            self.user_vmin = maybe_variable_to_number(self.user_vmin, unit=self._unit)
-        if self.user_vmax is not None:
-            self.user_vmax = maybe_variable_to_number(self.user_vmax, unit=self._unit)
+        if "user" in self._cmin:
+            self._cmin["user"] = maybe_variable_to_number(
+                self._cmin["user"], unit=self._unit
+            )
+        if "user" in self._cmax:
+            self._cmax["user"] = maybe_variable_to_number(
+                self._cmax["user"], unit=self._unit
+            )
 
     @property
-    def ylabel(self) -> str | None:
+    def clabel(self) -> str | None:
         """
         Get or set the label of the colorbar axis.
         """
         if self.cax is not None:
             return self.cax.get_ylabel()
 
-    @ylabel.setter
-    def ylabel(self, lab: str):
+    @clabel.setter
+    def clabel(self, lab: str):
         if self.cax is not None:
             self.cax.set_ylabel(lab)
 
+    @property
+    def ylabel(self) -> str | None:
+        """
+        Get or set the label of the colorbar axis.
+        This is an old property name. Prefer using ``clabel`` instead.
+        """
+        return self.clabel
+
+    @ylabel.setter
+    def ylabel(self, lab: str):
+        self.clabel = lab
+
     def toggle_norm(self):
         """
         Toggle the norm flag, between `linear` and `log`.
         """
-        self.norm = "log" if self.norm == 'linear' else 'linear'
-        self.normalizer = _get_normalizer(self.norm)
-        self._vmin = np.inf
-        self._vmax = -np.inf
+        self._logc = not self._logc
+        self.normalizer = _get_normalizer('log' if self._logc else 'linear')
+        self._cmin["data"] = np.inf
+        self._cmax["data"] = -np.inf
         if self.colorbar is not None:
             self.colorbar.mappable.norm = self.normalizer
         self.autoscale()
         if self._canvas is not None:
             self._canvas.draw()
+
+    @property
+    def norm(self) -> Literal['linear', 'log']:
+        """
+        Get or set the colorscale normalization.
+        """
+        return 'log' if self._logc else 'linear'
+
+    @norm.setter
+    def norm(self, value: Literal['linear', 'log']):
+        if value not in ['linear', 'log']:
+            raise ValueError('norm must be either "linear" or "log".')
+        if value != self.norm:
+            self.toggle_norm()
+
+    def has_user_clabel(self) -> bool:
+        """
+        Return ``True`` if the user has set a colorbar label.
+        """
+        return self._clabel is not None

plopp/graphics/graphicalview.py

@@ -49,8 +49,9 @@ class GraphicalView(View):
         colormapper: bool = False,
         cmap: str = 'viridis',
         mask_cmap: str = 'gray',
+        mask_color: str | None = None,
         cbar: bool = False,
-        norm: Literal['linear', 'log'] = 'linear',
+        norm: Literal['linear', 'log', None] = None,
         vmin: sc.Variable | float | None = None,
         vmax: sc.Variable | float | None = None,
         scale: dict[str, str] | None = None,
@@ -64,9 +65,27 @@ class GraphicalView(View):
         autoscale: bool = True,
         ax: Any = None,
         cax: Any = None,
+        xmin: sc.Variable | float | None = None,
+        xmax: sc.Variable | float | None = None,
+        ymin: sc.Variable | float | None = None,
+        ymax: sc.Variable | float | None = None,
+        zmin: sc.Variable | float | None = None,
+        zmax: sc.Variable | float | None = None,
+        cmin: sc.Variable | float | None = None,
+        cmax: sc.Variable | float | None = None,
+        logx: bool | None = None,
+        logy: bool | None = None,
+        logz: bool | None = None,
+        logc: bool | None = None,
+        xlabel: str | None = None,
+        ylabel: str | None = None,
+        zlabel: str | None = None,
+        clabel: str | None = None,
+        nan_color: str | None = None,
         **kwargs,
     ):
         super().__init__(*nodes)
+
         self._dims = dims
         self._scale = {} if scale is None else scale
         self.artists = {}
@@ -88,6 +107,19 @@ class GraphicalView(View):
             camera=camera,
             ax=ax,
             cax=cax,
+            xmin=xmin,
+            xmax=xmax,
+            ymin=ymin,
+            ymax=ymax,
+            zmin=zmin,
+            zmax=zmax,
+            logx=logx,
+            logy=logy,
+            logz=logz,
+            xlabel=xlabel,
+            ylabel=ylabel,
+            zlabel=zlabel,
+            norm=norm if len(dims) == 1 else None,
         )
 
         if colormapper:
@@ -95,11 +127,17 @@ class GraphicalView(View):
                 cmap=cmap,
                 cbar=cbar,
                 mask_cmap=mask_cmap,
+                mask_color=mask_color,
                 norm=norm,
                 vmin=vmin,
                 vmax=vmax,
+                cmin=cmin,
+                cmax=cmax,
+                clabel=clabel,
+                logc=logc,
                 canvas=self.canvas,
                 figsize=getattr(self.canvas, "figsize", None),
+                nan_color=nan_color,
             )
             self._kwargs['colormapper'] = self.colormapper
             if self._autoscale:
@@ -108,9 +146,10 @@ class GraphicalView(View):
                 self.colormapper.set_colors_on_update = False
         else:
             self.colormapper = None
+            # If there is not colormapper, we need to forward the mask_color to the
+            # artist maker.
+            self._kwargs['mask_color'] = mask_color
 
-        if len(self._dims) == 1:
-            self.canvas.yscale = norm
         self.render()
 
     def autoscale(self):
@@ -145,19 +184,20 @@ class GraphicalView(View):
             for i, direction in enumerate(self._dims):
                 if self._dims[direction] is None:
                     self._dims[direction] = new_values.dims[i]
-                try:
-                    coords[direction] = new_values.coords[self._dims[direction]]
-                except KeyError as e:
+                if self._dims[direction] not in new_values.coords:
                     raise KeyError(
                         "Supplied data is incompatible with this view: "
                         f"coordinate '{self._dims[direction]}' was not found in data."
-                    ) from e
+                    )
+                coords[direction] = new_values.coords[self._dims[direction]]
 
             if self.canvas.empty:
                 self._data_name = new_values.name
                 axes_units = {k: coord.unit for k, coord in coords.items()}
                 axes_dtypes = {k: coord.dtype for k, coord in coords.items()}
 
+                data_label = name_with_unit(var=new_values.data, name=self._data_name)
+
                 if set(self._dims) == {'x'}:
                     axes_units['data'] = new_values.unit
                     axes_dtypes['data'] = new_values.dtype
@@ -165,28 +205,31 @@ class GraphicalView(View):
                     self.colormapper.unit = new_values.unit
                     axes_units['data'] = new_values.unit
                     axes_dtypes['data'] = new_values.dtype
-                    self._data_axis = self.colormapper
+                    if not self.colormapper.has_user_clabel():
+                        self.colormapper.clabel = data_label
                 else:
-                    self._data_axis = self.canvas
+                    if not self.canvas.has_user_ylabel():
+                        self.canvas.ylabel = data_label
 
                 self.canvas.set_axes(
                     dims=self._dims, units=axes_units, dtypes=axes_dtypes
                 )
 
                 for xyz, dim in self._dims.items():
-                    setattr(
-                        self.canvas,
-                        f'{xyz}label',
-                        name_with_unit(var=coords[xyz], name=dim),
-                    )
+                    if not getattr(self.canvas, f'has_user_{xyz}label')():
+                        setattr(
+                            self.canvas,
+                            f'{xyz}label',
+                            name_with_unit(var=coords[xyz], name=dim),
+                        )
+                    # Note that setting the scale is handled here as well as in the
+                    # canvas for historical purposes. We kept the scale argument for
+                    # backward compatibility, but it is now also possible to set the
+                    # axes scales with logx, logy, logz in the constructor of the
+                    # canvas.
                     if dim in self._scale:
                         setattr(self.canvas, f'{xyz}scale', self._scale[dim])
 
-                if self._data_axis is not None:
-                    self._data_axis.ylabel = name_with_unit(
-                        var=new_values.data, name=self._data_name
-                    )
-
             else:
                 for xy, dim in self._dims.items():
                     new_values.coords[dim] = make_compatible(
@@ -198,9 +241,15 @@ class GraphicalView(View):
                     )
                     if self._data_name and (new_values.name != self._data_name):
                         self._data_name = None
-                        self._data_axis.ylabel = name_with_unit(
-                            var=sc.scalar(0.0, unit=self.canvas.units['data']), name=''
+                        data_label = name_with_unit(
+                            var=sc.scalar(0.0, unit=self.canvas.units['data']),
+                            name='',
                         )
+                        if self.colormapper is not None:
+                            if not self.colormapper.has_user_clabel():
+                                self.colormapper.clabel = data_label
+                        elif not self.canvas.has_user_ylabel():
+                            self.canvas.ylabel = data_label
 
             if key not in self.artists:
                 self.artists[key] = self._artist_maker(

plopp/plotting/common.py

@@ -3,7 +3,7 @@
 
 import warnings
 from collections.abc import Callable, Iterable
-from typing import Any
+from typing import Any, Literal
 
 import numpy as np
 import scipp as sc
@@ -97,7 +97,7 @@ def to_data_array(obj: Plottable | list) -> sc.DataArray:
     return out
 
 
-def _check_size(da: sc.DataArray) -> None:
+def check_size(da: sc.DataArray) -> None:
     """
     Prevent slow figure rendering by raising an error if the data array exceeds a
     default size.
@@ -293,7 +293,7 @@ def preprocess(
     if name is not None:
         out.name = str(name)
     if not ignore_size:
-        _check_size(out)
+        check_size(out)
     if coords is not None:
         out = _rename_dims_from_coords(out, coords)
     out = _add_missing_dimension_coords(out)
@@ -344,3 +344,71 @@ def raise_multiple_inputs_for_2d_plot_error(origin):
         'want to plot two images onto the same axes, use the lower-level '
         'plopp.imagefigure function.'
     )
+
+
+def categorize_args(
+    aspect: Literal['auto', 'equal', None] = None,
+    autoscale: bool = True,
+    cbar: bool = True,
+    clabel: str | None = None,
+    cmap: str = 'viridis',
+    cmax: sc.Variable | float | None = None,
+    cmin: sc.Variable | float | None = None,
+    errorbars: bool = True,
+    figsize: tuple[float, float] | None = None,
+    grid: bool = False,
+    legend: bool | tuple[float, float] = True,
+    logc: bool | None = None,
+    logx: bool | None = None,
+    logy: bool | None = None,
+    mask_cmap: str = 'gray',
+    mask_color: str = 'black',
+    nan_color: str | None = None,
+    norm: Literal['linear', 'log', None] = None,
+    scale: dict[str, str] | None = None,
+    title: str | None = None,
+    vmax: sc.Variable | float | None = None,
+    vmin: sc.Variable | float | None = None,
+    xlabel: str | None = None,
+    xmax: sc.Variable | float | None = None,
+    xmin: sc.Variable | float | None = None,
+    ylabel: str | None = None,
+    ymax: sc.Variable | float | None = None,
+    ymin: sc.Variable | float | None = None,
+    **kwargs,
+) -> dict:
+    common_args = {
+        'aspect': aspect,
+        'autoscale': autoscale,
+        'figsize': figsize,
+        'grid': grid,
+        'logx': logx,
+        'logy': logy,
+        'mask_color': mask_color,
+        'norm': norm,
+        'scale': scale,
+        'title': title,
+        'vmax': vmax,
+        'vmin': vmin,
+        'xlabel': xlabel,
+        'xmax': xmax,
+        'xmin': xmin,
+        'ylabel': ylabel,
+        'ymax': ymax,
+        'ymin': ymin,
+        **kwargs,
+    }
+    return {
+        "1d": {'errorbars': errorbars, 'legend': legend, **common_args},
+        "2d": {
+            'cbar': cbar,
+            'cmap': cmap,
+            'cmin': cmin,
+            'cmax': cmax,
+            'clabel': clabel,
+            'logc': logc,
+            'nan_color': nan_color,
+            'mask_cmap': mask_cmap,
+            **common_args,
+        },
+    }