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

plopp/plotting/scatter3d.py

@@ -43,14 +43,20 @@ def scatter3d(
     y: str = 'y',
     z: str = 'z',
     pos: str | None = None,
+    autoscale: bool = True,
+    camera: Camera | None = None,
+    cbar: bool = False,
+    clabel: str | None = None,
+    cmap: str = 'viridis',
+    cmax: sc.Variable | float = None,
+    cmin: sc.Variable | float = None,
     figsize: tuple[int, int] = (600, 400),
-    norm: Literal['linear', 'log'] = 'linear',
+    logc: bool | None = None,
+    nan_color: str | None = None,
+    norm: Literal['linear', 'log', None] = None,
     title: str | None = None,
-    vmin: sc.Variable | float = None,
     vmax: sc.Variable | float = None,
-    cbar: bool = False,
-    cmap: str = 'viridis',
-    camera: Camera | None = None,
+    vmin: sc.Variable | float = None,
     **kwargs,
 ) -> FigureLike:
     """Make a three-dimensional scatter plot.
@@ -76,20 +82,43 @@ def scatter3d(
         The name of the coordinate that is to be used for the Z positions.
     pos:
         The name of the vector coordinate that is to be used for the positions.
-    norm:
-        Set to ``'log'`` for a logarithmic colorscale.
+    autoscale:
+        Automatically scale the colormap on updates if ``True``.
+    camera:
+        Initial camera configuration (position, target).
+    cbar:
+        Show colorbar if ``True``. If ``cbar`` is ``True``, the marker will be colored
+        using the data values in the supplied data array.
+    clabel:
+        Label for colorscale (only applicable if ``cbar`` is ``True``).
+    cmap:
+        The colormap to be used for the colorscale (only applicable if ``cbar`` is
+        ``True``).
+    cmax:
+        Upper limit for the colorscale (only applicable if ``cbar`` is ``True``).
+    cmin:
+        Lower limit for the colorscale (only applicable if ``cbar`` is ``True``).
     figsize:
         The size of the 3d rendering area, in pixels: ``(width, height)``.
+    logc:
+        Set to ``True`` for a logarithmic colorscale (only applicable if ``cbar`` is
+        ``True``).
+    nan_color:
+        Color to use for NaN values in color mapping (only applicable if ``cbar`` is
+        ``True``).
+    norm:
+        Set to ``'log'`` for a logarithmic colorscale (only applicable if ``cbar`` is
+        ``True``). Legacy, prefer ``logc`` instead.
     title:
         The figure title.
     vmin:
-        Lower bound for the colorscale.
+        Lower limit for the colorscale for (only applicable if ``cbar`` is ``True``).
+        Legacy, prefer ``cmin`` instead.
     vmax:
-        Upper bound for the colorscale.
-    cmap:
-        The name of the colormap.
-    camera:
-        Initial camera configuration (position, target).
+        Upper limit for the colorscale for (only applicable if ``cbar`` is ``True``).
+        Legacy, prefer ``cmax`` instead.
+    **kwargs:
+        All other kwargs are forwarded the underlying plotting library.
 
     Returns
     -------
@@ -115,14 +144,20 @@ def scatter3d(
         x=x,
         y=y,
         z=z,
+        autoscale=autoscale,
+        camera=camera,
+        cbar=cbar,
+        clabel=clabel,
+        cmax=cmax,
+        cmin=cmin,
+        cmap=cmap,
         figsize=figsize,
+        logc=logc,
+        nan_color=nan_color,
         norm=norm,
         title=title,
-        vmin=vmin,
         vmax=vmax,
-        cmap=cmap,
-        cbar=cbar,
-        camera=camera,
+        vmin=vmin,
         **kwargs,
     )
     clip_planes = ClippingPlanes(fig)

plopp/plotting/slicer.py

@@ -3,13 +3,15 @@
 
 from functools import partial
 from itertools import groupby
+from typing import Literal
 
-from scipp.typing import VariableLike
+import scipp as sc
 
 from ..core import widget_node
 from ..core.typing import FigureLike, PlottableMulti
 from ..graphics import imagefigure, linefigure
 from .common import (
+    categorize_args,
     input_to_nodes,
     preprocess,
     raise_multiple_inputs_for_2d_plot_error,
@@ -34,19 +36,16 @@ class Slicer:
     ----------
     obj:
         The input data.
+    coords:
+        If supplied, use these coords instead of the input's dimension coordinates.
+    enable_player:
+        If ``True``, add a play button to the sliders to automatically step through
+        the slices.
     keep:
         The dimensions to be kept, all remaining dimensions will be sliced. This should
         be a list of dims. If no dims are provided, the last dim will be kept in the
         case of a 2-dimensional input, while the last two dims will be kept in the case
         of higher dimensional inputs.
-    coords:
-        If supplied, use these coords instead of the input's dimension coordinates.
-    vmin:
-        The minimum value of the y-axis (1d plots) or color range (2d plots).
-    vmax:
-        The maximum value of the y-axis (1d plots) or color range (2d plots).
-    cbar:
-        Whether to display a colorbar for 2D plots.
     **kwargs:
         The additional arguments are forwarded to the underlying 1D or 2D figures.
     """
