Generate and return dataset id if not given

examples/concepts.ipynb

@@ -276,7 +276,7 @@
    ],
    "source": [
     "plot.add_dataset(\n",
-    "    \"ref\",\n",
+    "    \"ref\",  # optional ID to update data later\n",
     "    particles=data2,\n",
     "    plot_kwargs=dict(label=\"Data B\", c=\"C2\", lw=2),\n",
     "    autoscale=True,\n",

xplt/__init__.py

@@ -16,6 +16,7 @@
 from .properties import *
 from .timestructure import *
 from .twiss import *
+from .util import AUTO
 
 # allow usage of xplt.mpl.* without importing matplotlib
 import matplotlib as mpl

xplt/base.py

@@ -23,7 +23,7 @@
 import numpy as np
 import pint
 
-from .util import defaults, flattened, defaults_for
+from .util import defaults, flattened, defaults_for, AUTO
 from .properties import Property, find_property, DataProperty, arb_unit
 
 
@@ -880,11 +880,11 @@ def _create_artists(self, callback, dataset_id=None):
                 Signature: (i, j, k, axis, p) -> artist
                 Where i, j, k are the subplot, twin-axis, trace indices respectively;
                 axis is the axis and the string p is the property to plot.
-            dataset_id (str | None): The dataset identifier if this plot represents multiple datasets.
-                If None, and a default dataset already exists, a new UUID is generated.
+            dataset_id (str | None | AUTO): The dataset identifier if this plot represents multiple datasets.
+                If :const:`xplt.AUTO`, a new UUID is generated.
         """
 
-        if dataset_id is None and None in self._artists:
+        if dataset_id is AUTO:
             dataset_id = str(uuid.uuid4())
         if dataset_id in self._artists:
             raise ValueError(f"Dataset identifier `{dataset_id}` already exists")

xplt/particles.py

@@ -304,7 +304,7 @@ def __init__(
         if add_default_dataset:
             self.add_dataset(None, particles=particles, mask=mask, plot_kwargs=plot_kwargs)
 
-    def add_dataset(self, id=None, *, plot_kwargs=None, **kwargs):
+    def add_dataset(self, id=AUTO, *, plot_kwargs=None, **kwargs):
         """Create artists for a new dataset to the plot and optionally update their values
 
         Args:
@@ -328,6 +328,8 @@ def create_artist(i, j, k, ax, p):
         if kwargs.get("particles") is not None:
             self.update(**kwargs, dataset_id=id)
 
+        return id
+
     def _symbol_for(self, p):
         symbol = super()._symbol_for(p)
         if p != self.on_x and not self._count_based(p):
@@ -489,7 +491,7 @@ def __init__(
         if add_default_dataset:
             self.add_dataset(None, particles=particles, mask=mask, plot_kwargs=plot_kwargs)
 
-    def add_dataset(self, id=None, *, plot_kwargs=None, **kwargs):
+    def add_dataset(self, id=AUTO, *, plot_kwargs=None, **kwargs):
         """Create artists for a new dataset to the plot and optionally update their values
 
         Args:
@@ -511,6 +513,8 @@ def create_artists(i, j, k, a, p):
         if kwargs.get("particles") is not None:
             self.update(**kwargs, dataset_id=id)
 
+        return id
+
     def update(self, particles, mask=None, *, autoscale=None, dataset_id=None):
         """Update plot with new data
 

xplt/timestructure.py

@@ -452,7 +452,7 @@ def bin_time(self):
         return self.bin_width
 
     def add_dataset(
-        self, id=None, *, plot_kwargs=None, particles=None, timeseries=None, **kwargs
+        self, id=AUTO, *, plot_kwargs=None, particles=None, timeseries=None, **kwargs
     ):
         """Create artists for a new dataset to the plot and optionally update their values
 
@@ -618,7 +618,7 @@ def __init__(
 
     def add_dataset(
         self,
-        id=None,
+        id=AUTO,
         *,
         plot_kwargs=None,
         averaging_shadow=True,
@@ -667,6 +667,8 @@ def create_artists(i, j, k, ax, p):
         if kwargs.get("particles") is not None or kwargs.get("timeseries") is not None:
             self.update(**kwargs, dataset_id=id)
 
+        return id
+
     def _get_scaling(self, key):
         if isinstance(self._scaling, str):
             return self._scaling.lower()
@@ -1013,7 +1015,7 @@ def __init__(
             )
 
     def add_dataset(
-        self, id=None, *, plot_kwargs=None, poisson=False, poisson_kwargs=None, **kwargs
+        self, id=AUTO, *, plot_kwargs=None, poisson=False, poisson_kwargs=None, **kwargs
     ):
         """Create artists for a new dataset to the plot and optionally update their values
 
@@ -1063,6 +1065,8 @@ def create_artists(i, j, k, ax, p):
         if kwargs.get("particles") is not None:
             self.update(**kwargs, dataset_id=id)
 
+        return id
+
     @property
     def bin_time(self):
         return self._bin_time or self.dt_max / self._bin_count
@@ -1239,7 +1243,7 @@ def __init__(
             )
 
     def add_dataset(
-        self, id=None, *, plot_kwargs=None, poisson=True, poisson_kwargs=None, **kwargs
+        self, id=AUTO, *, plot_kwargs=None, poisson=True, poisson_kwargs=None, **kwargs
     ):
         """Create artists for a new dataset to the plot and optionally update their values
 
@@ -1282,6 +1286,8 @@ def create_artists(i, j, k, ax, p):
         if kwargs.get("particles") is not None or kwargs.get("timeseries") is not None:
             self.update(**kwargs, dataset_id=id)
 
+        return id
+
     def update(
         self, particles=None, mask=None, *, autoscale=None, timeseries=None, dataset_id=None
     ):
@@ -1473,7 +1479,7 @@ def __init__(
 
     def add_dataset(
         self,
-        id=None,
+        id=AUTO,
         *,
         plot_kwargs=None,
         std=True,
@@ -1529,6 +1535,8 @@ def create_artists(i, j, k, ax, p):
         if kwargs.get("particles") or kwargs.get("timeseries") is not None:
             self.update(**kwargs, dataset_id=id)
 
+        return id
+
     def update(
         self,
         particles=None,

xplt/util.py

@@ -50,6 +50,7 @@ def PUBLIC_SECTION_END():
 
 
 VOID = object()
+AUTO = object()
 
 
 c0 = 299792458