Add overlay unit validation at both intra-layer and cross-layer sites

HoloViews silently renders overlaid elements against a single shared axis
using the first element's units, producing incorrect plots when sources
have mismatched units. This adds validation at two sites:

Site 1 (Plotter.compute): validates that all DataArrays in an overlay
share the same dimension names, coordinate units, and value units.
Errors are caught by the existing try/except and displayed as text.

Site 2 (_get_session_composed_plot): validates cross-layer unit
compatibility before composing DynamicMaps. Each Plotter stores an
OverlayUnitKey after compute(), which captures kdim and vdim unit
metadata. ROI readback/request plotters provide kdim units from their
coordinate metadata but skip vdim validation. Static plotters are
naturally exempt (no Plotter instance).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SimonHeybrock

src/ess/livedata/dashboard/plots.py

@@ -214,6 +214,121 @@ def _compute_time_info(data: dict[str, sc.DataArray]) -> str | None:
         return f'{end_str} (Lag: {lag_s:.1f}s)'
 
 
+@dataclass(frozen=True)
+class OverlayUnitKey:
+    """Unit signature for cross-layer overlay validation.
+
+    Captures the units of all plotting dimensions and (optionally) the value
+    dimension.  Two keys are compatible when every shared kdim label has the
+    same unit string and, if both keys carry a vdim unit, those match too.
+    """
+
+    kdim_units: tuple[tuple[str, str | None], ...] = ()
+    vdim_unit: str | None = None
+
+    @classmethod
+    def from_data_array(
+        cls,
+        da: sc.DataArray,
+        *,
+        include_vdim: bool = True,
+    ) -> OverlayUnitKey:
+        """Build a key from a scipp DataArray using its dimension coordinates."""
+        kdim_units = tuple(
+            sorted(
+                (dim, _unit_str(da.coords[dim].unit))
+                for dim in da.dims
+                if dim in da.coords
+            )
+        )
+        vdim_unit = _unit_str(da.unit) if include_vdim else None
+        return cls(kdim_units=kdim_units, vdim_unit=vdim_unit)
+
+
+def _unit_str(unit: sc.Unit | None) -> str | None:
+    """Convert a scipp unit to its string representation, or None."""
+    return str(unit) if unit is not None else None
+
+
+def _validate_overlay_units(data: dict[ResultKey, sc.DataArray]) -> None:
+    """Validate that all DataArrays in an overlay share compatible units.
+
+    Raises
+    ------
+    ValueError
+        If dimension names, coordinate units, or value units do not match.
+    """
+    if len(data) < 2:
+        return
+
+    items = iter(data.items())
+    ref_key, ref = next(items)
+    ref_source = ref_key.job_id.source_name
+
+    for key, da in items:
+        source = key.job_id.source_name
+        if ref.dims != da.dims:
+            raise ValueError(
+                f"Cannot overlay '{ref_source}' and '{source}': "
+                f"dimension mismatch ({ref.dims} vs {da.dims})"
+            )
+        for dim in ref.dims:
+            if dim in ref.coords and dim in da.coords:
+                u_ref = ref.coords[dim].unit
+                u_da = da.coords[dim].unit
+                if u_ref != u_da:
+                    raise ValueError(
+                        f"Cannot overlay '{ref_source}' and '{source}': "
+                        f"unit mismatch for coordinate '{dim}' "
+                        f"({u_ref} vs {u_da})"
+                    )
+        if ref.unit != da.unit:
+            raise ValueError(
+                f"Cannot overlay '{ref_source}' and '{source}': "
+                f"value unit mismatch ({ref.unit} vs {da.unit})"
+            )
+
+
+def validate_cross_layer_units(
+    keys: list[tuple[str, OverlayUnitKey]],
+) -> str | None:
+    """Check overlay unit keys from multiple layers for compatibility.
+
+    Parameters
+    ----------
+    keys:
+        Pairs of (layer label, unit key) for each data-carrying layer.
+
+    Returns
+    -------
+    :
+        An error message if units are incompatible, or None if compatible.
+    """
+    if len(keys) < 2:
+        return None
+
+    ref_label, ref_key = keys[0]
+    ref_kdims = dict(ref_key.kdim_units)
+
+    for label, key in keys[1:]:
+        other_kdims = dict(key.kdim_units)
+        for dim_label, ref_unit in ref_kdims.items():
+            if dim_label in other_kdims and ref_unit != other_kdims[dim_label]:
+                return (
+                    f"Cannot overlay layers '{ref_label}' and '{label}': "
+                    f"unit mismatch for coordinate '{dim_label}' "
+                    f"({ref_unit} vs {other_kdims[dim_label]})"
+                )
+        if ref_key.vdim_unit is not None and key.vdim_unit is not None:
+            if ref_key.vdim_unit != key.vdim_unit:
+                return (
+                    f"Cannot overlay layers '{ref_label}' and '{label}': "
+                    f"value unit mismatch "
+                    f"({ref_key.vdim_unit} vs {key.vdim_unit})"
+                )
+    return None
+
+
 class Plotter:
     """
     Base class for plots that support autoscaling.
@@ -245,6 +360,7 @@ def __init__(
         """
         self._normalize_to_rate = normalize_to_rate
         self._cached_state: Any | None = None