@@ -55,16 +54,14 @@ class Slicer:
         self,
         obj: PlottableMulti,
         *,
-        keep: list[str] | None = None,
         coords: list[str] | None = None,
-        vmin: VariableLike | float = None,
-        vmax: VariableLike | float = None,
-        cbar: bool = True,
         enable_player: bool = False,
+        keep: list[str] | None = None,
         **kwargs,
     ):
         nodes = input_to_nodes(
-            obj, processor=partial(preprocess, ignore_size=True, coords=coords)
+            obj,
+            processor=partial(preprocess, ignore_size=True, coords=coords),
         )
 
         dims = nodes[0]().dims
@@ -106,34 +103,60 @@ class Slicer:
         self.slider_node = widget_node(self.slider)
         self.slice_nodes = [slice_dims(node, self.slider_node) for node in nodes]
 
+        args = categorize_args(**kwargs)
+
         ndims = len(keep)
         if ndims == 1:
-            make_figure = linefigure
+            make_figure = partial(linefigure, **args['1d'])
         elif ndims == 2:
             if len(self.slice_nodes) > 1:
                 raise_multiple_inputs_for_2d_plot_error(origin='slicer')
-            make_figure = partial(imagefigure, cbar=cbar)
+            make_figure = partial(imagefigure, **args['2d'])
         else:
             raise ValueError(
                 f'Slicer plot: the number of dims to be kept must be 1 or 2, '
                 f'but {ndims} were requested.'
             )
 
