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

plopp/backends/matplotlib/canvas.py

@@ -12,6 +12,7 @@ from mpl_toolkits.axes_grid1 import make_axes_locatable
 
 from ...core.utils import maybe_variable_to_number, scalar_to_string
 from ...graphics.bbox import BoundingBox
+from ...utils import parse_mutually_exclusive
 from .utils import fig_to_bytes, is_sphinx_build, make_figure, make_legend
 
 
@@ -82,6 +83,24 @@ class Canvas:
     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.
+    xmin:
+        The minimum value for the x axis.
+    xmax:
+        The maximum value for the x axis.
+    ymin:
+        The minimum value for the y axis.
+    ymax:
+        The maximum value for the y axis.
+    logx:
+        If ``True``, use a logarithmic scale for the x axis.
+    logy:
+        If ``True``, use a logarithmic scale for the y axis.
+    xlabel:
+        The label for the x axis.
+    ylabel:
+        The label for the y axis.
+    norm:
+        Set to ``'log'`` for a logarithmic y-axis (legacy, prefer ``logy`` instead).
     """
 
     def __init__(
@@ -91,11 +110,20 @@ class Canvas:
         figsize: tuple[float, float] | None = None,
         title: str | None = None,
         grid: bool = False,
-        user_vmin: sc.Variable | float = None,
-        user_vmax: sc.Variable | float = None,
+        user_vmin: sc.Variable | float | None = None,
+        user_vmax: sc.Variable | float | None = None,
         aspect: Literal['auto', 'equal', None] = None,
         cbar: bool = False,
         legend: bool | tuple[float, float] = True,
+        xmin: sc.Variable | float | None = None,
+        xmax: sc.Variable | float | None = None,
+        ymin: sc.Variable | float | None = None,
+        ymax: sc.Variable | float | None = None,
+        logx: bool = False,
+        logy: bool = False,
+        xlabel: str | None = None,
+        ylabel: str | None = None,
+        norm: Literal['linear', 'log', None] = None,
         **ignored,
     ):
         # Note on the `**ignored`` keyword arguments: the figure which owns the canvas
@@ -107,12 +135,20 @@ class Canvas:
         # Instead, we forward all the kwargs from the figure to both the canvas and the
         # artist, and filter out the artist kwargs with `**ignored`.
 
+        ymin = parse_mutually_exclusive(vmin=user_vmin, ymin=ymin)
+        ymax = parse_mutually_exclusive(vmax=user_vmax, ymax=ymax)
+        logy = parse_mutually_exclusive(norm=norm, logy=logy)
+
         self.fig = None
         self.ax = ax
         self.cax = cax
         self.bbox = BoundingBox()
-        self._user_vmin = user_vmin
-        self._user_vmax = user_vmax
+        self._xmin = xmin
+        self._xmax = xmax
+        self._ymin = ymin
+        self._ymax = ymax
+        self._xlabel = xlabel
+        self._ylabel = ylabel
         self.units = {}
         self.dims = {}
         self._legend = legend
@@ -143,6 +179,15 @@ class Canvas:
             self.ax.set_title(title)
         self._coord_formatters = []
 
+        if logx:
+            self.xscale = 'log'
+        if logy:
+            self.yscale = 'log'
+        if xlabel is not None:
+            self.xlabel = xlabel
+        if ylabel is not None:
+            self.ylabel = ylabel
+
     def is_widget(self):
         return hasattr(self.fig.canvas, "on_widget_constructed")
 
@@ -225,8 +270,10 @@ class Canvas:
         self.ax.format_coord = self.format_coord
         key = 'y' if 'y' in self.units else 'data'
         self.bbox = BoundingBox(
-            ymin=maybe_variable_to_number(self._user_vmin, unit=self.units[key]),
-            ymax=maybe_variable_to_number(self._user_vmax, unit=self.units[key]),
+            xmin=maybe_variable_to_number(self._xmin, unit=self.units['x']),
+            xmax=maybe_variable_to_number(self._xmax, unit=self.units['x']),
+            ymin=maybe_variable_to_number(self._ymin, unit=self.units[key]),
+            ymax=maybe_variable_to_number(self._ymax, unit=self.units[key]),
         )
 
     def register_format_coord(self, formatter):
@@ -414,6 +461,28 @@ class Canvas:
     def yrange(self, value: tuple[float, float]):
         self.ax.set_ylim(value)
 
+    @property
+    def logx(self) -> bool:
+        """
+        Get or set whether the x-axis is in logarithmic scale.
+        """
+        return self.xscale == 'log'
+
+    @logx.setter
+    def logx(self, value: bool):
+        self.xscale = 'log' if value else 'linear'
+
+    @property
+    def logy(self) -> bool:
+        """
+        Get or set whether the y-axis is in logarithmic scale.
+        """
+        return self.yscale == 'log'
+
+    @logy.setter
+    def logy(self, value: bool):
+        self.yscale = 'log' if value else 'linear'
+
     @property
     def grid(self) -> bool:
         """
