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

plopp/plotting/inspector.py

@@ -38,9 +38,31 @@ def inspector(
     obj: Plottable,
     dim: str | None = None,
     *,
+    aspect: Literal['auto', 'equal', None] = None,
+    autoscale: bool = True,
+    cbar: bool = True,
+    clabel: str | None = None,
+    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,
+    logy: bool | None = None,
+    mask_cmap: str = 'gray',
+    mask_color: str = 'black',
+    nan_color: str | None = None,
+    norm: Literal['linear', 'log', None] = None,
     operation: Literal['sum', 'mean', 'min', 'max'] = 'sum',
     orientation: Literal['horizontal', 'vertical'] = 'horizontal',
-    cbar: bool = True,
+    title: str | None = None,
+    vmax: sc.Variable | float | None = None,
+    vmin: sc.Variable | float | None = None,
+    xlabel: str | None = None,
+    ylabel: str | None = None,
+    ymax: sc.Variable | float | None = None,
+    ymin: sc.Variable | float | None = None,
     **kwargs,
 ):
     """
@@ -66,16 +88,65 @@ def inspector(
         the dimension that remains in the one-dimensional slices generated by adding
         markers on the image. If no dim is provided, the last (inner) dim of the input
         data will be used.
+    aspect:
+        Aspect ratio for the axes.
+    autoscale:
+        Automatically scale the axes/colormap on updates if ``True``.
+    cbar:
+        Show colorbar if ``True`` (2d figure).
+    clabel:
+        Label for colorscale (2d figure).
+    cmax:
+        Upper limit for colorscale (2d figure).
+    cmin:
+        Lower limit for colorscale (2d figure).
+    errorbars:
+        Show errorbars if ``True`` (1d figure).
+    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
+        (1d figure).
+    logc:
+        If ``True``, use logarithmic scale for colorscale (2d figure).
+    logy:
+        If ``True``, use logarithmic scale for y-axis (1d figure).
+    mask_cmap:
+        Colormap to use for masks in 2d figure.
+    mask_color:
+        Color of masks (overrides ``mask_cmap``).
+    nan_color:
+        Color to use for NaN values in 2d figure.
+    norm:
+        Set to ``'log'`` for a logarithmic y-axis (1d figure) or logarithmic colorscale
+        (2d figure). Legacy, prefer ``logy`` and ``logc`` instead.
     operation:
         The operation to apply along the third (undisplayed) dimension specified by
         ``dim``.
     orientation:
         Display the two panels side-by-side ('horizontal') or one below the other
         ('vertical').
-    cbar:
-        Show a colorbar on the image.
+    title:
+        The figure title.
+    vmax:
+        Upper limit for data to be displayed (y-axis for 1d figure, colorscale for
+        2d figure). Legacy, prefer ``ymax`` and ``cmax`` instead.
+    vmin:
+        Lower limit for data to be displayed (y-axis for 1d figure, colorscale for
+        2d figure). Legacy, prefer ``ymin`` and ``cmin`` instead.
+    xlabel:
+        Label for x-axis (2d figure).
+    ylabel:
+        Label for y-axis (2d figure).
+    ymax:
+        Upper limit for y-axis (1d figure).
+    ymin:
+        Lower limit for y-axis (1d figure).
     **kwargs:
-        See :py:func:`plopp.plot` for the full list of figure customization arguments.
+        Additional arguments forwarded to the underlying plotting library.
 
     Returns
     -------
@@ -83,7 +154,19 @@ def inspector(
         A :class:`Box` which will contain two :class:`Figure` and one slider widget.
     """
 
-    f1d = linefigure()
+    f1d = linefigure(
+        autoscale=autoscale,
+        errorbars=errorbars,
+        grid=grid,
+        legend=legend,
+        logy=logy,
+        mask_color=mask_color,
+        norm=norm,
+        vmax=vmax,
+        vmin=vmin,
+        ymax=ymax,
+        ymin=ymin,
+    )
     require_interactive_figure(f1d, 'inspector')
 
     in_node = Node(preprocess, obj, ignore_size=True)