-        self.figure = make_figure(*self.slice_nodes, vmin=vmin, vmax=vmax, **kwargs)
+        self.figure = make_figure(*self.slice_nodes)
         require_interactive_figure(self.figure, 'slicer')
         self.figure.bottom_bar.add(self.slider)
 
 
 def slicer(
     obj: PlottableMulti,
-    *,
     keep: list[str] | None = None,
+    *,
+    aspect: Literal['auto', 'equal', None] = None,
     autoscale: bool = True,
-    coords: list[str] | None = None,
-    vmin: VariableLike | float = None,
-    vmax: VariableLike | float = None,
     cbar: bool = True,
+    clabel: str | None = None,
+    cmap: str = 'viridis',
+    cmax: sc.Variable | float | None = None,
+    cmin: sc.Variable | float | None = None,
+    coords: list[str] | None = None,
     enable_player: bool = False,
+    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 | None = None,
+    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,
 ) -> FigureLike:
     """
@@ -145,36 +168,110 @@ def slicer(
     obj:
         The object to be plotted.
     keep:
-        The dimensions to be kept, all remaining dimensions will be sliced. This should
-        be a list of dims. If no dims are provided, the last dim will be kept in the
-        case of a 2-dimensional input, while the last two dims will be kept in the case
-        of higher dimensional inputs.
+        The single dimension to be kept, all remaining dimensions will be sliced.
+        This should be a single string. If no dim is provided, the last/inner dim will
+        be kept.
+    aspect:
+        Aspect ratio for the axes.
     autoscale:
-        Automatically adjust range of the y-axis (1d plots) or color scale (2d plots)
-        every time the data changes if ``True``.
+        Automatically scale the axes/colormap on updates if ``True``.
+    cbar:
+        Show colorbar in 2d plots if ``True``.
+    clabel:
+        Label for colorscale (2d plots only).
+    cmap:
+        The colormap to be used for the colorscale (2d plots only).
+    cmax:
+        Upper limit for colorscale (2d plots only).
+    cmin:
+        Lower limit for colorscale (2d plots only).
     coords:
         If supplied, use these coords instead of the input's dimension coordinates.
-    vmin:
-        The minimum value of the y-axis (1d plots) or color range (2d plots).
-    vmax:
-        The maximum value of the y-axis (1d plots) or color range (2d plots).
-    cbar:
-        Whether to display a colorbar for 2D plots.
     enable_player:
-        Add a play button to animate the sliders if True. Defaults to False.
-
-        .. versionadded:: 25.07.0
+        If ``True``, add a play button to the sliders to automatically step through
+        the slices.
+    errorbars:
+        Show errorbars in 1d plots if ``True``.
+    figsize:
+        The width and height of the figure, in inches.
+    grid:
+        Show grid if ``True``.
+    legend:
+        Show legend if ``True``. If ``legend`` is a tuple, it should contain the
+        ``(x, y)`` coordinates of the legend's anchor point in axes coordinates.
+    logc:
+        If ``True``, use logarithmic scale for colorscale (2d plots only).
+    logx:
+        If ``True``, use logarithmic scale for x-axis.
+    logy:
+        If ``True``, use logarithmic scale for y-axis.
+    mask_cmap:
+        Colormap to use for masks in 2d plots.
+    mask_color:
+        Color of masks.
+    nan_color:
+        Color to use for NaN values in 2d plots.
+    norm:
+        Set to ``'log'`` for a logarithmic y-axis (1d plots) or logarithmic colorscale
+        (2d plots). Legacy, prefer ``logy`` and ``logc`` instead.
+    scale:
+        Change axis scaling between ``log`` and ``linear``. For example, specify
+        ``scale={'time': 'log'}`` if you want log-scale for the ``time`` dimension.
+        Legacy, prefer ``logx`` and ``logy`` instead.
+    title:
+        The figure title.
+    vmax:
+        Upper limit for data to be displayed (y-axis for 1d plots, colorscale for
+        2d plots). Legacy, prefer ``ymax`` and ``cmax`` instead.
+    vmin:
+        Lower limit for data to be displayed (y-axis for 1d plots, colorscale for
+        2d plots). Legacy, prefer ``ymin`` and ``cmin`` instead.
+    xlabel:
+        Label for x-axis.
+    xmax:
+        Upper limit for x-axis.
+    xmin:
+        Lower limit for x-axis.
+    ylabel:
+        Label for y-axis.
+    ymax:
+        Upper limit for y-axis.
+    ymin:
+        Lower limit for y-axis.
     **kwargs:
-        See :py:func:`plopp.plot` for the full list of figure customization arguments.
+        Additional arguments forwarded to the underlying plotting library.
     """
     return Slicer(
         obj,
         keep=keep,
+        aspect=aspect,
         autoscale=autoscale,
-        vmin=vmin,
-        vmax=vmax,
-        coords=coords,
         cbar=cbar,
+        clabel=clabel,
+        cmap=cmap,
+        cmax=cmax,
+        cmin=cmin,
+        coords=coords,
         enable_player=enable_player,
+        errorbars=errorbars,
+        figsize=figsize,
+        grid=grid,
+        legend=legend,
+        logc=logc,
+        logx=logx,
+        logy=logy,
+        mask_color=mask_color,
+        nan_color=nan_color,
+        norm=norm,
+        scale=scale,
+        title=title,
+        vmax=vmax,
+        vmin=vmin,
+        xlabel=xlabel,
+        xmax=xmax,
+        xmin=xmin,
+        ylabel=ylabel,
+        ymax=ymax,
+        ymin=ymin,
         **kwargs,
     ).figure

plopp/plotting/superplot.py

@@ -1,6 +1,9 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
 
+from typing import Literal
+
+import scipp as sc
 
 from ..core.typing import FigureLike, Plottable
 from .slicer import Slicer