@@ -463,14 +532,26 @@ class Canvas:
         """
         self.fig.canvas.toolbar.save_figure()
 
-    def logx(self):
+    def toggle_logx(self):
         """
         Toggle the scale between ``linear`` and ``log`` along the horizontal axis.
         """
         self.xscale = 'log' if self.xscale == 'linear' else 'linear'
 
-    def logy(self):
+    def toggle_logy(self):
         """
         Toggle the scale between ``linear`` and ``log`` along the vertical axis.
         """
         self.yscale = 'log' if self.yscale == 'linear' else 'linear'
+
+    def has_user_xlabel(self) -> bool:
+        """
+        Return ``True`` if the user has set an x-axis label.
+        """
+        return self._xlabel is not None
+
+    def has_user_ylabel(self) -> bool:
+        """
+        Return ``True`` if the user has set a y-axis label.
+        """
+        return self._ylabel is not None

plopp/backends/matplotlib/line.py

@@ -50,7 +50,7 @@ class Line:
         uid: str | None = None,
         artist_number: int = 0,
         errorbars: bool = True,
-        mask_color: str = 'black',
+        mask_color: str | None = None,
         **kwargs,
     ):
         check_ndim(data, ndim=1, origin='Line')
@@ -69,6 +69,8 @@ class Line:
         self._dim = self._data.dim
         self._unit = self._data.unit
         self._coord = self._data.coords[self._dim]
+        if mask_color is None:
+            mask_color = 'black'
 
         aliases = {'ls': 'linestyle', 'lw': 'linewidth', 'c': 'color'}
         for key, alias in aliases.items():

plopp/backends/matplotlib/scatter.py

@@ -56,7 +56,7 @@ class Scatter:
         size: str | float | None = None,
         artist_number: int = 0,
         colormapper: ColorMapper | None = None,
-        mask_color: str = 'black',
+        mask_color: str | None = None,
         cbar: bool = False,
         **kwargs,
     ):
@@ -117,7 +117,7 @@ class Scatter:
             ymask,
             s=marker_size,
             marker=merged_kwargs['marker'],
-            edgecolors=mask_color,
+            edgecolors=mask_color or 'black',
             facecolor="None",
             linewidth=3.0,
             zorder=self._scatter.get_zorder() + 1,

plopp/backends/matplotlib/tiled.py

@@ -68,6 +68,8 @@ class Tiled:
         nrows: int,
         ncols: int,
         figsize: tuple[float, float] | None = None,
+        hspace: float = 0.05,
+        wspace: float = 0.1,
         **kwargs: Any,
     ) -> None:
         self.nrows = nrows
@@ -81,7 +83,9 @@ class Tiled:
             layout='constrained',
         )
 
-        self.gs = gridspec.GridSpec(nrows, ncols, figure=self.fig, **kwargs)
+        self.gs = gridspec.GridSpec(
+            nrows, ncols, figure=self.fig, wspace=wspace, hspace=hspace, **kwargs
+        )
         self.figures = np.full((nrows, ncols), None)
         self._history = []
 

plopp/backends/plotly/canvas.py

@@ -7,6 +7,7 @@ import scipp as sc
 
 from ...core.utils import maybe_variable_to_number
 from ...graphics.bbox import BoundingBox
+from ...utils import parse_mutually_exclusive
 
 
 class Canvas:
@@ -35,8 +36,17 @@ class Canvas:
         self,
         figsize: tuple[float, float] | None = None,
         title: str | None = None,
-        user_vmin: sc.Variable | float = None,
-        user_vmax: sc.Variable | float = None,
+        user_vmin: sc.Variable | float | None = None,
+        user_vmax: sc.Variable | float | None = 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,
+        logx: bool | None = None,
+        logy: bool | None = None,
+        xlabel: str | None = None,
+        ylabel: str | None = None,
+        norm: Literal['linear', 'log', None] = None,
         **ignored,
     ):
         # Note on the `**ignored`` keyword arguments: the figure which owns the canvas
@@ -48,6 +58,10 @@ class Canvas:
         # Instead, we forward all the kwargs from the figure to both the canvas and the
         # artist, and filter out the artist kwargs with `**ignored`.
 
+        ymin = parse_mutually_exclusive(vmin=user_vmin, ymin=ymin)
+        ymax = parse_mutually_exclusive(vmax=user_vmax, ymax=ymax)
+        logy = parse_mutually_exclusive(norm=norm, logy=logy)
+
         import plotly.graph_objects as go
 
         self.fig = go.FigureWidget(
@@ -70,8 +84,12 @@ class Canvas:
             }
         )
         self.figsize = figsize
-        self._user_vmin = user_vmin
-        self._user_vmax = user_vmax
+        self._xmin = xmin
+        self._xmax = xmax
+        self._ymin = ymin
+        self._ymax = ymax
+        self._xlabel = xlabel
+        self._ylabel = ylabel
         self.units = {}
         self.dims = {}
         self._own_axes = False
@@ -79,6 +97,17 @@ class Canvas:
             self.title = title
         self.bbox = BoundingBox()
 
+        logx = False if logx is None else logx
+        logy = False if logy is None else logy
+        if logx:
+            self.xscale = 'log'
+        if logy:
+            self.yscale = 'log'
+        if xlabel is not None:
+            self.xlabel = xlabel
+        if ylabel is not None:
+            self.ylabel = ylabel
+
     def to_widget(self):
         return self.fig
 
@@ -118,8 +147,10 @@ class Canvas:
         self.dtypes = dtypes
         key = 'y' if 'y' in self.units else 'data'
         self.bbox = BoundingBox(
-            ymin=maybe_variable_to_number(self._user_vmin, unit=self.units[key]),
-            ymax=maybe_variable_to_number(self._user_vmax, unit=self.units[key]),
+            xmin=maybe_variable_to_number(self._xmin, unit=self.units['x']),
+            xmax=maybe_variable_to_number(self._xmax, unit=self.units['x']),
+            ymin=maybe_variable_to_number(self._ymin, unit=self.units[key]),
+            ymax=maybe_variable_to_number(self._ymax, unit=self.units[key]),
         )
 
     @property
@@ -255,6 +286,28 @@ class Canvas:
     def yrange(self, value: tuple[float, float]):
         self.fig.layout.yaxis.range = value
 
+    @property
+    def logx(self) -> bool:
+        """
+        Get or set whether the x-axis is in logarithmic scale.
+        """
+        return self.xscale == 'log'
+
+    @logx.setter
+    def logx(self, value: bool):
+        self.xscale = 'log' if value else 'linear'
+
+    @property
+    def logy(self) -> bool:
+        """
+        Get or set whether the y-axis is in logarithmic scale.
+        """
+        return self.yscale == 'log'
+
+    @logy.setter
+    def logy(self, value: bool):
+        self.yscale = 'log' if value else 'linear'
+
     def reset_mode(self):
         """
         Reset the modebar mode to nothing, to disable all zoom/pan tools.