+        self._overlay_unit_key: OverlayUnitKey | None = None
         self._presenters: weakref.WeakSet[PresenterBase] = weakref.WeakSet()
         self.autoscaler_kwargs = kwargs
         self.autoscalers: dict[ResultKey, Autoscaler] = {}
@@ -257,6 +373,25 @@ def __init__(
         # with responsive mode in Panel containers (upstream bug).
         self._sizing_opts: dict[str, Any] = {'responsive': True}
 
+    @property
+    def overlay_unit_key(self) -> OverlayUnitKey | None:
+        """Unit signature from the last compute(), for cross-layer validation."""
+        return self._overlay_unit_key
+
+    def _extract_overlay_unit_key(
+        self, data: dict[ResultKey, sc.DataArray]
+    ) -> OverlayUnitKey | None:
+        """Extract an overlay unit key from input data.
+
+        Default implementation uses dimension coordinates and value unit from the
+        first DataArray. Subclasses with non-standard coordinate structures (e.g.,
+        ROI plotters) should override this method.
+        """
+        if not data:
+            return None
+        da = next(iter(data.values()))
+        return OverlayUnitKey.from_data_array(da)
+
     @staticmethod
     def _make_tick_opts(tick_params: TickParams | None) -> dict[str, Any]:
         """
@@ -430,9 +565,13 @@ def compute(
         if self._normalize_to_rate:
             data = {key: _normalize_to_rate(da) for key, da in data.items()}
 
+        self._overlay_unit_key = self._extract_overlay_unit_key(data)
+
         resolver = title_resolver or TitleResolver()
         plots: list[hv.Element] = []
         try:
+            if self.layout_params.combine_mode == 'overlay':
+                _validate_overlay_units(data)
             for data_key, da in data.items():
                 label = resolver.get_legend_label(
                     data_key.job_id.source_name, data_key.output_name

src/ess/livedata/dashboard/roi_readback_plots.py

@@ -21,7 +21,23 @@
 )
 from ess.livedata.config.workflow_spec import ResultKey
 
-from .plots import Plotter
+from .plots import OverlayUnitKey, Plotter, _unit_str
+
+
+def _roi_overlay_unit_key(da: sc.DataArray) -> OverlayUnitKey:
+    """Build an overlay unit key from ROI coordinate metadata.
+
+    ROI DataArrays use named coords ('x', 'y') rather than dimension
+    coordinates, and have no meaningful value unit.
+    """
+    kdim_units = tuple(
+        sorted(
+            (name, _unit_str(da.coords[name].unit))
+            for name in ('x', 'y')
+            if name in da.coords
+        )
+    )
+    return OverlayUnitKey(kdim_units=kdim_units, vdim_unit=None)
 
 
 class ROIReadbackStyle(pydantic.BaseModel):
@@ -81,6 +97,14 @@ def from_params(cls, params: RectanglesReadbackParams) -> RectanglesReadbackPlot
         """Create plotter from params."""
         return cls(params)
 
+    def _extract_overlay_unit_key(
+        self, data: dict[ResultKey, sc.DataArray]
+    ) -> OverlayUnitKey | None:
+        if not data:
+            return None
+        da = next(iter(data.values()))
+        return _roi_overlay_unit_key(da)
+
     def plot(
         self, data: sc.DataArray, data_key: ResultKey, *, label: str = '', **kwargs
     ) -> hv.Rectangles:
@@ -187,6 +211,14 @@ def from_params(cls, params: PolygonsReadbackParams) -> PolygonsReadbackPlotter:
         """Create plotter from params."""
         return cls(params)
 
+    def _extract_overlay_unit_key(
+        self, data: dict[ResultKey, sc.DataArray]
+    ) -> OverlayUnitKey | None:
+        if not data:
+            return None
+        da = next(iter(data.values()))
+        return _roi_overlay_unit_key(da)
+
     def plot(
         self, data: sc.DataArray, data_key: ResultKey, *, label: str = '', **kwargs
     ) -> hv.Polygons:

src/ess/livedata/dashboard/roi_request_plots.py

@@ -48,7 +48,7 @@
     get_roi_mapper,
 )
 
-from .plots import Plotter, PresenterBase
+from .plots import OverlayUnitKey, Plotter, PresenterBase
 from .static_plots import Color, LineDash, RectanglesCoordinates
 
 if TYPE_CHECKING:
@@ -626,6 +626,16 @@ def compute(
             else None
         )
 
+        # Build overlay unit key from ROI coordinate units
+        kdim_units = tuple(
+            sorted(
+                (name, unit)
+                for name, unit in [('x', self._x_unit), ('y', self._y_unit)]
+                if unit is not None
+            )
+        )
+        self._overlay_unit_key = OverlayUnitKey(kdim_units=kdim_units, vdim_unit=None)
+
         # Forward data (presenter may use in future)
         self._set_cached_state(data)
         return data

src/ess/livedata/dashboard/widgets/plot_grid_tabs.py

@@ -35,6 +35,7 @@
     SubscriptionId,
 )
 from ..plot_params import PlotAspectType, StretchMode
+from ..plots import OverlayUnitKey, validate_cross_layer_units
 from ..save_filename import build_save_filename_from_cell, make_save_filename_hook
 from ..session_layer import SessionLayer
 from ..session_updater import SessionUpdater
@@ -940,6 +941,7 @@ def _get_session_composed_plot(
             Composed plot from session DMaps/elements, or None if none available.
         """
         plots = []
+        unit_keys: list[tuple[str, OverlayUnitKey]] = []
         has_layout = False
         for layer in cell.layers:
             layer_id = layer.layer_id
@@ -967,9 +969,22 @@ def _get_session_composed_plot(
                     has_layout = True
                 plots.append(dmap)
 
+                # Collect unit key for cross-layer validation
+                if state is not None and state.plotter is not None:
+                    key = state.plotter.overlay_unit_key
+                    if key is not None:
+                        unit_keys.append((layer.config.plot_name, key))
+
         if not plots:
             return None
 
+        # Validate cross-layer unit compatibility before composing
+        error = validate_cross_layer_units(unit_keys)
+        if error is not None:
+            return hv.Text(0.5, 0.5, f"Error: {error}").opts(
+                text_align='center', text_baseline='middle'
+            )
+
         result: hv.DynamicMap | hv.Element
         if len(plots) == 1:
             result = plots[0]