@@ -97,7 +180,28 @@ def inspector(
         dim = data.dims[-1]
     bin_edges_node = Node(_to_bin_edges, in_node, dim=dim)
     op_node = Node(_apply_op, da=bin_edges_node, op=operation, dim=dim)
-    f2d = imagefigure(op_node, cbar=cbar, **kwargs)
+    f2d = imagefigure(
+        op_node,
+        aspect=aspect,
+        cbar=cbar,
+        clabel=clabel,
+        cmax=cmax,
+        cmin=cmin,
+        figsize=figsize,
+        grid=grid,
+        logc=logc,
+        mask_color=mask_color,
+        nan_color=nan_color,
+        norm=norm,
+        title=title,
+        vmax=vmax,
+        vmin=vmin,
+        xlabel=xlabel,
+        ylabel=ylabel,
+        ymax=ymax,
+        ymin=ymin,
+        **kwargs,
+    )
 
     from ..widgets import Box, PointsTool
 

plopp/plotting/mesh3d.py

@@ -39,17 +39,24 @@ def _preprocess_mesh(
 
 
 def mesh3d(
+    *,
     vertices: Plottable,
     faces: Plottable,
     vertexcolors: Plottable | None = None,
+    autoscale: bool = True,
+    camera: Camera | None = None,
+    clabel: str | None = None,
+    cmap: str = 'viridis',
+    cmax: sc.Variable | float = None,
+    cmin: sc.Variable | float = None,
     edgecolor: str | None = 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,
-    cmap: str = 'viridis',
-    camera: Camera | None = None,
+    vmin: sc.Variable | float = None,
     **kwargs,
 ) -> FigureLike:
     """
@@ -66,22 +73,42 @@ def mesh3d(
     vertexcolors:
         The colors of the vertices of the mesh. If ``None``, the mesh will have a
         single solid color.
+    autoscale:
+        Automatically scale the colormap on updates if ``True``.
+    camera:
+        Initial camera configuration (position, target).
+    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``).
     edgecolor:
         The color of the edges. If None, no edges are drawn.
     figsize:
-        The size of the figure.
+        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:
-        The normalization of the colormap.
+        Set to ``'log'`` for a logarithmic colorscale (only applicable if ``cbar`` is
+        ``True``). Legacy, prefer ``logc`` instead.
     title:
-        The title of the figure.
+        The figure title.
     vmin:
-        The minimum value of the colormap.
+        Lower limit for the colorscale for (only applicable if ``cbar`` is ``True``).
+        Legacy, prefer ``cmin`` instead.
     vmax:
-        The maximum value of the colormap.
-    cmap:
-        The colormap to use.
-    camera:
-        The camera configuration.
+        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.
     """
     from ..graphics import mesh3dfigure
 
@@ -95,14 +122,20 @@ def mesh3d(
     fig = mesh3dfigure(
         input_node,
         vertexcolors=vertexcolors,
+        autoscale=autoscale,
+        camera=camera,
+        clabel=clabel,
+        cmax=cmax,
+        cmin=cmin,
+        cmap=cmap,
         edgecolor=edgecolor,
         figsize=figsize,
+        logc=logc,
+        nan_color=nan_color,
         norm=norm,
         title=title,
-        vmin=vmin,
         vmax=vmax,
-        cmap=cmap,
-        camera=camera,
+        vmin=vmin,
         **kwargs,
     )
     return fig

plopp/plotting/plot.py

@@ -4,30 +4,51 @@
 from functools import partial
 from typing import Literal
 
-from scipp import Variable
+import scipp as sc
 
 from ..core.typing import FigureLike, PlottableMulti
 from ..graphics import imagefigure, linefigure
-from .common import input_to_nodes, preprocess, raise_multiple_inputs_for_2d_plot_error
+from .common import (
+    categorize_args,
+    input_to_nodes,
+    preprocess,
+    raise_multiple_inputs_for_2d_plot_error,
+)
 
 
 def plot(
     obj: PlottableMulti,
     *,
     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,
     coords: list[str] | None = None,
     errorbars: bool = True,
     figsize: tuple[float, float] | None = None,
     grid: bool = False,
     ignore_size: bool = False,
-    mask_color: str = 'black',
-    norm: Literal['linear', 'log'] = 'linear',
+    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,
-    vmin: Variable | float | None = None,
-    vmax: Variable | float | None = None,
-    legend: bool | tuple[float, float] = True,
+    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:
     """Plot a Scipp object.
@@ -38,8 +59,18 @@ def plot(
         The object to be plotted.
     aspect:
         Aspect ratio for the axes.
+    autoscale:
+        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.
     errorbars:
@@ -49,34 +80,51 @@ def plot(
     grid:
         Show grid if ``True``.
     ignore_size:
-        If ``True``, skip the check that prevents the rendering of very large data
-        objects.
+        If ``True``, skip the check that prevents the rendering of very large data.
+    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 in 1d plots.
+        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).
+        (2d plots). Legacy, prefer ``logy`` and ``logc`` instead.
     scale:
         Change axis scaling between ``log`` and ``linear``. For example, specify
-        ``scale={'tof': 'log'}`` if you want log-scale for the ``tof`` dimension.
+        ``scale={'time': 'log'}`` if you want log-scale for the ``time`` dimension.
+        Legacy, prefer ``logx`` and ``logy`` instead.
     title:
         The figure title.
-    vmin:
-        Lower bound for data to be displayed (y-axis for 1d plots, colorscale for
-        2d plots).
     vmax:
-        Upper bound for data to be displayed (y-axis for 1d plots, colorscale for
-        2d plots).
-    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.
+        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:
-        All other kwargs are directly forwarded to Matplotlib, the underlying plotting
-        library. The underlying functions called are the following:
-
-        - 1d data with a non bin-edge coordinate: ``plot``
-        - 1d data with a bin-edge coordinate: ``step``
-        - 2d data: ``pcolormesh``
+        All other kwargs are forwarded to the underlying plotting library.
 
     Returns
     -------
@@ -84,17 +132,37 @@ def plot(
         A figure.
     """
 
-    common_args = {
-        'aspect': aspect,
-        'grid': grid,
-        'norm': norm,
-        'scale': scale,
-        'title': title,
-        'vmin': vmin,
-        'vmax': vmax,
-        'figsize': figsize,
+    args = categorize_args(
+        aspect=aspect,
+        autoscale=autoscale,
+        cbar=cbar,
+        clabel=clabel,
+        cmap=cmap,
+        cmax=cmax,
+        cmin=cmin,
+        errorbars=errorbars,
+        figsize=figsize,
+        grid=grid,
+        legend=legend,
+        logc=logc,
+        logx=logx,
+        logy=logy,
+        mask_cmap=mask_cmap,
+        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,
-    }
+    )
 
     nodes = input_to_nodes(
         obj, processor=partial(preprocess, ignore_size=ignore_size, coords=coords)
@@ -110,17 +178,11 @@ def plot(
         )
     ndim = ndims.pop()
     if ndim == 1:
-        return linefigure(
-            *nodes,
-            errorbars=errorbars,
-            mask_color=mask_color,
-            legend=legend,
-            **common_args,
-        )
+        return linefigure(*nodes, **args['1d'])
     elif ndim == 2:
         if len(nodes) > 1:
             raise_multiple_inputs_for_2d_plot_error(origin='plot')
-        return imagefigure(*nodes, cbar=cbar, **common_args)
+        return imagefigure(*nodes, **args['2d'])
     else:
         raise ValueError(
             'The plot function can only plot 1d and 2d data, got input '

plopp/plotting/scatter.py

@@ -8,26 +8,33 @@ from typing import Literal
 import scipp as sc
 
 from ..core.typing import FigureLike, PlottableMulti
-from .common import check_not_binned, from_compatible_lib, input_to_nodes
+from .common import check_not_binned, check_size, from_compatible_lib, input_to_nodes
 
 
 def _preprocess_scatter(
     obj: PlottableMulti,
     x: str,
     y: str,
+    pos: str | None,
     size: str | None,
     name: str | None = None,
+    ignore_size: bool = False,
 ):
     da = from_compatible_lib(obj)
     check_not_binned(da)
 
-    cnames = [x, y]
+    if pos is not None:
+        coords = {k: getattr(da.coords[pos].fields, k) for k in (x, y)}
+    else:
+        coords = {k: da.coords[k] for k in (x, y)}
+
     if isinstance(size, str):
-        cnames.append(size)
-    coords = {k: da.coords[k] for k in cnames}
+        coords[size] = da.coords[size]
     out = sc.DataArray(data=da.data, masks=da.masks, coords=coords)
     if out.ndim != 1:
         out = out.flatten(to=uuid.uuid4().hex)
+    if not ignore_size:
+        check_size(out)
     if name is not None:
         out.name = name
     return out
@@ -38,15 +45,35 @@ def scatter(
     *,
     x: str = 'x',
     y: str = 'y',
-    size: str | float | None = None,
-    figsize: tuple[float, float] | None = None,
-    norm: Literal['linear', 'log'] = 'linear',
-    title: str | None = None,
-    vmin: sc.Variable | float = None,
-    vmax: sc.Variable | float = None,
-    cbar: bool = False,
+    pos: str | None = None,
+    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,
+    figsize: tuple[float, float] | None = None,
+    grid: bool = False,
+    ignore_size: bool = False,
     legend: bool | tuple[float, float] = True,
+    logc: bool | None = None,
+    logx: bool | None = None,
+    logy: bool | None = None,
+    mask_color: str = 'black',
+    nan_color: str | None = None,
+    norm: Literal['linear', 'log', None] = None,
+    scale: dict[str, str] | None = None,
+    size: str | float | 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:
     """
@@ -62,50 +89,114 @@ def scatter(
         The name of the coordinate that is to be used for the X positions.
     y:
         The name of the coordinate that is to be used for the Y positions.
-    size:
-        The size of the marker. If a float is supplied, all markers will have the same
-        size. If a string is supplied, it will be the name of the coordinate that is to
-        be used for the size of the markers.
+    pos:
+        The name of the vector coordinate that is to be used for the positions.
+    aspect:
+        Aspect ratio for the axes.
+    autoscale:
+        Automatically scale the axes/colormap if ``True``.
+    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 width and height of the figure, in inches.
+    grid:
+        Show grid if ``True``.
+    ignore_size:
+        If ``True``, skip the check that prevents the rendering of very large data.
+    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:
+        Set to ``True`` for a logarithmic colorscale (only applicable if ``cbar`` is
+        ``True``).
+    logx:
+        If ``True``, use logarithmic scale for x-axis.
+    logy:
+        If ``True``, use logarithmic scale for y-axis.
+    mask_color:
+        Color of markers for masked data.
+    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``).
+        ``True``). Legacy, prefer ``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.
     vmin:
-        Lower bound for the colorscale for (only applicable if ``cbar`` is ``True``).
+        Lower limit for the colorscale for (only applicable if ``cbar`` is ``True``).
+        Legacy, prefer ``cmin`` instead.
     vmax:
-        Upper bound for the colorscale for (only applicable if ``cbar`` is ``True``).
-    cbar:
-        Show colorbar if ``True``. If ``cbar`` is ``True``, the marker will be colored
-        using the data values in the supplied data array.
-    cmap:
-        The colormap to be used for the colorscale.
-    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.
+        Upper limit for the colorscale for (only applicable if ``cbar`` is ``True``).
+        Legacy, prefer ``cmax`` 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:
         All other kwargs are forwarded the underlying plotting library.
     """
     from ..graphics import scatterfigure
 
     nodes = input_to_nodes(
-        obj, processor=partial(_preprocess_scatter, x=x, y=y, size=size)
+        obj,
+        processor=partial(
+            _preprocess_scatter, x=x, y=y, pos=pos, size=size, ignore_size=ignore_size
+        ),
     )
 
     return scatterfigure(
         *nodes,
-        x=x,
-        y=y,
-        size=size,
+        aspect=aspect,
+        autoscale=autoscale,
+        cbar=cbar,
+        clabel=clabel,
+        cmap=cmap,
+        cmax=cmax,
+        cmin=cmin,
         figsize=figsize,
+        grid=grid,
+        legend=legend,
+        logc=logc,
+        logx=logx,
+        logy=logy,
+        mask_color=mask_color,
+        nan_color=nan_color,
         norm=norm,
+        scale=scale,
+        size=size,
         title=title,
-        vmin=vmin,
         vmax=vmax,
-        cmap=cmap,
-        cbar=cbar,
-        legend=legend,
+        vmin=vmin,
+        x=x,
+        xlabel=xlabel,
+        xmax=xmax,
+        xmin=xmin,
+        y=y,
+        ylabel=ylabel,
+        ymax=ymax,
+        ymin=ymin,
         **kwargs,
     )