qten.plottings

Package reference for qten.plottings.

Registered Plot Methods

For the user-facing obj.plot(...) methods registered by the plotting extension, see Plot Methods.

plottings

Core plotting dispatch layer for QTen objects.

This package defines the lightweight plotting interface used by QTen and its plotting extensions. Backend-specific implementations may live elsewhere, but objects become plottable by inheriting from the exported base class and registering plotting methods. Users normally interact with this layer through calls such as obj.plot("heatmap", backend="plotly").

Exports

• Plottable Base class providing backend-aware plot-method registration and dispatch.

Notes

The concrete plot object types exposed to users are primarily documented in qten_plots, while this package focuses on the shared dispatch mechanism. The generated API page links to the Plot Methods index for the registered obj.plot(...) calls.

Exported API

Plottable

Bases: ABC

Base class for objects that dispatch plotting calls to registered backends.

Plottable does not implement plotting directly. Instead, backend packages register functions under (object type, method name, backend name) keys. Users call plot() on the object they want to visualize, and the dispatcher finds the matching registered function through the object's method-resolution order.

Repository usage

The qten-plots extension registers Plotly and Matplotlib implementations through the qten.plottings entry-point group. Those implementations remain private backend details; the public user-facing API is the dispatcher call, for example tensor.plot("heatmap", backend="plotly").

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)