@@ -290,13 +343,13 @@ class Canvas:
         """
         self.fig.write_image('figure.png')
 
-    def logx(self):
+    def toggle_logx(self):
         """
         Toggle the scale between ``linear`` and ``log`` along the horizontal axis.
         """
         self.xscale = 'log' if self.xscale in ('linear', None) else 'linear'
 
-    def logy(self):
+    def toggle_logy(self):
         """
         Toggle the scale between ``linear`` and ``log`` along the vertical axis.
         """
@@ -307,3 +360,15 @@ class Canvas:
 
     def update_legend(self):
         pass
+
+    def has_user_xlabel(self) -> bool:
+        """
+        Return ``True`` if the user has set an x-axis label.
+        """
+        return self._xlabel is not None
+
+    def has_user_ylabel(self) -> bool:
+        """
+        Return ``True`` if the user has set a y-axis label.
+        """
+        return self._ylabel is not None

plopp/backends/pythreejs/canvas.py

@@ -47,6 +47,10 @@ class Canvas:
         self.xscale = 'linear'
         self.yscale = 'linear'
         self.zscale = 'linear'
+        # TODO: Support setting labels on axes via xlabel, ylabel, zlabel args.
+        self._xlabel = None
+        self._ylabel = None
+        self._zlabel = None
         self.outline = None
         self.axticks = None
         self.figsize = np.asarray(figsize if figsize is not None else (600, 400))
@@ -398,3 +402,21 @@ class Canvas:
 
     def update_legend(self):
         pass
+
+    def has_user_xlabel(self) -> bool:
+        """
+        Return ``True`` if the user has set an x-axis label.
+        """
+        return self._xlabel is not None
+
+    def has_user_ylabel(self) -> bool:
+        """
+        Return ``True`` if the user has set a y-axis label.
+        """
+        return self._ylabel is not None
+
+    def has_user_zlabel(self) -> bool:
+        """
+        Return ``True`` if the user has set a z-axis label.
+        """
+        return self._zlabel is not None

plopp/backends/pythreejs/mesh3d.py

@@ -57,6 +57,7 @@ class Mesh3d:
         opacity: float = 1,
         edgecolor: str | None = None,
         artist_number: int = 0,
+        **ignored,
     ):
         import pythreejs as p3
 

plopp/backends/pythreejs/scatter3d.py

@@ -45,6 +45,8 @@ class Scatter3d:
         The opacity of the points.
     pixel_size:
         The size of the pixels in the plot. Deprecated (use size instead).
+    mask_color:
+        The color of the masked points. TODO: not yet implemented.
     """
 
     def __init__(
@@ -62,6 +64,7 @@ class Scatter3d:
         artist_number: int = 0,
         opacity: float = 1,
         pixel_size: sc.Variable | float | None = None,
+        mask_color: str | None = None,
     ):
         import pythreejs as p3
 

