qten_plots.plottables

Module reference for qten_plots.plottables.

plottables

Plot-ready objects used by QTen plotting backends.

This module defines lightweight containers that carry both geometry data and backend-independent display preferences. Backend implementations can then read the same object and translate its styling fields into Matplotlib or Plotly arguments without changing the underlying QTen geometry objects.

PointCloud dataclass

PointCloud(
    offsets: FrozenSet[Offset] = frozenset(),
    name: str | None = None,
    color: str | None = None,
    marker: str | None = None,
    opacity: float | None = None,
    size: float | None = None,
    border_color: str | None = None,
    border_width: float | None = None,
)

Bases: Plottable

Plottable collection of spatial offsets with optional display styling.

A PointCloud groups Offset objects that should be rendered together as one scatter trace. The object stores backend-independent style hints; each plotting backend maps those hints onto its own marker, color, opacity, size, and border options.

Marker aliases

The marker field accepts the common aliases o, circle, s, square, d, D, diamond, +, plus, cross, and x. These are normalized to the marker vocabulary supported by each backend.

Attributes:

Name	Type	Description
offsets	FrozenSet[Offset]	Spatial offsets to render as a single point cloud. The set is normalized to a frozenset during initialization.
name	str | None	Optional trace or legend label.
color	str | None	Optional backend color value used for all points in the cloud.
marker	str | None	Optional marker shape alias.
opacity	float | None	Optional marker opacity in the inclusive range [0, 1].
size	float | None	Optional positive marker size.
border_color	str | None	Optional marker border color.
border_width	float | None	Optional non-negative marker border width.

Raises:

Type	Description
TypeError	If any entry in offsets is not an Offset.
ValueError	If marker, opacity, size, or border_width is outside the supported range.

offsets class-attribute instance-attribute

offsets: FrozenSet[Offset] = field(
    default_factory=frozenset
)

Spatial offsets to render as a single point cloud. The set is normalized to a frozenset during initialization so the plottable is immutable and hashable.

name class-attribute instance-attribute

name: str | None = None

Optional trace or legend label shown by plotting backends.

color class-attribute instance-attribute

color: str | None = None

Optional backend color value applied uniformly to all points in the cloud.

marker class-attribute instance-attribute

marker: str | None = None

Optional marker shape alias, normalized to the vocabulary supported by the selected plotting backend.

opacity class-attribute instance-attribute

opacity: float | None = None

Optional marker opacity in the inclusive range [0, 1], forwarded as a backend-independent styling hint.

size class-attribute instance-attribute

size: float | None = None

Optional positive marker size shared by every rendered point.

border_color class-attribute instance-attribute

border_color: str | None = None

Optional marker border color used by backends that support outlines.

border_width class-attribute instance-attribute

border_width: float | None = None

Optional non-negative marker border width used by backends that support marker outlines.

__post_init__

__post_init__()

Source code in ext/plots/src/qten_plots/plottables.py

def __post_init__(self):
    from qten.geometries.spatials import Offset

    normalized = frozenset(self.offsets)
    if not all(isinstance(offset, Offset) for offset in normalized):
        raise TypeError("PointCloud offsets must all be Offset instances.")
    if self.opacity is not None and not (0.0 <= self.opacity <= 1.0):
        raise ValueError(
            f"PointCloud opacity must lie in [0, 1], got {self.opacity}."
        )
    normalize_pointcloud_marker(self.marker)
    if self.size is not None and self.size <= 0:
        raise ValueError(f"PointCloud size must be positive, got {self.size}.")
    if self.border_width is not None and self.border_width < 0:
        raise ValueError(
            f"PointCloud border_width must be non-negative, got {self.border_width}."
        )
    object.__setattr__(self, "offsets", normalized)

of classmethod

of(
    offsets: Iterable[Offset],
    name: str | None = None,
    color: str | None = None,
    marker: str | None = None,
    opacity: float | None = None,
    size: float | None = None,
    border_color: str | None = None,
    border_width: float | None = None,
) -> PointCloud

Construct a PointCloud from any iterable of offsets.

This helper is convenient when the offsets are produced by an iterator or generator. It freezes the iterable into the immutable set stored by the dataclass.

Parameters:

Name	Type	Description	Default
offsets	Iterable[Offset]	Spatial offsets to render as one point cloud.	required
name	str | None	Optional trace or legend label.	None
color	str | None	Optional backend color value used for all points in the cloud.	None
marker	str | None	Optional marker shape alias.	None
opacity	float | None	Optional marker opacity in the inclusive range [0, 1].	None
size	float | None	Optional positive marker size.	None
border_color	str | None	Optional marker border color.	None
border_width	float | None	Optional non-negative marker border width.	None

Returns:

Type	Description
PointCloud	New immutable point cloud containing the provided offsets.

Raises:

Type	Description
TypeError	If any entry in offsets is not an Offset.
ValueError	If marker, opacity, size, or border_width is outside the supported range.

Source code in ext/plots/src/qten_plots/plottables.py