@@ -9,6 +12,29 @@ from .slicer import Slicer
 def superplot(
     obj: Plottable,
     keep: str | None = None,
+    *,
+    aspect: Literal['auto', 'equal', None] = None,
+    autoscale: bool = True,
+    coords: list[str] | None = None,
+    enable_player: bool = False,
+    errorbars: bool = True,
+    figsize: tuple[float, float] | None = None,
+    grid: bool = False,
+    legend: bool | tuple[float, float] = True,
+    logx: bool | None = None,
+    logy: bool | None = None,
+    mask_color: str = 'black',
+    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,
 ) -> FigureLike:
     """
@@ -25,8 +51,56 @@ def superplot(
         The single dimension to be kept, all remaining dimensions will be sliced.
         This should be a single string. If no dim is provided, the last/inner dim will
         be kept.
+    aspect:
+        Aspect ratio for the axes.
+    autoscale:
+        Automatically scale the axes/colormap if ``True``.
+    coords:
+        If supplied, use these coords instead of the input's dimension coordinates.
+    enable_player:
+        If ``True``, add a play button to the sliders to automatically step through
+        the slices.
+    errorbars:
+        Show errorbars in 1d plots if ``True``.
+    figsize:
+        The width and height of the figure, in inches.
+    grid:
+        Show grid if ``True``.
+    legend:
+        Show legend if ``True``. If ``legend`` is a tuple, it should contain the
+        ``(x, y)`` coordinates of the legend's anchor point in axes coordinates.
+    logx:
+        If ``True``, use logarithmic scale for x-axis.
+    logy:
+        If ``True``, use logarithmic scale for y-axis.
+    mask_color:
+        Color of masks in 1d plots.
+    norm:
+        Set to ``'log'`` for a logarithmic y-axis. Legacy, prefer ``logy`` instead.
+    scale:
+        Change axis scaling between ``log`` and ``linear``. For example, specify
+        ``scale={'time': 'log'}`` if you want log-scale for the ``time`` dimension.
+        Legacy, prefer ``logx`` instead.
+    title:
+        The figure title.
+    vmax:
+        Upper limit for data to be displayed (y-axis). Legacy, prefer ``ymax`` instead.
+    vmin:
+        Lower limit for data to be displayed (y-axis). Legacy, prefer ``ymin`` instead.
+    xlabel:
+        Label for x-axis.
+    xmax:
+        Upper limit for x-axis.
+    xmin:
+        Lower limit for x-axis.
+    ylabel:
+        Label for y-axis.
+    ymax:
+        Upper limit for y-axis.
+    ymin:
+        Lower limit for y-axis.
     **kwargs:
-        See :py:func:`plopp.plot` for the full list of line customization arguments.
+        Additional arguments forwarded to the underlying plotting library.
 
     Returns
     -------
@@ -36,7 +110,33 @@ def superplot(
     """
     from ..widgets import LineSaveTool
 