plopp/core/node_class.py

@@ -26,6 +26,18 @@ class Node:
     A node can be constructed from a callable ``func``, or a raw object. In the case
     of a raw object, a node wrapping the object will be created.
 
+    Nodes can have views attached to them, which are instances of :class:`View`. Views
+    can be notified when the node's data changes. When this happens, the view typically
+    requests data from its parent nodes, who in-turn request data from their parents,
+    traversing the graph from bottom to top.
+
+    Caching is used to avoid traversing the graph multiple times when data is
+    requested multiple times without any changes to the graph.
+
+    Leaf nodes are nodes that have neither children nor views. When such nodes are
+    notified of changes, they will call their ``func`` to ensure any side effects are
+    executed.
+
     Parameters
     ----------
     func:
@@ -160,6 +172,12 @@ class Node:
         _no_replace_append(self.views, view, 'view')
         view.graph_nodes[self.id] = self
 
+    def is_leaf(self) -> bool:
+        """
+        Whether the node is a leaf node (i.e. has neither children nor views).
+        """
+        return (not self.children) and (not self.views)
+
     def notify_children(self, message: Any) -> None:
         """
         Notify all of the node's children with ``message``.
@@ -172,6 +190,11 @@ class Node:
             The message to pass to the children.
         """
         self._data = None
+        if self.is_leaf():
+            # Special case: leaf nodes have no children nor views, so we always request
+            # data from parents and call ``self.func``.
+            self.request_data()
+            return
         self.notify_views(message)
         for child in self.children:
             child.notify_children(message)

plopp/data/examples.py

@@ -98,7 +98,9 @@ def three_bands(npeaks=200, per_peak=500, spread=30.0):
         data=sc.ones(sizes=xcoord.sizes, unit='counts'),
         coords={'x': xcoord, 'y': ycoord},
     )
-    return table.hist(y=300, x=300) + sc.scalar(1.0, unit='counts')
+    xedges = sc.linspace('x', -50, 350, num=nx + 1, unit='cm')
+    yedges = sc.linspace('y', -50, 350, num=ny + 1, unit='cm')
+    return table.hist(y=yedges, x=xedges) + sc.scalar(1.0, unit='counts')
 
 
 def clusters3d(nclusters=100, npercluster=2000):