@classmethod
def of(
    cls,
    offsets: Iterable[Offset],
    name: str | None = None,
    color: str | None = None,
    marker: str | None = None,
    opacity: float | None = None,
    size: float | None = None,
    border_color: str | None = None,
    border_width: float | None = None,
) -> "PointCloud":
    """
    Construct a [`PointCloud`][qten_plots.plottables.PointCloud] from any iterable of offsets.

    This helper is convenient when the offsets are produced by an iterator
    or generator. It freezes the iterable into the immutable set stored by
    the dataclass.

    Parameters
    ----------
    offsets : Iterable[Offset]
        Spatial offsets to render as one point cloud.
    name : str | None
        Optional trace or legend label.
    color : str | None
        Optional backend color value used for all points in the cloud.
    marker : str | None
        Optional marker shape alias.
    opacity : float | None
        Optional marker opacity in the inclusive range `[0, 1]`.
    size : float | None
        Optional positive marker size.
    border_color : str | None
        Optional marker border color.
    border_width : float | None
        Optional non-negative marker border width.

    Returns
    -------
    PointCloud
        New immutable point cloud containing the provided offsets.

    Raises
    ------
    TypeError
        If any entry in `offsets` is not an `Offset`.
    ValueError
        If `marker`, `opacity`, `size`, or `border_width` is outside the
        supported range.
    """
    return cls(
        offsets=frozenset(offsets),
        name=name,
        color=color,
        marker=marker,
        opacity=opacity,
        size=size,
        border_color=border_color,
        border_width=border_width,
    )

register_plot_method classmethod

register_plot_method(name: str, backend: str = 'plotly')

Register a backend plotting function for this plottable class.

The returned decorator stores the function in the global plotting registry. Registered functions receive the object being plotted as their first argument, followed by any extra positional and keyword arguments supplied to plot().

Parameters:

Name	Type	Description	Default
name	str	User-facing plot method name, such as scatter, structure, or heatmap.	required
backend	str	Backend name that selects the implementation. The qten-plots extension currently uses plotly and matplotlib.	'plotly'

Returns:

Type	Description
Callable	Decorator that registers the provided plotting function and returns it unchanged.

Source code in src/qten/plottings/_plottings.py

@classmethod
def register_plot_method(cls, name: str, backend: str = "plotly"):
    """
    Register a backend plotting function for this plottable class.

    The returned decorator stores the function in the global plotting
    registry. Registered functions receive the object being plotted as their
    first argument, followed by any extra positional and keyword arguments
    supplied to [`plot()`][qten.plottings.Plottable.plot].

    Parameters
    ----------
    name : str
        User-facing plot method name, such as `scatter`, `structure`, or
        `heatmap`.
    backend : str
        Backend name that selects the implementation. The `qten-plots`
        extension currently uses `plotly` and `matplotlib`.

    Returns
    -------
    Callable
        Decorator that registers the provided plotting function and returns
        it unchanged.
    """

    def decorator(func: Callable):
        # We register against 'cls' - the class this method was called on.
        Plottable._registry[(cls, name, backend)] = func
        return func

    return decorator

plot

plot(method: str, backend: str = 'plotly', *args, **kwargs)

Dispatch a named plot method to a registered backend implementation.

The dispatcher first loads plotting entry points, then searches the instance type and its base classes for a matching (type, method, backend) registration. Additional arguments are forwarded unchanged to the selected backend function.

Parameters:

Name	Type	Description	Default
method	str	Plot method name registered for this object's type.	required
backend	str	Backend implementation to use. The qten-plots extension currently registers plotly and matplotlib.	'plotly'
args		Positional arguments forwarded to the registered plotting function.	()
kwargs		Keyword arguments forwarded to the registered plotting function.	{}

Returns:

Type	Description
object	Backend-specific figure object returned by the registered plotting function, such as a Plotly or Matplotlib figure.

Raises:

Type	Description
ValueError	If no plotting function is registered for the requested method and backend on this object.

See Also

qten_plots.plottables.PointCloud Public plottable helper object provided by the plotting extension.

Source code in src/qten/plottings/_plottings.py

def plot(self, method: str, backend: str = "plotly", *args, **kwargs):
    """
    Dispatch a named plot method to a registered backend implementation.

    The dispatcher first loads plotting entry points, then searches the
    instance type and its base classes for a matching `(type, method,
    backend)` registration. Additional arguments are forwarded unchanged to
    the selected backend function.

    Parameters
    ----------
    method : str
        Plot method name registered for this object's type.
    backend : str
        Backend implementation to use. The `qten-plots` extension currently
        registers `plotly` and `matplotlib`.
    args
        Positional arguments forwarded to the registered plotting function.
    kwargs
        Keyword arguments forwarded to the registered plotting function.

    Returns
    -------
    object
        Backend-specific figure object returned by the registered plotting
        function, such as a Plotly or Matplotlib figure.

    Raises
    ------
    ValueError
        If no plotting function is registered for the requested method and
        backend on this object.

    See Also
    --------
    qten_plots.plottables.PointCloud
        Public plottable helper object provided by the plotting extension.
    """
    Plottable._ensure_backends_loaded()

    # Iterate over the MRO (Method Resolution Order) of the instance
    for class_in_hierarchy in type(self).__mro__:
        key = (class_in_hierarchy, method, backend)

        # Check the central registry
        if key in Plottable._registry:
            plot_func = Plottable._registry[key]
            return plot_func(self, *args, **kwargs)

    # If we reach here, no method was found. Provide a helpful error.
    self._raise_method_not_found(method, backend)