-    slicer = Slicer(obj, keep=keep, **kwargs)
+    slicer = Slicer(
+        obj,
+        keep=keep,
+        aspect=aspect,
+        autoscale=autoscale,
+        coords=coords,
+        enable_player=enable_player,
+        errorbars=errorbars,
+        figsize=figsize,
+        grid=grid,
+        legend=legend,
+        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,
+    )
     slicer.figure.right_bar.add(
         LineSaveTool(
             data_node=slicer.slice_nodes[0],

plopp/plotting/xyplot.py

@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 # Copyright (c) 2023 Scipp contributors (https://github.com/scipp)
 
+from typing import Literal
 
 import scipp as sc
 from numpy import ndarray
@@ -39,6 +40,25 @@ def _make_data_array(x: sc.Variable, y: sc.Variable) -> sc.DataArray:
 def xyplot(
     x: sc.Variable | ndarray | list | Node,
     y: sc.Variable | ndarray | list | Node,
+    aspect: Literal['auto', 'equal', None] = None,
+    autoscale: bool = True,
+    errorbars: bool = True,
+    figsize: tuple[float, float] | None = None,
+    grid: bool = False,
+    legend: bool | tuple[float, float] = True,
+    logx: bool | None = None,
+    logy: bool | 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,
 ) -> FigureLike:
     """
@@ -53,9 +73,72 @@ def xyplot(
         Must be one-dimensional.
     y:
         The variable to use as the data for the vertical axis. Must be one-dimensional.
+    aspect:
+        Aspect ratio for the axes.
+    autoscale:
+        Automatically scale the axes on updates if ``True``.
+    errorbars:
+        Show errorbars in 1d plots if ``True``.
+    figsize:
+        The width and height of the figure, in inches.
+    grid:
+        Show grid if ``True``.
+    legend:
+        Show legend if ``True``. If ``legend`` is a tuple, it should contain the
+        ``(x, y)`` coordinates of the legend's anchor point in axes coordinates.
+    logx:
+        If ``True``, use logarithmic scale for x-axis.
+    logy:
+        If ``True``, use logarithmic scale for y-axis.
+    norm:
+        Set to ``'log'`` for a logarithmic y-axis. Legacy, prefer ``logy`` instead.
+    scale:
+        Change axis scaling between ``log`` and ``linear``. For example, specify
+        ``scale={'time': 'log'}`` if you want log-scale for the ``time`` dimension.
+        Legacy, prefer ``logx`` instead.
+    title:
+        The figure title.
+    vmax:
+        Upper limit for data to be displayed (y-axis). Legacy, prefer ``ymax`` instead.
+    vmin:
+        Lower limit for data to be displayed (y-axis). Legacy, prefer ``ymin`` instead.
+    xlabel:
+        Label for x-axis.
+    xmax:
+        Upper limit for x-axis.
+    xmin:
+        Lower limit for x-axis.
+    ylabel:
+        Label for y-axis.
+    ymax:
+        Upper limit for y-axis.
+    ymin:
+        Lower limit for y-axis.
     **kwargs:
-        See :py:func:`plopp.plot`.
+        All other kwargs are forwarded the underlying plotting library.
     """
     x = Node(to_variable, x)
     y = Node(to_variable, y)
-    return linefigure(Node(_make_data_array, x=x, y=y), **kwargs)
+    return linefigure(
+        Node(_make_data_array, x=x, y=y),
+        aspect=aspect,
+        autoscale=autoscale,
+        errorbars=errorbars,
+        figsize=figsize,
+        grid=grid,
+        legend=legend,
+        logx=logx,
+        logy=logy,
+        norm=norm,
+        scale=scale,
+        title=title,
+        vmax=vmax,
+        vmin=vmin,
+        xlabel=xlabel,
+        xmax=xmax,
+        xmin=xmin,
+        ylabel=ylabel,
+        ymax=ymax,
+        ymin=ymin,
+        **kwargs,
+    )

plopp/utils/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+
+import lazy_loader as lazy
+
+__getattr__, __dir__, __all__ = lazy.attach_stub(__name__, __file__)

plopp/utils/__init__.pyi

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+
+from .arg_parse import parse_mutually_exclusive
+from .deprecation import deprecated
+
+__all__ = ['deprecated', 'parse_mutually_exclusive']

plopp/utils/arg_parse.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: BSD-3-Clause
+# Copyright (c) 2025 Scipp contributors (https://github.com/scipp)
+
+from typing import Any
+
+
+def parse_mutually_exclusive(**kwargs) -> Any | None:
+    """
+    Check that only one of the provided keyword arguments is not None.
+    Return that one.
+    Additionally, if the final value is a string (either 'linear' or 'log'), return a
+    boolean indicating whether the value is 'log'.
+    """
+    values = list(kwargs.values())
+    if None not in values:
+        raise ValueError(f'Only one of {list(kwargs.keys())} can be specified.')
+    out = ([v for v in values if v is not None] or [None])[0]
+    match out:
+        case 'linear':
+            return False
+        case 'log':
+            return True
+        case _:
+            return out

plopp/{utils.py → utils/deprecation.py}

@@ -22,6 +22,3 @@ def deprecated(message: str = '') -> Callable:
         return wrapper
 
     return decorator
-
-
-__all__ = ['deprecated']

plopp/widgets/toolbar.py

@@ -60,12 +60,12 @@ def make_toolbar_canvas2d(view: GraphicalView) -> Toolbar:
     """
 
     def logx() -> None:
-        view.canvas.logx()
+        view.canvas.toggle_logx()
         view.autoscale()
         view.canvas.draw()
 
     def logy() -> None:
-        view.canvas.logy()
+        view.canvas.toggle_logy()
         view.autoscale()
         view.canvas.draw()
 

{plopp-25.9.0.dist-info → plopp-25.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plopp
-Version: 25.9.0
+Version: 25.10.0
 Summary: Visualization library for Scipp
 Author: Scipp contributors
 License-Expression: BSD-3-Clause