diffract-core 0.2.1__py3-none-any.whl

diffract/viz/plots/base/line.py

@@ -0,0 +1,197 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import plotly.graph_objects as go
+
+from diffract.viz.data import Entry, FieldRef
+from diffract.viz.styling import (
+    CategoricalPropertyResolver,
+    ColorResolver,
+    ColorSource,
+    DashSource,
+    DefaultColorPalette,
+    DefaultDashPalette,
+    NumericPropertyResolver,
+    ResolvedColor,
+    Theme,
+)
+
+from .coloraxis import SupportsColoraxis
+
+
+@dataclass(kw_only=True)
+class SupportsLine(SupportsColoraxis("line")):
+    """Configurator mixin for line properties.
+
+    Trace data keys used (resolved in _build_traces_data):
+        - line_width: resolved width values
+        - line_color: resolved color (single color or array)
+        - line_color_values: numeric values for coloraxis (if applicable)
+        - line_dash: resolved dash pattern
+    """
+
+    line_width: FieldRef | float | None = 2
+    line_width_range: tuple[float, float] | None = None
+    line_color: ColorSource = None
+    line_dash: DashSource = None
+    line_shape: str | None = None
+    line_smoothing: float | None = None
+
+    def configure(self, fig: go.Figure) -> None:
+        """Apply resolved line styling to matching traces in the figure.
+
+        Args:
+            fig: The Plotly figure whose line traces are updated in place.
+        """
+        super().configure(fig)
+
+        if self._traces_data is None:
+            return
+
+        coloraxis = self.resolve_coloraxis(fig)
+
+        for trace_id, trace_data in self._traces_data.items():
+            kwargs = _build_line_kwargs(self, trace_data, coloraxis)
+
+            if kwargs:
+                fig.update_traces(
+                    line=kwargs,
+                    selector=lambda t, tid=trace_id: t.meta
+                    and t.meta.get("trace_id") == tid,
+                )
+
+    def _resolve_line_width(
+        self,
+        entries: dict[str, Entry] | None,
+        theme: Theme | None = None,
+    ) -> float | list[float] | None:
+        match self.line_width:
+            case None:
+                return None
+            case int() | float():
+                return float(self.line_width)
+            case FieldRef():
+                resolver = NumericPropertyResolver(self.line_width_range)
+                return resolver.resolve(self.line_width, entries)
+
+    def _add_line_width_to_trace(
+        self,
+        trace_data: dict[str, Any],
+        resolved_line_width: float | list[float] | None,
+    ) -> None:
+        """Add resolved line width to trace data."""
+        if resolved_line_width is None:
+            return
+        trace_data["line_width"] = resolved_line_width
+
+    def _resolve_line_dash(
+        self,
+        entries: dict[str, Entry] | None,
+        theme: Theme | None = None,
+    ) -> str | list[str] | None:
+        match self.line_dash:
+            case None:
+                return None
+            case str():
+                return self.line_dash
+            case FieldRef():
+                dash_palette = theme.palettes.dashes if theme else DefaultDashPalette()
+                resolver = CategoricalPropertyResolver(list(dash_palette.dashes))
+                return resolver.resolve(self.line_dash, entries)
+
+    def _add_line_dash_to_trace(
+        self,
+        trace_data: dict[str, Any],
+        resolved_line_dash: str | list[str] | None,
+    ) -> None:
+        """Add resolved line dash to trace data."""
+        if resolved_line_dash is None:
+            return
+        trace_data["line_dash"] = resolved_line_dash
+
+    def _resolve_line_color(
+        self,
+        entries: dict[str, Entry] | None,
+        theme: Theme | None = None,
+    ) -> ResolvedColor:
+        color_palette = theme.palettes.color if theme else DefaultColorPalette()
+        resolver = ColorResolver(color_palette)
+        return resolver.resolve(self.line_color, entries)
+
+    def _add_line_color_to_trace(
+        self,
+        trace_data: dict[str, Any],
+        resolved_color: ResolvedColor,
+    ) -> None:
+        """Add resolved line color to trace data."""
+        if resolved_color.values is not None:
+            trace_data["line_color_values"] = resolved_color.values
+        elif resolved_color.color is not None:
+            trace_data["line_color"] = resolved_color.color
+
+
+def _build_line_kwargs(
+    line: SupportsLine,
+    trace_data: dict[str, Any],
+    coloraxis: str | None = None,
+) -> dict[str, Any]:
+    """Build line kwargs from pre-resolved trace data.
+
+    Expected trace_data keys:
+        - line_width: resolved width (number or array)
+        - line_dash: resolved dash pattern (string or array)
+        - line_color: resolved color (string, rgb, or array)
+        - line_color_values: numeric values for coloraxis mapping
+    """
+    kwargs: dict[str, Any] = {}
+
+    # Width
+    width = trace_data.get("line_width")
+    if width is not None:
+        kwargs["width"] = width
+
+    # Dash
+    dash = trace_data.get("line_dash")
+    if dash is not None:
+        kwargs["dash"] = dash
+
+    # Shape (static, from config)
+    if line.line_shape is not None:
+        kwargs["shape"] = line.line_shape
+
+    # Smoothing (static, from config)
+    if line.line_smoothing is not None:
+        kwargs["smoothing"] = line.line_smoothing
+
+    # Color
+    color_kwargs = _build_line_color_kwargs(trace_data, coloraxis)
+    kwargs.update(color_kwargs)
+
+    return kwargs
+
+
+def _build_line_color_kwargs(
+    trace_data: dict[str, Any], coloraxis: str | None = None
+) -> dict[str, Any]:
+    """Build line color kwargs from pre-resolved trace data.
+
+    Expected trace_data keys:
+        - line_color: resolved color (string or array of colors)
+        - line_color_values: numeric values for coloraxis mapping
+    """
+    kwargs: dict[str, Any] = {}
+
+    color = trace_data.get("line_color")
+    color_values = trace_data.get("line_color_values")
+
+    if color_values is not None:
+        kwargs["color"] = color_values
+        if coloraxis is not None:
+            kwargs["coloraxis"] = coloraxis
+
+    elif color is not None:
+        kwargs["color"] = color
+
+    return kwargs

