Source code for plopp.plotting._plot

# SPDX-License-Identifier: BSD-3-Clause
# Copyright (c) 2023 Scipp contributors (https://github.com/scipp)

from functools import partial
from typing import Literal

import scipp as sc

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,
)


[docs] 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: Literal['band', 'bar', True, False] = True, figsize: tuple[float, float] | None = None, grid: bool = False, ignore_size: bool = False, ignore_sorted: bool = False, legend: bool | tuple[float, float] = True, hide_log_buttons: bool = False, 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: """Plot a Scipp object. Parameters ---------- obj: 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: Whether to add error bars to the line. Optionally, this can be a string to specify the error bar style. Valid values are 'band' and 'bar'. figsize: The width and height of the figure, in inches. grid: Show grid if ``True``. hide_log_buttons: If ``True``, the interactive log buttons will be hidden. ignore_size: If ``True``, skip the check that prevents the rendering of very large data. ignore_sorted: Do not check if the coordinates are sorted before plotting. 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: All other kwargs are forwarded to the underlying plotting library. Returns ------- : A figure. """ args = categorize_args( aspect=aspect, autoscale=autoscale, cbar=cbar, clabel=clabel, cmap=cmap, cmax=cmax, cmin=cmin, errorbars=errorbars, figsize=figsize, grid=grid, hide_log_buttons=hide_log_buttons, 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, ignore_sorted=ignore_sorted, coords=coords, ), ) ndims = set() for n in nodes: ndims.add(n().ndim) if len(ndims) > 1: raise ValueError( 'All items given to the plot function must have the same ' f'number of dimensions. Found dimensions {ndims}.' ) ndim = ndims.pop() if ndim == 1: return linefigure(*nodes, **args['1d']) elif ndim == 2: if len(nodes) > 1: raise_multiple_inputs_for_2d_plot_error(origin='plot') return imagefigure(*nodes, **args['2d']) else: raise ValueError( 'The plot function can only plot 1d and 2d data, got input ' f'with {ndim} dimensions' )