diffract/viz/plots/base/marker.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import plotly.graph_objects as go
+
+from diffract.viz.data import Entry, FieldRef
+from diffract.viz.styling import (
+    CategoricalPropertyResolver,
+    ColorResolver,
+    ColorSource,
+    DefaultColorPalette,
+    DefaultSymbolPalette,
+    NumericPropertyResolver,
+    ResolvedColor,
+    SymbolSource,
+    Theme,
+)
+
+from .coloraxis import SupportsColoraxis
+
+
+@dataclass(kw_only=True)
+class SupportsMarker(SupportsColoraxis("marker")):
+    """Configurator mixin for marker properties."""
+
+    marker_size: FieldRef | float | None = 6
+    marker_size_range: tuple[float, float] | None = None
+    marker_opacity: FieldRef | float | None = 0.7
+    marker_opacity_range: tuple[float, float] | None = None
+    marker_color: ColorSource = None
+    marker_symbol: SymbolSource = None
+
+    def configure(self, fig: go.Figure) -> None:
+        """Apply resolved marker styling to matching traces in the figure.
+
+        Args:
+            fig: The Plotly figure whose marker traces are updated in place.
+        """
+        super().configure(fig)
+
+        if self._traces_data is None:
+            return
+
+        coloraxis = self.resolve_coloraxis(fig)
+
+        for trace_id, trace_data in self._traces_data.items():
+            base_kwargs, per_point_kwargs = _build_marker_kwargs(
+                trace_data,
+                coloraxis,
+            )
+
+            if base_kwargs:
+                fig.update_traces(
+                    marker=base_kwargs,
+                    selector=lambda t, tid=trace_id: (
+                        t.meta and t.meta.get("trace_id") == tid
+                    ),
+                )
+
+            if per_point_kwargs:
+                fig.update_traces(
+                    marker=per_point_kwargs,
+                    selector=lambda t, tid=trace_id: (
+                        t.meta
+                        and t.meta.get("trace_id") == tid
+                        and _supports_per_point_marker(t)
+                    ),
+                )
+
+    def _resolve_marker_size(
+        self,
+        entries: dict[str, Entry] | None,
+        theme: Theme | None = None,
+    ) -> float | list[float] | None:
+        match self.marker_size:
+            case None:
+                return None
+            case int() | float():
+                return float(self.marker_size)
+            case FieldRef():
+                resolver = NumericPropertyResolver(self.marker_size_range)
+                return resolver.resolve(self.marker_size, entries)
+
+    def _add_marker_size_to_trace(
+        self,
+        trace_data: dict[str, Any],
+        resolved_size: float | list[float] | None,
+    ) -> None:
+        """Add resolved marker size to trace data."""
+        if resolved_size is None:
+            return
+        trace_data["marker_size"] = resolved_size
+
+    def _resolve_marker_opacity(
+        self,
+        entries: dict[str, Entry] | None,
+        theme: Theme | None = None,
+    ) -> float | list[float] | None:
+        match self.marker_opacity:
+            case None:
+                return None
+            case int() | float():
+                return float(self.marker_opacity)
+            case FieldRef():
+                resolver = NumericPropertyResolver(self.marker_opacity_range)
+                return resolver.resolve(self.marker_opacity, entries)
+
+    def _add_marker_opacity_to_trace(
+        self,
+        trace_data: dict[str, Any],
+        resolved_opacity: float | list[float] | None,
+    ) -> None:
+        """Add resolved marker opacity to trace data."""
+        if resolved_opacity is None:
+            return
+        trace_data["marker_opacity"] = resolved_opacity
+
+    def _resolve_marker_symbol(
+        self,
+        entries: dict[str, Entry] | None,
+        theme: Theme | None = None,
+    ) -> str | list[str] | None:
+        match self.marker_symbol:
+            case None:
+                return None
+            case str():
+                return self.marker_symbol
+            case FieldRef():
+                symbol_palette = (
+                    theme.palettes.symbols if theme else DefaultSymbolPalette()
+                )
+                resolver = CategoricalPropertyResolver(symbol_palette.symbols)
+                return resolver.resolve(self.marker_symbol, entries)
+
+    def _add_marker_symbol_to_trace(
+        self,
+        trace_data: dict[str, Any],
+        resolved_symbol: str | list[str] | None,
+    ) -> None:
+        """Add resolved marker symbol to trace data."""
+        if resolved_symbol is None:
+            return
+        trace_data["marker_symbol"] = resolved_symbol
+
+    def _resolve_marker_color(
+        self,
+        entries: dict[str, Entry] | None,
+        theme: Theme | None = None,
+    ) -> ResolvedColor:
+        color_palette = theme.palettes.color if theme else DefaultColorPalette()
+        resolver = ColorResolver(color_palette)
+        return resolver.resolve(self.marker_color, entries)
+
+    def _add_marker_color_to_trace(
+        self,
+        trace_data: dict[str, Any],
+        resolved_color: ResolvedColor,
+    ) -> None:
+        """Add resolved marker color to trace data."""
+        if resolved_color.values is not None:
+            trace_data["marker_color_values"] = resolved_color.values
+        elif resolved_color.color is not None:
+            trace_data["marker_color"] = resolved_color.color
+
+
+def _build_marker_kwargs(
+    trace_data: dict[str, Any],
+    coloraxis: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Build marker kwargs, split into universal and per-point.
+
+    Returns:
+        Tuple of ``(base_kwargs, per_point_kwargs)``.
+
+        *base_kwargs* contains properties supported by all trace types
+        (scalar size, scalar opacity, symbol, scalar/single color, line).
+
+        *per_point_kwargs* contains list-valued properties and the
+        ``coloraxis`` reference, which are only supported by
+        scatter-type traces (not ``go.Box``, ``go.Violin``, etc.).
+    """
+    base_kwargs: dict[str, Any] = {}
+    per_point_kwargs: dict[str, Any] = {}
+
+    # Size — scalar goes to base, list goes to per-point
+    size = trace_data.get("marker_size")
+    if size is not None:
+        if isinstance(size, list):
+            per_point_kwargs["size"] = size
+        else:
+            base_kwargs["size"] = size
+
+    # Opacity — scalar goes to base, list goes to per-point
+    opacity = trace_data.get("marker_opacity")
+    if opacity is not None:
+        if isinstance(opacity, list):
+            per_point_kwargs["opacity"] = opacity
+        else:
+            base_kwargs["opacity"] = opacity
+
+    # Symbol
+    symbol = trace_data.get("marker_symbol")
+    if symbol is not None:
+        base_kwargs["symbol"] = symbol
+
+    # Color (split into base color value and coloraxis reference)
+    color_base, coloraxis_kwargs = _build_marker_color_kwargs(trace_data, coloraxis)
+    base_kwargs.update(color_base)
+    per_point_kwargs.update(coloraxis_kwargs)
+
+    return base_kwargs, per_point_kwargs
+
+
+def _build_marker_color_kwargs(
+    trace_data: dict[str, Any],
+    coloraxis: str | None = None,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Build marker color kwargs, split into base and per-point.
+
+    Returns:
+        Tuple of ``(base_kwargs, per_point_kwargs)``.
+
+        Numeric ``color_values`` (continuous colorscale mapping) and
+        list-valued categorical colors are routed to *per_point_kwargs*
+        together with the ``coloraxis`` reference, since these are only
+        supported by scatter-type traces.
+
+        A single color string is placed in *base_kwargs* (safe for all
+        trace types).
+    """
+    base_kwargs: dict[str, Any] = {}
+    per_point_kwargs: dict[str, Any] = {}
+
+    color = trace_data.get("marker_color")
+    color_values = trace_data.get("marker_color_values")
+
+    if color_values is not None:
+        per_point_kwargs["color"] = color_values
+        if coloraxis is not None:
+            per_point_kwargs["coloraxis"] = coloraxis
+    elif color is not None:
+        if isinstance(color, list):
+            per_point_kwargs["color"] = color
+        else:
+            base_kwargs["color"] = color
+
+    return base_kwargs, per_point_kwargs
+
+
+# --- Trace-type support ---
+
+_PER_POINT_MARKER_TRACE_TYPES = frozenset(
+    {
+        "scatter",
+        "scattergl",
+        "scatter3d",
+        "scattergeo",
+        "scattermapbox",
+        "scatterpolar",
+        "scatterpolargl",
+        "scatterternary",
+        "splom",
+        "barpolar",
+    }
+)
+
+
+def _supports_per_point_marker(trace: Any) -> bool:
+    """Check if a Plotly trace type supports per-point marker properties.
+
+    Scatter-type traces accept list-valued ``marker.size``,
+    ``marker.opacity``, ``marker.color``, and the ``marker.coloraxis``
+    reference.  Aggregation traces like ``go.Box`` and ``go.Violin``
+    only accept scalar values for these properties.
+    """
+    return getattr(trace, "type", None) in _PER_POINT_MARKER_TRACE_TYPES

diffract/viz/plots/base/overlay.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+import plotly.graph_objects as go
+
+
+class Overlay(ABC):
+    """A mixin that can add overlay traces to a Plotly figure."""
+
+    @abstractmethod
+    def add_overlay_traces(self, fig: go.Figure) -> None:
+        """Add overlay traces to the given figure."""
+        raise NotImplementedError

diffract/viz/plots/base/plot.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field, fields
+from typing import TYPE_CHECKING, Any
+
+import plotly.graph_objects as go
+
+from diffract.session import Session
+from diffract.viz.data import DataProvider, Entry, FieldRef
+from diffract.viz.plots.base.overlay import Overlay
+from diffract.viz.styling import apply_theme
+
+from .configurator import Configurator
+
+if TYPE_CHECKING:
+    from diffract.viz.styling import Theme
+
+
+@dataclass(kw_only=True)
+class Plot(ABC):
+    """A configurable plot that can render itself given a Session."""
+
+    title: str | None = None
+    value_filter: dict[str, tuple[str, Any]] | None = None
+
+    _traces_data: dict[str, dict[str, Any]] | None = field(
+        default=None, repr=False, compare=False
+    )
+    _theme: Theme | None = field(default=None, repr=False, compare=False)
+
+    def render(self, session: Session, theme: Theme | None = None) -> go.Figure:
+        """Render the plot using data from the session.
+
+        Args:
+            session: The diffract session containing data to plot.
+            theme: Optional theme for styling. If provided, palettes from theme
+                   are used for colors/symbols/dashes, and figure-level styling
+                   is applied after configurators.
+
+        Returns:
+            A Plotly Figure object.
+        """
+        self._theme = theme
+        data_provider = DataProvider(session)
+        entries = self._collect_entries(data_provider)
+        self._traces_data = self._build_traces_data(entries)
+        fig: go.Figure = self._build_figure()
+        self._add_overlay_traces_by_mro(fig)
+        self._configure_by_mro(fig)
+
+        if theme is not None:
+            apply_theme(fig, theme)
+
+        return fig
+
+    def _collect_entries(self, data_provider: DataProvider) -> dict[str, Entry]:
+        """Collect all entries needed for the plot."""
+        fields_to_fetch = self._collect_fields_to_fetch()
+        return data_provider.fetch(fields_to_fetch, value_filter=self.value_filter)
+
+    def _collect_fields_to_fetch(self) -> list[str]:
+        """Collect all field names needed for the plot.
+
+        Walks the MRO and inspects dataclass fields, collecting the ``field``
+        attribute from every value that is a :class:`FieldRef`.
+        """
+        result: list[str] = []
+        seen: set[str] = set()
+
+        for cls in type(self).mro():
+            if not hasattr(cls, "__dataclass_fields__"):
+                continue
+            for f in fields(cls):
+                value = getattr(self, f.name, None)
+                if isinstance(value, FieldRef) and value.field not in seen:
+                    seen.add(value.field)
+                    result.append(value.field)
+
+        return result
+
+    @abstractmethod
+    def _build_traces_data(
+        self, entries: dict[str, Entry]
+    ) -> dict[str, dict[str, Any]]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def _build_figure(self) -> go.Figure:
+        raise NotImplementedError
+
+    def _add_overlay_traces_by_mro(self, fig: go.Figure) -> None:
+        """Hook for mixins to add overlay traces (jitter, annotations, etc.).
+
+        Override in mixins to add additional traces after the main figure is built.
+        Always call super()._add_overlay_traces(fig) to ensure proper MRO chaining.
+        """
+        for cls in type(self).mro():
+            if cls is Overlay:
+                continue
+            if issubclass(cls, Overlay):
+                cls.add_overlay_traces(self, fig)
+
+    def _configure_by_mro(self, fig: go.Figure) -> None:
+        """Apply configurator mixins in MRO order."""
+        for cls in type(self).mro():
+            if cls is Configurator:
+                continue
+            if issubclass(cls, Configurator):
+                cls.configure(self, fig)

diffract/viz/plots/base/update.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from diffract.viz.renderer import Plot
+from diffract.viz.styling import apply_theme
+
+if TYPE_CHECKING:  # pragma: no cover
+    import plotly.graph_objects as go  # type: ignore[import-not-found]
+
+    from diffract.session import Session
+    from diffract.viz.styling import Theme
+
+
+@dataclass(kw_only=True)
+class UpdateFigure:
+    """Wrap another plot and apply Plotly update calls."""
+
+    plot: Plot
+
+    # Back-compat: older configs used `config:` meaning `Figure.update(config)`.
+    config: dict[str, Any] | None = None
+    update: dict[str, Any] | None = None
+    layout: dict[str, Any] | None = None
+    traces: dict[str, Any] | None = None
+    xaxes: dict[str, Any] | None = None
+    yaxes: dict[str, Any] | None = None
+
+    def render(self, session: Session, theme: Theme | None = None) -> go.Figure:
+        """Render the wrapped plot and apply configuration overrides."""
+        fig = self.plot.render(session, theme)
+
+        if self.config is not None:
+            fig.update(self.config)
+        if self.update is not None:
+            fig.update(self.update)
+        if self.layout is not None:
+            fig.update_layout(**self.layout)
+        if self.traces is not None:
+            fig.update_traces(**self.traces)
+        if self.xaxes is not None:
+            fig.update_xaxes(**self.xaxes)
+        if self.yaxes is not None:
+            fig.update_yaxes(**self.yaxes)
+
+        if theme is not None:
+            apply_theme(fig, theme)
+
+        return fig