whitecanvas.canvas

Canvas

Source code in whitecanvas\canvas\_base.py

class Canvas(CanvasBase):
    _CURRENT_INSTANCE: Canvas | None = None

    def __init__(
        self,
        backend: str | None = None,
        *,
        palette: ColormapType | None = None,
    ):
        self._backend = Backend(backend)
        self._backend_object = self._create_backend_object()
        super().__init__(palette=palette)
        self.__class__._CURRENT_INSTANCE = self

    @classmethod
    def from_backend(
        cls,
        obj: protocols.CanvasProtocol,
        *,
        palette: ColormapType | None = None,
        backend: str | None = None,
    ) -> Self:
        """Create a canvas object from a backend object."""
        with patch_dummy_backend() as name:
            # this patch will delay initialization by "_init_canvas" until the backend
            # objects are created.
            self = cls(backend=name, palette=palette)
        self._backend = Backend(backend)
        self._backend_object = obj
        self._init_canvas()
        return self

    def _create_backend_object(self) -> protocols.CanvasProtocol:
        return self._backend.get("Canvas")()

    def _get_backend(self):
        return self._backend

    def _canvas(self) -> protocols.CanvasProtocol:
        return self._backend_object

from_backend(obj, *, palette=None, backend=None) classmethod

Create a canvas object from a backend object.

Source code in whitecanvas\canvas\_base.py

@classmethod
def from_backend(
    cls,
    obj: protocols.CanvasProtocol,
    *,
    palette: ColormapType | None = None,
    backend: str | None = None,
) -> Self:
    """Create a canvas object from a backend object."""
    with patch_dummy_backend() as name:
        # this patch will delay initialization by "_init_canvas" until the backend
        # objects are created.
        self = cls(backend=name, palette=palette)
    self._backend = Backend(backend)
    self._backend_object = obj
    self._init_canvas()
    return self

CanvasBase

Base class for any canvas object.

Source code in whitecanvas\canvas\_base.py

class CanvasBase(CanvasNDBase):
    """Base class for any canvas object."""

    dims = Dims()
    overlays = _ll.LayerList()
    mouse = _ns.MouseNamespace()

    def __init__(self, palette: ColormapType | None = None):
        super().__init__(palette)
        self._autoscale_enabled = True
        if not self._get_backend().is_dummy():
            self._init_canvas()

    def _init_canvas(self):
        # default colors and font
        _t = theme.get_theme()
        _ft = _t.font
        self.x.color = _t.foreground_color
        self.y.color = _t.foreground_color
        self.x.label.update(family=_ft.family, color=_ft.color, size=_ft.size)
        self.y.label.update(family=_ft.family, color=_ft.color, size=_ft.size)
        self.title.update(family=_ft.family, color=_ft.color, size=_ft.size)
        self.x.ticks.update(family=_ft.family, color=_ft.color, size=_ft.size)
        self.y.ticks.update(family=_ft.family, color=_ft.color, size=_ft.size)

        # connect layer events
        self.layers.events.inserted.connect(
            self._cb_inserted, unique=True, max_args=None
        )
        self.layers.events.removed.connect(self._cb_removed, unique=True, max_args=None)
        self.layers.events.reordered.connect(
            self._cb_reordered, unique=True, max_args=None
        )
        self.layers.events.connect(self._draw_canvas, unique=True, max_args=None)

        self.overlays.events.inserted.connect(
            self._cb_overlay_inserted, unique=True, max_args=None
        )
        self.overlays.events.removed.connect(
            self._cb_removed, unique=True, max_args=None
        )
        self.overlays.events.connect(self._draw_canvas, unique=True, max_args=None)

        canvas = self._canvas()
        canvas._plt_connect_xlim_changed(self._emit_xlim_changed)
        canvas._plt_connect_ylim_changed(self._emit_ylim_changed)

        if hasattr(canvas, "_plt_canvas_hook"):
            canvas._plt_canvas_hook(self)

    def _install_mouse_events(self):
        canvas = self._canvas()
        canvas._plt_connect_mouse_click(self.mouse.clicked.emit)
        canvas._plt_connect_mouse_click(self.mouse.moved.emit)
        canvas._plt_connect_mouse_drag(self.mouse.moved.emit)
        canvas._plt_connect_mouse_release(self.mouse.moved.emit)
        canvas._plt_connect_mouse_double_click(self.mouse.double_clicked.emit)
        canvas._plt_connect_mouse_double_click(self.mouse.moved.emit)

    def _emit_xlim_changed(self, lim):
        self.x.events.lim.emit(lim)
        self.events.lims.emit(Rect(*lim, *self.y.lim))

    def _emit_ylim_changed(self, lim):
        self.y.events.lim.emit(lim)
        self.events.lims.emit(Rect(*self.x.lim, *lim))

    def _emit_mouse_moved(self, ev):
        """Emit mouse moved event with autoscaling blocked"""
        self.mouse.moved.emit(ev)

    @property
    def mouse_clicked(self):
        warnings.warn(
            "`canvas.events.mouse_clicked` is deprecated. Use `canvas.mouse.clicked` "
            "instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return self.mouse.clicked

    @property
    def mouse_moved(self):
        warnings.warn(
            "`canvas.events.mouse_moved` is deprecated. Use `canvas.mouse.moved` "
            "instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return self.mouse.clicked

    @property
    def mouse_double_clicked(self):
        warnings.warn(
            "`canvas.events.mouse_double_clicked` is deprecated. Use "
            "`canvas.mouse.double_clicked` instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return self.mouse.clicked

    @property
    def native(self) -> Any:
        """Return the native canvas object."""
        return self._canvas()._plt_get_native()

    @property
    def aspect_ratio(self) -> float | None:
        """Aspect ratio of the canvas (None if not locked)."""
        return self._canvas()._plt_get_aspect_ratio()

    @aspect_ratio.setter
    def aspect_ratio(self, ratio: float | None):
        if ratio is not None:
            ratio = float(ratio)
        self._canvas()._plt_set_aspect_ratio(ratio)

    @property
    def mouse_enabled(self) -> bool:
        warnings.warn(
            "`canvas.mouse_enabled` is deprecated. Use `canvas.mouse.enabled` instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        return self.mouse.enabled

    @mouse_enabled.setter
    def mouse_enabled(self, enabled: bool):
        warnings.warn(
            "`canvas.mouse_enabled` is deprecated. Use `canvas.mouse.enabled` instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        self.mouse.enabled = enabled

    def autoscale(
        self,
        xpad: float | tuple[float, float] | None = None,
        ypad: float | tuple[float, float] | None = None,
    ) -> tuple[float, float, float, float]:
        """
        Autoscale the canvas to fit the contents.

        Parameters
        ----------
        xpad : float or (float, float), optional
            Padding in the x direction.
        ypad : float or (float, float), optional
            Padding in the y direction.
        """
        ar = np.stack([layer.bbox_hint() for layer in self.layers], axis=0)
        xmin = np.min(ar[:, 0])
        xmax = np.max(ar[:, 1])
        ymin = np.min(ar[:, 2])
        ymax = np.max(ar[:, 3])
        x0, x1 = self.x.lim
        y0, y1 = self.y.lim
        if np.isnan(xmin):
            xmin = x0
        if np.isnan(xmax):
            xmax = x1
        if np.isnan(ymin):
            ymin = y0
        if np.isnan(ymax):
            ymax = y1
        if xpad is not None:
            xrange = xmax - xmin
            if is_real_number(xpad):
                dx0 = dx1 = xpad * xrange
            else:
                dx0, dx1 = xpad[0] * xrange, xpad[1] * xrange
            xmin -= dx0
            xmax += dx1
        if ypad is not None:
            yrange = ymax - ymin
            if is_real_number(ypad):
                dy0 = dy1 = ypad * yrange
            else:
                dy0, dy1 = ypad[0] * yrange, ypad[1] * yrange
            ymin -= dy0
            ymax += dy1
        small_diff = 1e-6
        if xmax - xmin < small_diff:
            xmin -= 0.05
            xmax += 0.05
        if ymax - ymin < small_diff:
            ymin -= 0.05
            ymax += 0.05
        self.x.lim = xmin, xmax
        self.y.lim = ymin, ymax
        return xmin, xmax, ymin, ymax

    def install_second_x(self, *, palette: ColormapType | None = None) -> Canvas:
        """Create a twin canvas that has a secondary x-axis and shared y-axis."""
        try:
            new = self._canvas()._plt_twiny()
        except AttributeError:
            raise NotImplementedError(
                f"Backend {self._get_backend()} does not support `install_second_x`."
            ) from None
        canvas = Canvas.from_backend(new, palette=palette, backend=self._get_backend())
        canvas._init_canvas()
        return canvas

    def install_second_y(self, *, palette: ColormapType | None = None) -> Canvas:
        """Create a twin canvas that has a secondary y-axis and shared x-axis."""
        try:
            new = self._canvas()._plt_twinx()
        except AttributeError:
            raise NotImplementedError(
                f"Backend {self._get_backend()} does not support `install_second_y`."
            ) from None
        canvas = Canvas.from_backend(new, palette=palette, backend=self._get_backend())
        canvas._init_canvas()
        return canvas

    @overload
    def install_inset(
        self, left: float, right: float, bottom: float, top: float, *,
        palette: ColormapType | None = None
    ) -> Canvas:  # fmt: skip
        ...

    @overload
    def install_inset(
        self, rect: Rect | tuple[float, float, float, float], /, *,
        palette: ColormapType | None = None
    ) -> Canvas:  # fmt: skip
        ...

    def install_inset(self, *args, palette=None, **kwargs) -> Canvas:
        """
        Install a new canvas pointing to an inset of the current canvas.

        >>> canvas.install_inset(left=0.1, right=0.9, bottom=0.1, top=0.9)
        >>> canvas.install_inset([0.1, 0.9, 0.1, 0.9])  # or a sequence
        """
        # normalize input
        if len(args) == 1 and not kwargs:
            rect = args[0]
            if not isinstance(rect, Rect):
                rect = Rect.with_check(*rect)
        else:
            rect = Rect.with_check(*args, **kwargs)
        try:
            new = self._canvas()._plt_inset(rect)
        except AttributeError:
            raise NotImplementedError(
                f"Backend {self._get_backend()} does not support `install_inset`"
            ) from None
        canvas = Canvas.from_backend(new, palette=palette, backend=self._get_backend())
        canvas._init_canvas()
        return canvas

    @property
    def visible(self):
        """Show the canvas."""
        return self._canvas()._plt_get_visible()

    @visible.setter
    def visible(self, visible):
        """Hide the canvas."""
        self._canvas()._plt_set_visible(visible)

    @property
    def lims(self) -> Rect:
        """Return the x/y limits of the canvas."""
        return Rect(*self.x.lim, *self.y.lim)

    @lims.setter
    def lims(self, lims: tuple[float, float, float, float]):
        xmin, xmax, ymin, ymax = lims
        if xmin >= xmax or ymin >= ymax:
            raise ValueError(f"Invalid view rect: {Rect(*lims)}")
        with self.events.lims.blocked():
            self.x.lim = xmin, xmax
            self.y.lim = ymin, ymax
        self.events.lims.emit(Rect(xmin, xmax, ymin, ymax))

    def update_axes(
        self,
        *,
        visible: bool | None = None,
        color: ColorType | None = None,
    ):
        """
        Update axes appearance.

        Parameters
        ----------
        visible : bool, optional
            Whether to show the axes.
        color : color-like, optional
            Color of the axes.
        """
        if visible is not None:
            self.x.ticks.visible = self.y.ticks.visible = visible
        if color is not None:
            self.x.color = self.y.color = color
            self.x.ticks.color = self.y.ticks.color = color
            self.x.label.color = self.y.label.color = color
        return self

    def update_labels(
        self,
        title: str | None = None,
        x: str | None = None,
        y: str | None = None,
    ) -> Self:
        """
        Helper function to update the title, x, and y labels.

        >>> from whitecanvas import new_canvas
        >>> canvas = new_canvas("matplotlib").update_labels("Title", "X", "Y")
        """
        if title is not None:
            self.title.text = title
            self.title.visible = True
        if x is not None:
            self.x.label.text = x
            self.x.label.visible = True
        if y is not None:
            self.y.label.text = y
            self.y.label.visible = True
        return self

    def update_font(
        self,
        size: float | None = None,
        color: ColorType | None = None,
        family: str | None = None,
    ) -> Self:
        """
        Update all the fonts, including the title, x/y labels and x/y tick labels.

        Parameters
        ----------
        size : float, optional
            New font size.
        color : color-like, optional
            New font color.
        family : str, optional
            New font family.
        """
        if size is not None:
            self.title.size = self.x.label.size = self.y.label.size = size
            self.x.ticks.size = self.y.ticks.size = size
        if family is not None:
            self.title.family = self.x.label.family = self.y.label.family = family
            self.x.ticks.family = self.y.ticks.family = family
        if color is not None:
            self.title.color = self.x.label.color = self.y.label.color = color
            self.x.ticks.color = self.y.ticks.color = color
        return self

    def cat(
        self,
        data: _DF,
        x: str | None = None,
        y: str | None = None,
        *,
        update_labels: bool = True,
    ) -> _df.CatPlotter[Self, _DF]:
        """
        Categorize input data for plotting.

        This method provides categorical plotting methods for the input data.
        Methods are very similar to `seaborn` and `plotly.express`.

        Parameters
        ----------
        data : tabular data
            Any categorizable data. Currently, dict, pandas.DataFrame, and
            polars.DataFrame are supported.
        x : str, optional
            Name of the column that will be used for the x-axis. Must be numerical.
        y : str, optional
            Name of the column that will be used for the y-axis. Must be numerical.
        update_labels : bool, default True
            If True, update the x/y labels to the corresponding names.

        Returns
        -------
        CatPlotter
            Plotter object.
        """
        plotter = _df.CatPlotter(self, data, x, y, update_labels=update_labels)
        return plotter

    def cat_x(
        self,
        data: _DF,
        x: str | Sequence[str] | None = None,
        y: str | None = None,
        *,
        update_labels: bool = True,
        numeric_axis: bool = False,
    ) -> _df.XCatPlotter[Self, _DF]:
        """
        Categorize input data for plotting with x-axis as a categorical axis.

        Parameters
        ----------
        data : tabular data
            Any categorizable data. Currently, dict, pandas.DataFrame, and
            polars.DataFrame are supported.
        x : str or sequence of str, optional
            Name of the column(s) that will be used for the x-axis. Must be categorical.
        y : str, optional
            Name of the column that will be used for the y-axis. Must be numerical.
        update_labels : bool, default True
            If True, update the x/y labels to the corresponding names.
        numeric_axis : bool, default False
            If True, the x-axis will be treated as a numerical axis. For example, if
            categories are [2, 4, 8], the x coordinates will be mapped to [0, 1, 2] by
            default, but if this option is True, the x coordinates will be [2, 4, 8].

        Returns
        -------
        XCatPlotter
            Plotter object.
        """
        return _df.XCatPlotter(self, data, x, y, update_labels, numeric=numeric_axis)

    def cat_y(
        self,
        data: _DF,
        x: str | None = None,
        y: str | Sequence[str] | None = None,
        *,
        update_labels: bool = True,
        numeric_axis: bool = False,
    ) -> _df.YCatPlotter[Self, _DF]:
        """
        Categorize input data for plotting with y-axis as a categorical axis.

        Parameters
        ----------
        data : tabular data
            Any categorizable data. Currently, dict, pandas.DataFrame, and
            polars.DataFrame are supported.
        x : str, optional
            Name of the column that will be used for the x-axis. Must be numerical.
        y : str or sequence of str, optional
            Name of the column(s) that will be used for the y-axis. Must be categorical.
        update_labels : bool, default True
            If True, update the x/y labels to the corresponding names.
        numeric_axis : bool, default False
            If True, the x-axis will be treated as a numerical axis. For example, if
            categories are [2, 4, 8], the y coordinates will be mapped to [0, 1, 2] by
            default, but if this option is True, the y coordinates will be [2, 4, 8].

        Returns
        -------
        YCatPlotter
            Plotter object
        """
        return _df.YCatPlotter(self, data, y, x, update_labels, numeric=numeric_axis)

    def cat_xy(
        self,
        data: _DF,
        x: str | Sequence[str],
        y: str | Sequence[str],
        *,
        update_labels: bool = True,
    ) -> _df.XYCatPlotter[Self, _DF]:
        """
        Categorize input data for plotting with both axes as categorical.

        Parameters
        ----------
        data : tabular data
            Any categorizable data. Currently, dict, pandas.DataFrame, and
            polars.DataFrame are supported.
        x : str or sequence of str, optional
            Name of the column(s) that will be used for the x-axis. Must be categorical.
        y : str or sequence of str, optional
            Name of the column(s) that will be used for the y-axis. Must be categorical.
        update_labels : bool, default True
            If True, update the x/y labels to the corresponding names.

        Returns
        -------
        XYCatPlotter
            Plotter object
        """
        return _df.XYCatPlotter(self, data, x, y, update_labels)

    def stack_over(self, layer: _L0) -> StackOverPlotter[Self, _L0]:
        """
        Stack new data over the existing layer.

        For example following code

        >>> bars_0 = canvas.add_bars(x, y0)
        >>> bars_1 = canvas.stack_over(bars_0).add(y1)
        >>> bars_2 = canvas.stack_over(bars_1).add(y2)

        will result in a bar plot like this

        ```
         ┌───┐
         ├───│┌───┐
         │   │├───│
         ├───│├───│
        ─┴───┴┴───┴─
        ```
        """
        if not isinstance(layer, (_l.Bars, _l.Band, _lg.StemPlot, _lg.LabeledBars)):
            raise TypeError(
                f"Only Bars, StemPlot and Band are supported as an input, "
                f"got {type(layer)!r}."
            )
        return StackOverPlotter(self, layer)

    # TODO
    # def annotate(self, layer, at: int):
    #     ...

    def between(self, l0, l1) -> BetweenPlotter[Self]:
        return BetweenPlotter(self, l0, l1)

    @deprecated(
        "ImageRef is deprecated and will be removed in the future. "
        "Please use the Image methods `with_text`, `with_colorbar` instead.",
    )
    def imref(self, layer: _l.Image):
        """The Image reference namespace."""
        from whitecanvas.canvas._imageref import ImageRef

        while isinstance(layer, _l.LayerWrapper):
            layer = layer._base_layer
        if not isinstance(layer, _l.Image):
            raise TypeError(
                f"Expected an Image layer or its wrapper, got {type(layer)}."
            )
        return ImageRef(self, layer)

    def fit(self, layer: _l.DataBoundLayer[_P]) -> FitPlotter[Self, _P]:
        """The fit plotter namespace."""
        return FitPlotter(self, layer)

    def add_legend(
        self,
        layers: Sequence[str | _l.Layer] | None = None,
        *,
        location: Location | LocationStr = "top_right",
        title: str | None = None,
    ):
        """
        Add legend item to the canvas.

        Parameters
        ----------
        layers : sequence of layer or str, optional
            Which item to be added to the legend. If str is given, it will be converted
            into a title label.
        location : LegendLocation, default "top_right"
            Location of the legend. Can be following strings. Combination of the
            following strings (e.g., "top_left", "center_right").

            ```
                   (2) left  center right
                         v     v     v
              (1)     ┌─────────────────┐
               top -> │                 │
            center -> │     canvas      │
            bottom -> │                 │
                      └─────────────────┘
            ```

            Some backends also support adding legend outside the canvas. Following
            strings suffixed with "_side" can be used in combination with those strings
            above (e.g., "bottom_side_rigth", "right_side_top").

            ```
               top_side -> ┌────────┐
                        ┌──┼────────┼──┐
            left_side ->│  │ canvas │  │<- right_side
                        └──┼────────┼──┘
            bottom_side -> └────────┘
            ```
        title : str, optional
            If given, title label will be added as the first legend item.
        """
        if layers is None:
            layers = list(self.layers)
        if title is not None:
            layers = [title, *layers]
        location = Location(location)

        items = list[tuple[str, _legend.LegendItem]]()
        for layer in layers:
            if isinstance(layer, str):
                items.append((layer, _legend.TitleItem()))
            elif isinstance(layer, _l.Layer):
                items.append((layer.name, layer._as_legend_item()))
            else:
                raise TypeError(f"Expected a list of layer or str, got {type(layer)}.")
        self._canvas()._plt_make_legend(items, location)

    @overload
    def add_line(
        self, ydata: ArrayLike1D, *, name: str | None = None,
        color: ColorType | None = None, width: float = 1.0,
        style: LineStyle | str = LineStyle.SOLID, alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.Line:  # fmt: skip
        ...

    @overload
    def add_line(
        self, xdata: ArrayLike1D, ydata: ArrayLike1D, *, name: str | None = None,
        color: ColorType | None = None, width: float | None = None,
        style: LineStyle | str | None = None, alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.Line:  # fmt: skip
        ...

    @overload
    def add_line(
        self, xdata: ArrayLike1D, ydata: Callable[[ArrayLike1D], ArrayLike1D], *,
        name: str | None = None, color: ColorType | None = None,
        width: float | None = None, style: LineStyle | str | None = None,
        alpha: float = 1.0, antialias: bool = True,
    ) -> _l.Line:  # fmt: skip
        ...

    def add_line(
        self,
        *args,
        name=None,
        color=None,
        width=None,
        style=None,
        alpha=1.0,
        antialias=True,
    ):
        """
        Add a Line layer to the canvas.

        >>> canvas.add_line(y, ...)
        >>> canvas.add_line(x, y, ...)

        Parameters
        ----------
        name : str, optional
            Name of the layer.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        Line
            The line layer.
        """
        xdata, ydata = normalize_xy(*args)
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)
        layer = _l.Line(
            xdata, ydata, name=name, color=color, width=width, style=style,
            alpha=alpha, antialias=antialias, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    @overload
    def add_markers(
        self, xdata: ArrayLike1D, ydata: ArrayLike1D, *,
        name: str | None = None, symbol: Symbol | str | None = None,
        size: float | None = None, color: ColorType | None = None, alpha: float = 1.0,
        hatch: str | Hatch | None = None,
    ) -> _l.Markers[_mixin.ConstFace, _mixin.ConstEdge, float]:  # fmt: skip
        ...

    @overload
    def add_markers(
        self, ydata: ArrayLike1D, *,
        name: str | None = None, symbol: Symbol | str | None = None,
        size: float | None = None, color: ColorType | None = None, alpha: float = 1.0,
        hatch: str | Hatch | None = None,
    ) -> _l.Markers[_mixin.ConstFace, _mixin.ConstEdge, float]:  # fmt: skip
        ...

    def add_markers(
        self,
        *args,
        name=None,
        symbol=None,
        size=None,
        color=None,
        alpha=1.0,
        hatch=None,
    ):
        """
        Add markers (scatter plot).

        >>> canvas.add_markers(x, y)  # standard usage
        >>> canvas.add_markers(y)  # use 0, 1, ... for the x values

        Parameters
        ----------
        name : str, optional
            Name of the layer.
        symbol : str or Symbol, optional
            Marker symbols. Use the theme default if not specified.
        size : float, optional
            Marker size. Use the theme default if not specified.
        color : color-like, optional
            Color of the marker faces.
        alpha : float, default 1.0
            Alpha channel of the marker faces.
        hatch : str or FacePattern, optional
            Pattern of the marker faces. Use the theme default if not specified.

        Returns
        -------
        Markers
            The markers layer.
        """
        xdata, ydata = normalize_xy(*args)
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        symbol = theme._default("markers.symbol", symbol)
        size = theme._default("markers.size", size)
        hatch = theme._default("markers.hatch", hatch)
        layer = _l.Markers(
            xdata, ydata, name=name, symbol=symbol, size=size, color=color,
            alpha=alpha, hatch=hatch, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    @overload
    def add_bars(
        self, center: ArrayLike1D, height: ArrayLike1D, *,
        bottom: ArrayLike1D | None = None, name=None,
        orient: OrientationLike = "vertical", extent: float | None = None,
        color: ColorType | None = None, alpha: float = 1.0,
        hatch: str | Hatch | None = None,
    ) -> _l.Bars[_mixin.ConstFace, _mixin.ConstEdge]:  # fmt: skip
        ...

    @overload
    def add_bars(
        self, height: ArrayLike1D, *, bottom: ArrayLike1D | None = None,
        name=None, orient: OrientationLike = "vertical",
        extent: float | None = None, color: ColorType | None = None,
        alpha: float = 1.0, hatch: str | Hatch | None = None,
    ) -> _l.Bars[_mixin.ConstFace, _mixin.ConstEdge]:  # fmt: skip
        ...

    def add_bars(
        self,
        *args,
        bottom=None,
        name=None,
        orient="vertical",
        extent=None,
        color=None,
        alpha=1.0,
        hatch=None,
    ):
        """
        Add a bar plot.

        >>> canvas.add_bars(x, heights)  # standard usage
        >>> canvas.add_bars(heights)  # use 0, 1, ... for the x values
        >>> canvas.add_bars(..., orient="horizontal")  # horizontal bars

        Parameters
        ----------
        bottom : float or array-like, optional
            Bottom level of the bars.
        name : str, optional
            Name of the layer.
        orient : str or Orientation, default "vertical"
            Orientation of the bars.
        extent : float, default 0.8
            Bar width in the canvas coordinate
        color : color-like, optional
            Color of the bars.
        alpha : float, default 1.0
            Alpha channel of the bars.
        hatch : str or FacePattern, default FacePattern.SOLID
            Pattern of the bar faces.

        Returns
        -------
        Bars
            The bars layer.
        """
        center, height = normalize_xy(*args)
        if bottom is not None:
            bottom = as_array_1d(bottom)
            if bottom.shape != height.shape:
                raise ValueError("Expected bottom to have the same shape as height")
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        extent = theme._default("bars.extent", extent)
        hatch = theme._default("bars.hatch", hatch)
        layer = _l.Bars(
            center, height, bottom, extent=extent, name=name, orient=orient,
            color=color, alpha=alpha, hatch=hatch, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_hist(
        self,
        data: ArrayLike1D,
        *,
        bins: HistBinType = "auto",
        limits: tuple[float, float] | None = None,
        name: str | None = None,
        shape: Literal["step", "polygon", "bars"] = "bars",
        kind: Literal["count", "density", "frequency", "percent"] = "count",
        orient: OrientationLike = "vertical",
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str | None = None,
    ) -> _lg.Histogram:
        """
        Add data as a histogram.

        >>> canvas.add_hist(np.random.normal(size=100), bins=12)

        Parameters
        ----------
        data : array-like
            1D Array of data.
        bins : int or 1D array-like, default "auto"
            Bins of the histogram. This parameter will directly be passed
            to `np.histogram`.
        limits : (float, float), optional
            Limits in which histogram will be built. This parameter will equivalent to
            the `range` paraneter of `np.histogram`.
        name : str, optional
            Name of the layer.
        shape : {"step", "polygon", "bars"}, default "bars"
            Shape of the histogram. This parameter defines how to convert the data into
            the line nodes.
        kind : {"count", "density", "probability", "frequency", "percent"}, optional
            Kind of the histogram.
        orient : str or Orientation, default "vertical"
            Orientation of the bars.
        color : color-like, optional
            Color of the bars.

        Returns
        -------
        Bars
            The bars layer that represents the histogram.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)
        layer = _lg.Histogram.from_array(
            data, bins=bins, limits=limits, shape=shape, kind=kind, name=name,
            color=color, width=width, style=style, orient=orient,
            backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_hist2d(
        self,
        x: ArrayLike1D,
        y: ArrayLike1D,
        *,
        cmap: ColormapType = "inferno",
        name: str | None = None,
        bins: HistBinType | tuple[HistBinType, HistBinType] = "auto",
        rangex: tuple[float, float] | None = None,
        rangey: tuple[float, float] | None = None,
        density: bool = False,
    ) -> _l.Image:
        """
        Add a 2D histogram of given X/Y data.

        >>> x = np.random.normal(size=100)
        >>> y = np.random.normal(size=200)
        >>> canvas.add_hist2d(x, y)

        Note that unlike `add_image()` method, this method does not lock the aspect
        ratio and flip the canvas by default.

        Parameters
        ----------
        x : array-like
            1D Array of X data.
        y : array-like
            1D Array of Y data.
        cmap : ColormapType, default "gray"
            Colormap used for the image.
        name : str, optional
            Name of the layer.
        bins : int or tuple[int, int], optional
            Bins of the histogram of X/Y dimension respectively. If an integer is given,
            it will be used for both dimensions.
        rangex : (float, float), optional
            Range of x values in which histogram will be built.
        rangey : (float, float), optional
            Range of y values in which histogram will be built.
        density : bool, default False
            If True, values of the histogram will be normalized so that the total
            intensity of the histogram will be 1.

        Returns
        -------
        Image
            Image layer representing the 2D histogram.
        """
        layer = _l.Image.build_hist(
            x, y, bins=bins, range=(rangex, rangey), density=density, name=name,
            cmap=cmap, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_rects(
        self,
        coords: ArrayLike,
        *,
        name=None,
        color: ColorType | None = None,
        alpha: float = 1.0,
        hatch: str | Hatch | None = None,
    ) -> _l.Rects[_mixin.ConstFace, _mixin.ConstEdge]:
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        hatch = theme._default("bars.hatch", hatch)
        layer = _l.Rects(
            coords, name=name, color=color, alpha=alpha, hatch=hatch,
            backend=self._get_backend()
        )  # fmt: skip
        return self.add_layer(layer)

    def add_cdf(
        self,
        data: ArrayLike1D,
        *,
        name: str | None = None,
        orient: OrientationLike = "vertical",
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str | None = None,
        alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.Line:
        """
        Add a empirical cumulative distribution function (CDF) plot.

        >>> canvas.add_cdf(np.random.normal(size=100))

        Parameters
        ----------
        data : array-like
            1D Array of data.
        name : str, optional
            Name of the layer.
        orient : str or Orientation, default "vertical"
            Orientation of the bars.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        Line
            The line layer that represents the CDF.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)
        layer = _l.Line.build_cdf(
            data, orient=orient, name=name, color=color, width=width, style=style,
            alpha=alpha, antialias=antialias, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_spans(
        self,
        spans: ArrayLike,
        *,
        name: str | None = None,
        orient: OrientationLike = "vertical",
        color: ColorType = "blue",
        alpha: float = 0.4,
        hatch: str | Hatch = Hatch.SOLID,
    ) -> _l.Spans:
        """
        Add spans that extends infinitely.

        >>> canvas.add_spans([[5, 10], [15, 20]])

           |::::|     |::::|
           |::::|     |::::|
        ───5────10────15───20─────>
           |::::|     |::::|
           |::::|     |::::|

        Parameters
        ----------
        spans : (N, 2) array-like
            Array that contains the start and end points of the spans.
        name : str, optional
            Name of the layer.
        orient : str or Orientation, default "vertical"
            Orientation of the bars.
        color : color-like, optional
            Color of the bars.
        alpha : float, default 0.4
            Alpha channel of the bars.
        hatch : str or FacePattern, default FacePattern.SOLID
            Pattern of the bar faces.

        Returns
        -------
        Spans
            The spans layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        layer = _l.Spans(
            spans, name=name, orient=orient, color=color, alpha=alpha,
            hatch=hatch, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_vectors(
        self,
        x: ArrayLike1D,
        y: ArrayLike1D,
        vx: ArrayLike1D,
        vy: ArrayLike1D,
        *,
        name: str | None = None,
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str | None = None,
        alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.Vectors:
        """
        Add a vector field to the canvas.

        >>> canvas.add_vectors(x, y, vx, vy)

        Parameters
        ----------
        x : array-like
            X coordinates of the vectors.
        y : array-like
            Y coordinates of the vectors.
        vx : array-like
            X components of the vectors.
        vy : array-like
            Y components of the vectors.
        name : str, optional
            Name of the layer.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        Vectors
            The vectors layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)
        layer = _l.Vectors(
            as_array_1d(x, dtype=np.float32), as_array_1d(y, dtype=np.float32),
            as_array_1d(vx, dtype=np.float32), as_array_1d(vy, dtype=np.float32),
            name=name, color=color, width=width, style=style,
            alpha=alpha, antialias=antialias, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_infline(
        self,
        pos: tuple[float, float] = (0, 0),
        angle: float = 0.0,
        *,
        name: str | None = None,
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str | None = None,
        alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.InfLine:
        """
        Add an infinitely long line to the canvas.

        >>> canvas.add_infline((0, 0), 45)  # y = x
        >>> canvas.add_infline((1, 0), 90)  # x = 1
        >>> canvas.add_infline((0, -1), 0)  # y = -1

        Parameters
        ----------
        pos : (float, float), default (0, 0)
            One of the points this line passes.
        angle : float, default 0.0
            Angle of the line in degree, defined by the counter-clockwise
            rotation from the x axis.
        name : str, optional
            Name of the layer.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        InfLine
            The infline layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)
        layer = _l.InfLine(
            pos, angle, name=name, color=color, alpha=alpha,
            width=width, style=style, antialias=antialias,
            backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_infcurve(
        self,
        model: Callable[Concatenate[Any, _P], Any],
        *,
        bounds: tuple[float, float] = (-float("inf"), float("inf")),
        name: str | None = None,
        color: ColorType | None = None,
        width: float | None = None,
        style: str | LineStyle | None = None,
        alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.InfCurve[_P]:
        """
        Add an infinite curve to the canvas.

        >>> canvas.add_infcurve(lambda x: x ** 2)  # parabola
        >>> canvas.add_infcurve(lambda x, a: np.sin(a*x)).update_params(2)  # parametric

        Parameters
        ----------
        model : callable
            The model function. The first argument must be the x coordinates. Same
            signature as `scipy.optimize.curve_fit`.
        bounds : (float, float), default (-inf, inf)
            Lower and upper bounds that the function is defined.
        name : str, optional
            Name of the layer.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        InfCurve
            The infcurve layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)
        layer = _l.InfCurve(
            model, bounds=bounds, name=name, color=color, width=width, alpha=alpha,
            style=style, antialias=antialias, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_hline(
        self,
        y: float,
        *,
        name: str | None = None,
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str = LineStyle.SOLID,
        alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.InfLine:
        """
        Add a infinite horizontal line to the canvas.

        Parameters
        ----------
        y : float
            Y coordinate of the line.
        name : str, optional
            Name of the layer.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        InfLine
            The infline layer.
        """
        return self.add_infline(
            (0, y), 0, name=name, color=color, width=width, style=style, alpha=alpha,
            antialias=antialias
        )  # fmt: skip

    def add_vline(
        self,
        x: float,
        *,
        name: str | None = None,
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str = LineStyle.SOLID,
        alpha: float = 1.0,
        antialias: bool = True,
    ) -> _l.InfLine:
        """
        Add a infinite vertical line to the canvas.

        Parameters
        ----------
        x : float
            X coordinate of the line.
        name : str, optional
            Name of the layer.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        InfLine
            The infline layer.
        """
        return self.add_infline(
            (x, 0), 90, name=name, color=color, width=width, style=style, alpha=alpha,
            antialias=antialias,
        )  # fmt: skip

    def add_band(
        self,
        xdata: ArrayLike1D,
        ylow: ArrayLike1D,
        yhigh: ArrayLike1D,
        *,
        name: str | None = None,
        orient: OrientationLike = "vertical",
        color: ColorType | None = None,
        alpha: float = 1.0,
        hatch: str | Hatch = Hatch.SOLID,
    ) -> _l.Band:
        """
        Add a band (fill-between) layer to the canvas.

        Parameters
        ----------
        xdata : array-like
            X coordinates of the band.
        ylow : array-like
            Either lower or upper y coordinates of the band.
        yhigh : array-like
            The other y coordinates of the band.
        name : str, optional
            Name of the layer, by default None
        orient : str, Orientation, default "vertical"
            Orientation of the band. If vertical, band will be filled between
            vertical orientation.,
        color : color-like, default None
            Color of the band face.,
        alpha : float, default 1.0
            Alpha channel of the band face.
        hatch : str, FacePattern, default FacePattern.SOLID
            Hatch of the band face.

        Returns
        -------
        Band
            The band layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        layer = _l.Band(
            xdata, ylow, yhigh, name=name, orient=orient, color=color,
            alpha=alpha, hatch=hatch, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_errorbars(
        self,
        xdata: ArrayLike1D,
        ylow: ArrayLike1D,
        yhigh: ArrayLike1D,
        *,
        name: str | None = None,
        orient: OrientationLike = "vertical",
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str | None = None,
        alpha: float = 1.0,
        antialias: bool = False,
        capsize: float = 0.0,
    ) -> _l.Errorbars:
        """
        Add parallel lines as errorbars.

        Parameters
        ----------
        xdata : array-like
            X coordinates of the errorbars.
        ylow : array-like
            Lower bound of the errorbars.
        yhigh : array-like
            Upper bound of the errorbars.
        name : str, optional
            Name of the layer.
        orient : str or Orientation, default "vertical"
            Orientation of the errorbars. If vertical, errorbars will be parallel
            to the y axis.
        color : color-like, optional
            Color of the bars.
        width : float, optional
            Line width. Use the theme default if not specified.
        style : str or LineStyle, optional
            Line style. Use the theme default if not specified.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.
        capsize : float, default 0.0
            Size of the caps of the error indicators

        Returns
        -------
        Errorbars
            The errorbars layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)
        layer = _l.Errorbars(
            xdata, ylow, yhigh, name=name, color=color, width=width,
            style=style, antialias=antialias, capsize=capsize, alpha=alpha,
            orient=orient, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_rug(
        self,
        events: ArrayLike1D,
        *,
        low: float = 0.0,
        high: float = 1.0,
        name: str | None = None,
        orient: OrientationLike = "vertical",
        color: ColorType = "black",
        width: float = 1.0,
        style: LineStyle | str = LineStyle.SOLID,
        antialias: bool = True,
        alpha: float = 1.0,
    ) -> _l.Rug:
        """
        Add input data as a rug plot.

        >>> canvas.add_rug([2, 4, 5, 8, 11])

        ```
          │ ││  │   │
        ──┴─┴┴──┴───┴──> x
          2 45  8   11
        ```

        Parameters
        ----------
        events : array-like
            A 1D array of events.
        low : float, default 0.0
            The lower bound of the rug lines.
        high : float, default 1.0
            The upper bound of the rug lines.
        name : str, optional
            Name of the layer.
        orient : str or Orientation, default "vertical"
            Orientation of the errorbars. If vertical, rug lines will be parallel
            to the y axis.
        color : color-like, optional
            Color of the bars.
        width : float, default 1.0
            Line width.
        style : str or LineStyle, default LineStyle.SOLID
            Line style.
        alpha : float, default 1.0
            Alpha channel of the line.
        antialias : bool, default True
            Antialiasing of the line.

        Returns
        -------
        Rug
            The rug layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        layer = _l.Rug(
            events, low=low, high=high, name=name, color=color, alpha=alpha,
            width=width, style=style, antialias=antialias, orient=orient,
            backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_kde(
        self,
        data: ArrayLike1D,
        *,
        bottom: float = 0.0,
        name: str | None = None,
        orient: OrientationLike = "vertical",
        band_width: KdeBandWidthType = "scott",
        color: ColorType | None = None,
        width: float | None = None,
        style: LineStyle | str | None = None,
    ) -> _lg.Kde:
        """
        Add data as a band layer representing kernel density estimation (KDE).

        Parameters
        ----------
        data : array-like
            1D data to calculate the KDE.
        bottom : float, default 0.0
            Scalar value that define the height of the bottom line.
        name : str, optional
            Name of the layer, by default None
        orient : str, Orientation, default "vertical"
            Orientation of the KDE.
        band_width : float or str, default "scott"
            Method to calculate the estimator bandwidth.
        color : color-like, default None
            Color of the band face.
        width : float, optional
            Line width of the outline.
        style : str or LineStyle, optional
            Line style of the outline.

        Returns
        -------
        Kde
            The KDE layer.
        """
        name = self._coerce_name(name)
        color = self._generate_colors(color)
        width = theme._default("line.width", width)
        style = theme._default("line.style", style)

        layer = _lg.Kde.from_array(
            data, bottom=bottom, scale=1, band_width=band_width, name=name,
            orient=orient, color=color, width=width, style=style,
            backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    @overload
    def add_text(
        self, x: ArrayLike1D, y: ArrayLike1D, string: list[str], *,
        color: ColorType = "black", size: float = 12, rotation: float = 0.0,
        anchor: str | Alignment = Alignment.BOTTOM_LEFT, family: str | None = None,
    ) -> _l.Texts[_mixin.ConstFace, _mixin.ConstEdge, _mixin.ConstFont]:  # fmt: skip
        ...

    @overload
    def add_text(
        self, x: float, y: float, string: str, *, color: ColorType = "black",
        size: float = 12, rotation: float = 0.0,
        anchor: str | Alignment = Alignment.BOTTOM_LEFT, family: str | None = None,
    ) -> _l.Texts[_mixin.ConstFace, _mixin.ConstEdge, _mixin.ConstFont]:  # fmt: skip
        ...

    def add_text(
        self,
        x,
        y,
        string,
        *,
        color="black",
        size=12,
        rotation=0.0,
        anchor=Alignment.BOTTOM_LEFT,
        family=None,
    ):
        """
        Add a text layer to the canvas.

        >>> canvas.add_text([0, 0], [1, 1], ["text-0", "text-1])
        >>> canvas.add_text(...).with_face(color="red")  # with background
        >>> canvas.add_text(...).with_edge(color="red")  # with outline

        Parameters
        ----------
        x : float or array-like
            X position(s) of the text.
        y : float or array-like
            Y position(s) of the text.
        string : str or list[str]
            Text string to display.
        color : ColorType, optional
            Color of the text string.
        size : float, default 12
            Point size of the text.
        rotation : float, default 0.0
            Rotation angle of the text in degrees.
        anchor : str or Alignment, default Alignment.BOTTOM_LEFT
            Anchor position of the text. The anchor position will be the coordinate
            given by (x, y).
        family : str, optional
            Font family of the text.

        Returns
        -------
        Texts
            The text layer.
        """
        if is_real_number(x) and is_real_number(y) and isinstance(string, str):
            x, y, string = [x], [y], [string]
        x_, y_ = normalize_xy(x, y)
        if isinstance(string, str):
            string = [string] * x_.size
        elif len(string) != x_.size:
            raise ValueError("Expected string to have the same size as x/y")
        layer = _l.Texts(
            x_, y_, string, color=color, size=size, rotation=rotation, anchor=anchor,
            family=family, backend=self._get_backend(),
        )  # fmt: skip
        return self.add_layer(layer)

    def add_image(
        self,
        image: ArrayLike,
        *,
        name: str | None = None,
        cmap: ColormapType = "gray",
        clim: tuple[float | None, float | None] | None = None,
        flip_canvas: bool = True,
        lock_aspect: bool = True,
    ) -> _l.Image:
        """
        Add an image layer to the canvas.

        This method automatically flips the image vertically by default. `add_heatmap`
        does the similar thing with slightly different default settings.

        Parameters
        ----------
        image : ArrayLike
            Image data. Must be 2D or 3D array. If 3D, the last dimension must be
            RGB(A). Note that the first dimension is the vertical axis.
        cmap : ColormapType, default "gray"
            Colormap used for the image.
        clim : (float or None, float or None) or None
            Contrast limits. If None, the limits are automatically determined by min and
            max of the data. You can also pass None separately to either limit to use
            the default behavior.
        flip_canvas : bool, default True
            If True, flip the canvas vertically so that the image looks normal.
        lock_aspect : bool, default True
            If True, lock the aspect ratio of the canvas to 1:1.

        Returns
        -------
        Image
            The image layer.
        """
        layer = _l.Image(
            image, name=name, cmap=cmap, clim=clim, backend=self._get_backend()
        )
        self.add_layer(layer)
        if flip_canvas and not self.y.flipped:
            self.y.flipped = True
        if lock_aspect:
            self.aspect_ratio = 1.0
        return layer

    def add_heatmap(
        self,
        image: ArrayLike,
        *,
        name: str | None = None,
        cmap: ColormapType = "inferno",
        clim: tuple[float | None, float | None] | None = None,
        flip_canvas: bool = False,
    ) -> _l.Image:
        """
        Add an image layer to the canvas as a heatmap.

        Use `add_image` to add the layer as an image.

        Parameters
        ----------
        image : ArrayLike
            Image data. Must be 2D or 3D array. If 3D, the last dimension must be
            RGB(A). Note that the first dimension is the vertical axis.
        cmap : ColormapType, default "gray"
            Colormap used for the image.
        clim : (float or None, float or None) or None
            Contrast limits. If None, the limits are automatically determined by min and
            max of the data. You can also pass None separately to either limit to use
            the default behavior.
        flip_canvas : bool, default False
            If True, flip the canvas vertically so that the image looks normal.

        Returns
        -------
        Image
            The image layer.
        """
        layer = _l.Image(
            image, name=name, cmap=cmap, clim=clim, backend=self._get_backend()
        )
        self.add_layer(layer)
        if flip_canvas and not self.y.flipped:
            self.y.flipped = True
        return layer

    def add_layer(
        self,
        layer: _L,
        *,
        over: _l.Layer | Iterable[_l.Layer] | None = None,
        under: _l.Layer | Iterable[_l.Layer] | None = None,
    ) -> _L:
        """Add a layer to the canvas."""
        if over is None and under is None:
            self.layers.append(layer)
        elif over is not None:
            if under is not None:
                raise ValueError("Cannot specify both `over` and `under`")
            if isinstance(over, _l.Layer):
                idx = self.layers.index(over)
            else:
                idx = max([self.layers.index(l) for l in over])
            self.layers.insert(idx + 1, layer)
        else:
            if isinstance(under, _l.Layer):
                idx = self.layers.index(under)
            else:
                idx = min([self.layers.index(l) for l in under])
            self.layers.insert(idx, layer)
        return layer

    @overload
    def group_layers(
        self,
        layers: Iterable[_l.Layer],
        name: str | None = None,
    ) -> _l.LayerGroup: ...

    @overload
    def group_layers(
        self, *layers: _l.Layer, name: str | None = None
    ) -> _l.LayerGroup: ...

    def group_layers(self, layers, *more_layers, name=None):
        """
        Group layers.

        Parameters
        ----------
        layers : iterable of Layer
            Layers to group.

        Returns
        -------
        LayerGroup
            The grouped layer.
        """
        if more_layers:
            if not isinstance(layers, _l.Layer):
                raise TypeError("No overload matches the arguments")
            layers = [layers, *more_layers]
        return _lg.LayerTuple(layers, name=name)

    def _autoscale_for_layer(
        self,
        layer: _l.Layer,
        pad_rel: float | None = None,
        maybe_empty: bool = True,
    ):
        """This function will be called when a layer is inserted to the canvas."""
        if not self.autoscale_enabled:
            return
        if pad_rel is None:
            pad_rel = 0 if layer._NO_PADDING_NEEDED else 0.025
        xmin, xmax, ymin, ymax = layer.bbox_hint()
        if len(self.layers) > 1 or not maybe_empty:
            # NOTE: if there was no layer, so backend may not have xlim/ylim,
            # or they may be set to a default value.
            _xmin, _xmax = self.x.lim
            _ymin, _ymax = self.y.lim
            _dx = (_xmax - _xmin) * pad_rel
            _dy = (_ymax - _ymin) * pad_rel
            xmin = np.min([xmin, _xmin + _dx])
            xmax = np.max([xmax, _xmax - _dx])
            ymin = np.min([ymin, _ymin + _dy])
            ymax = np.max([ymax, _ymax - _dy])

        # this happens when there is <= 1 data
        small_diff = 1e-6
        if np.isnan(xmax) or np.isnan(xmin):
            xmin, xmax = self.x.lim
        elif xmax - xmin < small_diff:
            xmin -= 0.05
            xmax += 0.05
        else:
            dx = (xmax - xmin) * pad_rel
            if (
                xmin != 0
                or not layer._ATTACH_TO_AXIS
                or getattr(layer, "orient", None) is not Orientation.HORIZONTAL
            ):
                xmin -= dx
            xmax += dx
        if np.isnan(ymax) or np.isnan(ymin):
            ymin, ymax = self.y.lim
        elif ymax - ymin < small_diff:
            ymin -= 0.05
            ymax += 0.05
        else:
            dy = (ymax - ymin) * pad_rel
            if (
                ymin != 0
                or not layer._ATTACH_TO_AXIS
                or getattr(layer, "orient", None) is not Orientation.VERTICAL
            ):
                ymin -= dy
            ymax += dy
        self.lims = xmin, xmax, ymin, ymax

    def _cb_overlay_inserted(self, idx: int, layer: _l.Layer):
        _canvas = self._canvas()
        fn = self._get_backend().get("as_overlay")
        for l in _iter_layers(layer):
            _canvas._plt_add_layer(l._backend)
            fn(l._backend, _canvas)
            l._connect_canvas(self)

        if isinstance(layer, _l.LayerWrapper):
            # TODO: check if connecting LayerGroup is necessary
            fn(l._backend, _canvas)
            layer._connect_canvas(self)

    def _cb_removed(self, idx: int, layer: _l.Layer):
        if self._is_grouping:
            return
        _canvas = self._canvas()
        for l in _iter_layers(layer):
            _canvas._plt_remove_layer(l._backend)
            l._disconnect_canvas(self)

    def _cb_layer_grouped(self, group: _l.LayerGroup):
        indices: list[int] = []  # layers to remove
        not_found: list[_l.PrimitiveLayer] = []  # primitive layers to add
        id_exists = set(map(id, self.layers.iter_primitives()))
        for layer in group.iter_children():
            try:
                idx = self.layers.index(layer)
                indices.append(idx)
            except ValueError:
                not_found.extend(_iter_layers(layer))
        if not indices:
            return
        self._is_grouping = True
        try:
            for idx in reversed(indices):
                # remove from the layer list since it is directly grouped
                self.layers.pop(idx)
            self.layers.append(group)
            _canvas = self._canvas()
            for child in not_found:
                if id(child) in id_exists:
                    # skip since it is already in the canvas
                    continue
                child._connect_canvas(self)
                _canvas._plt_add_layer(child._backend)
        finally:
            self._is_grouping = False
        self._cb_reordered()
        self._autoscale_for_layer(group)

    def _generate_colors(self, color: ColorType | None) -> Color:
        if color is None:
            color = self._color_palette.next()
        return color

aspect_ratio: float | None property writable

Aspect ratio of the canvas (None if not locked).

lims: Rect property writable

Return the x/y limits of the canvas.

native: Any property

Return the native canvas object.

visible property writable

Show the canvas.

add_band(xdata, ylow, yhigh, *, name=None, orient='vertical', color=None, alpha=1.0, hatch=Hatch.SOLID)

Add a band (fill-between) layer to the canvas.

Parameters:

Name	Type	Description	Default
xdata	array - like	X coordinates of the band.	required
ylow	array - like	Either lower or upper y coordinates of the band.	required
yhigh	array - like	The other y coordinates of the band.	required
name	str	Name of the layer, by default None	None
orient	(str, Orientation)	Orientation of the band. If vertical, band will be filled between vertical orientation.,	"vertical"
color	color - like	Color of the band face.,	None
alpha	float	Alpha channel of the band face.	1.0
hatch	(str, FacePattern)	Hatch of the band face.	FacePattern.SOLID

Returns:

Type	Description
Band	The band layer.

Source code in whitecanvas\canvas\_base.py

def add_band(
    self,
    xdata: ArrayLike1D,
    ylow: ArrayLike1D,
    yhigh: ArrayLike1D,
    *,
    name: str | None = None,
    orient: OrientationLike = "vertical",
    color: ColorType | None = None,
    alpha: float = 1.0,
    hatch: str | Hatch = Hatch.SOLID,
) -> _l.Band:
    """
    Add a band (fill-between) layer to the canvas.

    Parameters
    ----------
    xdata : array-like
        X coordinates of the band.
    ylow : array-like
        Either lower or upper y coordinates of the band.
    yhigh : array-like
        The other y coordinates of the band.
    name : str, optional
        Name of the layer, by default None
    orient : str, Orientation, default "vertical"
        Orientation of the band. If vertical, band will be filled between
        vertical orientation.,
    color : color-like, default None
        Color of the band face.,
    alpha : float, default 1.0
        Alpha channel of the band face.
    hatch : str, FacePattern, default FacePattern.SOLID
        Hatch of the band face.

    Returns
    -------
    Band
        The band layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    layer = _l.Band(
        xdata, ylow, yhigh, name=name, orient=orient, color=color,
        alpha=alpha, hatch=hatch, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_bars(*args, bottom=None, name=None, orient='vertical', extent=None, color=None, alpha=1.0, hatch=None)

Add a bar plot.

canvas.add_bars(x, heights) # standard usage canvas.add_bars(heights) # use 0, 1, ... for the x values canvas.add_bars(..., orient="horizontal") # horizontal bars

Parameters:

Name	Type	Description	Default
bottom	float or array - like	Bottom level of the bars.	None
name	str	Name of the layer.	None
orient	str or Orientation	Orientation of the bars.	"vertical"
extent	float	Bar width in the canvas coordinate	0.8
color	color - like	Color of the bars.	None
alpha	float	Alpha channel of the bars.	1.0
hatch	str or FacePattern	Pattern of the bar faces.	FacePattern.SOLID

Returns:

Type	Description
Bars	The bars layer.

Source code in whitecanvas\canvas\_base.py

def add_bars(
    self,
    *args,
    bottom=None,
    name=None,
    orient="vertical",
    extent=None,
    color=None,
    alpha=1.0,
    hatch=None,
):
    """
    Add a bar plot.

    >>> canvas.add_bars(x, heights)  # standard usage
    >>> canvas.add_bars(heights)  # use 0, 1, ... for the x values
    >>> canvas.add_bars(..., orient="horizontal")  # horizontal bars

    Parameters
    ----------
    bottom : float or array-like, optional
        Bottom level of the bars.
    name : str, optional
        Name of the layer.
    orient : str or Orientation, default "vertical"
        Orientation of the bars.
    extent : float, default 0.8
        Bar width in the canvas coordinate
    color : color-like, optional
        Color of the bars.
    alpha : float, default 1.0
        Alpha channel of the bars.
    hatch : str or FacePattern, default FacePattern.SOLID
        Pattern of the bar faces.

    Returns
    -------
    Bars
        The bars layer.
    """
    center, height = normalize_xy(*args)
    if bottom is not None:
        bottom = as_array_1d(bottom)
        if bottom.shape != height.shape:
            raise ValueError("Expected bottom to have the same shape as height")
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    extent = theme._default("bars.extent", extent)
    hatch = theme._default("bars.hatch", hatch)
    layer = _l.Bars(
        center, height, bottom, extent=extent, name=name, orient=orient,
        color=color, alpha=alpha, hatch=hatch, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_cdf(data, *, name=None, orient='vertical', color=None, width=None, style=None, alpha=1.0, antialias=True)

Add a empirical cumulative distribution function (CDF) plot.

canvas.add_cdf(np.random.normal(size=100))

Parameters:

Name	Type	Description	Default
data	array - like	1D Array of data.	required
name	str	Name of the layer.	None
orient	str or Orientation	Orientation of the bars.	"vertical"
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	None
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
Line	The line layer that represents the CDF.

Source code in whitecanvas\canvas\_base.py

def add_cdf(
    self,
    data: ArrayLike1D,
    *,
    name: str | None = None,
    orient: OrientationLike = "vertical",
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str | None = None,
    alpha: float = 1.0,
    antialias: bool = True,
) -> _l.Line:
    """
    Add a empirical cumulative distribution function (CDF) plot.

    >>> canvas.add_cdf(np.random.normal(size=100))

    Parameters
    ----------
    data : array-like
        1D Array of data.
    name : str, optional
        Name of the layer.
    orient : str or Orientation, default "vertical"
        Orientation of the bars.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    Line
        The line layer that represents the CDF.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)
    layer = _l.Line.build_cdf(
        data, orient=orient, name=name, color=color, width=width, style=style,
        alpha=alpha, antialias=antialias, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_errorbars(xdata, ylow, yhigh, *, name=None, orient='vertical', color=None, width=None, style=None, alpha=1.0, antialias=False, capsize=0.0)

Add parallel lines as errorbars.

Parameters:

Name	Type	Description	Default
xdata	array - like	X coordinates of the errorbars.	required
ylow	array - like	Lower bound of the errorbars.	required
yhigh	array - like	Upper bound of the errorbars.	required
name	str	Name of the layer.	None
orient	str or Orientation	Orientation of the errorbars. If vertical, errorbars will be parallel to the y axis.	"vertical"
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	None
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True
capsize	float	Size of the caps of the error indicators	0.0

Returns:

Type	Description
Errorbars	The errorbars layer.

Source code in whitecanvas\canvas\_base.py

def add_errorbars(
    self,
    xdata: ArrayLike1D,
    ylow: ArrayLike1D,
    yhigh: ArrayLike1D,
    *,
    name: str | None = None,
    orient: OrientationLike = "vertical",
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str | None = None,
    alpha: float = 1.0,
    antialias: bool = False,
    capsize: float = 0.0,
) -> _l.Errorbars:
    """
    Add parallel lines as errorbars.

    Parameters
    ----------
    xdata : array-like
        X coordinates of the errorbars.
    ylow : array-like
        Lower bound of the errorbars.
    yhigh : array-like
        Upper bound of the errorbars.
    name : str, optional
        Name of the layer.
    orient : str or Orientation, default "vertical"
        Orientation of the errorbars. If vertical, errorbars will be parallel
        to the y axis.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.
    capsize : float, default 0.0
        Size of the caps of the error indicators

    Returns
    -------
    Errorbars
        The errorbars layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)
    layer = _l.Errorbars(
        xdata, ylow, yhigh, name=name, color=color, width=width,
        style=style, antialias=antialias, capsize=capsize, alpha=alpha,
        orient=orient, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_heatmap(image, *, name=None, cmap='inferno', clim=None, flip_canvas=False)

Add an image layer to the canvas as a heatmap.

Use add_image to add the layer as an image.

Parameters:

Name	Type	Description	Default
image	ArrayLike	Image data. Must be 2D or 3D array. If 3D, the last dimension must be RGB(A). Note that the first dimension is the vertical axis.	required
cmap	ColormapType	Colormap used for the image.	"gray"
clim	(float or None, float or None) or None	Contrast limits. If None, the limits are automatically determined by min and max of the data. You can also pass None separately to either limit to use the default behavior.	None
flip_canvas	bool	If True, flip the canvas vertically so that the image looks normal.	False

Returns:

Type	Description
Image	The image layer.

Source code in whitecanvas\canvas\_base.py

def add_heatmap(
    self,
    image: ArrayLike,
    *,
    name: str | None = None,
    cmap: ColormapType = "inferno",
    clim: tuple[float | None, float | None] | None = None,
    flip_canvas: bool = False,
) -> _l.Image:
    """
    Add an image layer to the canvas as a heatmap.

    Use `add_image` to add the layer as an image.

    Parameters
    ----------
    image : ArrayLike
        Image data. Must be 2D or 3D array. If 3D, the last dimension must be
        RGB(A). Note that the first dimension is the vertical axis.
    cmap : ColormapType, default "gray"
        Colormap used for the image.
    clim : (float or None, float or None) or None
        Contrast limits. If None, the limits are automatically determined by min and
        max of the data. You can also pass None separately to either limit to use
        the default behavior.
    flip_canvas : bool, default False
        If True, flip the canvas vertically so that the image looks normal.

    Returns
    -------
    Image
        The image layer.
    """
    layer = _l.Image(
        image, name=name, cmap=cmap, clim=clim, backend=self._get_backend()
    )
    self.add_layer(layer)
    if flip_canvas and not self.y.flipped:
        self.y.flipped = True
    return layer

add_hist(data, *, bins='auto', limits=None, name=None, shape='bars', kind='count', orient='vertical', color=None, width=None, style=None)

Add data as a histogram.

canvas.add_hist(np.random.normal(size=100), bins=12)

Parameters:

Name	Type	Description	Default
data	array - like	1D Array of data.	required
bins	int or 1D array-like	Bins of the histogram. This parameter will directly be passed to np.histogram.	"auto"
limits	(float, float)	Limits in which histogram will be built. This parameter will equivalent to the range paraneter of np.histogram.	None
name	str	Name of the layer.	None
shape	('step', 'polygon', 'bars')	Shape of the histogram. This parameter defines how to convert the data into the line nodes.	"step"
kind	('count', 'density', 'probability', 'frequency', 'percent')	Kind of the histogram.	"count"
orient	str or Orientation	Orientation of the bars.	"vertical"
color	color - like	Color of the bars.	None

Returns:

Type	Description
Bars	The bars layer that represents the histogram.

Source code in whitecanvas\canvas\_base.py

def add_hist(
    self,
    data: ArrayLike1D,
    *,
    bins: HistBinType = "auto",
    limits: tuple[float, float] | None = None,
    name: str | None = None,
    shape: Literal["step", "polygon", "bars"] = "bars",
    kind: Literal["count", "density", "frequency", "percent"] = "count",
    orient: OrientationLike = "vertical",
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str | None = None,
) -> _lg.Histogram:
    """
    Add data as a histogram.

    >>> canvas.add_hist(np.random.normal(size=100), bins=12)

    Parameters
    ----------
    data : array-like
        1D Array of data.
    bins : int or 1D array-like, default "auto"
        Bins of the histogram. This parameter will directly be passed
        to `np.histogram`.
    limits : (float, float), optional
        Limits in which histogram will be built. This parameter will equivalent to
        the `range` paraneter of `np.histogram`.
    name : str, optional
        Name of the layer.
    shape : {"step", "polygon", "bars"}, default "bars"
        Shape of the histogram. This parameter defines how to convert the data into
        the line nodes.
    kind : {"count", "density", "probability", "frequency", "percent"}, optional
        Kind of the histogram.
    orient : str or Orientation, default "vertical"
        Orientation of the bars.
    color : color-like, optional
        Color of the bars.

    Returns
    -------
    Bars
        The bars layer that represents the histogram.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)
    layer = _lg.Histogram.from_array(
        data, bins=bins, limits=limits, shape=shape, kind=kind, name=name,
        color=color, width=width, style=style, orient=orient,
        backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_hist2d(x, y, *, cmap='inferno', name=None, bins='auto', rangex=None, rangey=None, density=False)

Add a 2D histogram of given X/Y data.

x = np.random.normal(size=100) y = np.random.normal(size=200) canvas.add_hist2d(x, y)

Note that unlike add_image() method, this method does not lock the aspect ratio and flip the canvas by default.

Parameters:

Name	Type	Description	Default
x	array - like	1D Array of X data.	required
y	array - like	1D Array of Y data.	required
cmap	ColormapType	Colormap used for the image.	"gray"
name	str	Name of the layer.	None
bins	int or tuple[int, int]	Bins of the histogram of X/Y dimension respectively. If an integer is given, it will be used for both dimensions.	'auto'
rangex	(float, float)	Range of x values in which histogram will be built.	None
rangey	(float, float)	Range of y values in which histogram will be built.	None
density	bool	If True, values of the histogram will be normalized so that the total intensity of the histogram will be 1.	False

Returns:

Type	Description
Image	Image layer representing the 2D histogram.

Source code in whitecanvas\canvas\_base.py

def add_hist2d(
    self,
    x: ArrayLike1D,
    y: ArrayLike1D,
    *,
    cmap: ColormapType = "inferno",
    name: str | None = None,
    bins: HistBinType | tuple[HistBinType, HistBinType] = "auto",
    rangex: tuple[float, float] | None = None,
    rangey: tuple[float, float] | None = None,
    density: bool = False,
) -> _l.Image:
    """
    Add a 2D histogram of given X/Y data.

    >>> x = np.random.normal(size=100)
    >>> y = np.random.normal(size=200)
    >>> canvas.add_hist2d(x, y)

    Note that unlike `add_image()` method, this method does not lock the aspect
    ratio and flip the canvas by default.

    Parameters
    ----------
    x : array-like
        1D Array of X data.
    y : array-like
        1D Array of Y data.
    cmap : ColormapType, default "gray"
        Colormap used for the image.
    name : str, optional
        Name of the layer.
    bins : int or tuple[int, int], optional
        Bins of the histogram of X/Y dimension respectively. If an integer is given,
        it will be used for both dimensions.
    rangex : (float, float), optional
        Range of x values in which histogram will be built.
    rangey : (float, float), optional
        Range of y values in which histogram will be built.
    density : bool, default False
        If True, values of the histogram will be normalized so that the total
        intensity of the histogram will be 1.

    Returns
    -------
    Image
        Image layer representing the 2D histogram.
    """
    layer = _l.Image.build_hist(
        x, y, bins=bins, range=(rangex, rangey), density=density, name=name,
        cmap=cmap, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_hline(y, *, name=None, color=None, width=None, style=LineStyle.SOLID, alpha=1.0, antialias=True)

Add a infinite horizontal line to the canvas.

Parameters:

Name	Type	Description	Default
y	float	Y coordinate of the line.	required
name	str	Name of the layer.	None
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	SOLID
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
InfLine	The infline layer.

Source code in whitecanvas\canvas\_base.py

def add_hline(
    self,
    y: float,
    *,
    name: str | None = None,
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str = LineStyle.SOLID,
    alpha: float = 1.0,
    antialias: bool = True,
) -> _l.InfLine:
    """
    Add a infinite horizontal line to the canvas.

    Parameters
    ----------
    y : float
        Y coordinate of the line.
    name : str, optional
        Name of the layer.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    InfLine
        The infline layer.
    """
    return self.add_infline(
        (0, y), 0, name=name, color=color, width=width, style=style, alpha=alpha,
        antialias=antialias
    )  # fmt: skip

add_image(image, *, name=None, cmap='gray', clim=None, flip_canvas=True, lock_aspect=True)

Add an image layer to the canvas.

This method automatically flips the image vertically by default. add_heatmap does the similar thing with slightly different default settings.

Parameters:

Name	Type	Description	Default
image	ArrayLike	Image data. Must be 2D or 3D array. If 3D, the last dimension must be RGB(A). Note that the first dimension is the vertical axis.	required
cmap	ColormapType	Colormap used for the image.	"gray"
clim	(float or None, float or None) or None	Contrast limits. If None, the limits are automatically determined by min and max of the data. You can also pass None separately to either limit to use the default behavior.	None
flip_canvas	bool	If True, flip the canvas vertically so that the image looks normal.	True
lock_aspect	bool	If True, lock the aspect ratio of the canvas to 1:1.	True

Returns:

Type	Description
Image	The image layer.

Source code in whitecanvas\canvas\_base.py

def add_image(
    self,
    image: ArrayLike,
    *,
    name: str | None = None,
    cmap: ColormapType = "gray",
    clim: tuple[float | None, float | None] | None = None,
    flip_canvas: bool = True,
    lock_aspect: bool = True,
) -> _l.Image:
    """
    Add an image layer to the canvas.

    This method automatically flips the image vertically by default. `add_heatmap`
    does the similar thing with slightly different default settings.

    Parameters
    ----------
    image : ArrayLike
        Image data. Must be 2D or 3D array. If 3D, the last dimension must be
        RGB(A). Note that the first dimension is the vertical axis.
    cmap : ColormapType, default "gray"
        Colormap used for the image.
    clim : (float or None, float or None) or None
        Contrast limits. If None, the limits are automatically determined by min and
        max of the data. You can also pass None separately to either limit to use
        the default behavior.
    flip_canvas : bool, default True
        If True, flip the canvas vertically so that the image looks normal.
    lock_aspect : bool, default True
        If True, lock the aspect ratio of the canvas to 1:1.

    Returns
    -------
    Image
        The image layer.
    """
    layer = _l.Image(
        image, name=name, cmap=cmap, clim=clim, backend=self._get_backend()
    )
    self.add_layer(layer)
    if flip_canvas and not self.y.flipped:
        self.y.flipped = True
    if lock_aspect:
        self.aspect_ratio = 1.0
    return layer

add_infcurve(model, *, bounds=(-float('inf'), float('inf')), name=None, color=None, width=None, style=None, alpha=1.0, antialias=True)

Add an infinite curve to the canvas.

canvas.add_infcurve(lambda x: x ** 2) # parabola canvas.add_infcurve(lambda x, a: np.sin(a*x)).update_params(2) # parametric

Parameters:

Name	Type	Description	Default
model	callable	The model function. The first argument must be the x coordinates. Same signature as scipy.optimize.curve_fit.	required
bounds	(float, float)	Lower and upper bounds that the function is defined.	(-inf, inf)
name	str	Name of the layer.	None
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	None
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
InfCurve	The infcurve layer.

Source code in whitecanvas\canvas\_base.py

def add_infcurve(
    self,
    model: Callable[Concatenate[Any, _P], Any],
    *,
    bounds: tuple[float, float] = (-float("inf"), float("inf")),
    name: str | None = None,
    color: ColorType | None = None,
    width: float | None = None,
    style: str | LineStyle | None = None,
    alpha: float = 1.0,
    antialias: bool = True,
) -> _l.InfCurve[_P]:
    """
    Add an infinite curve to the canvas.

    >>> canvas.add_infcurve(lambda x: x ** 2)  # parabola
    >>> canvas.add_infcurve(lambda x, a: np.sin(a*x)).update_params(2)  # parametric

    Parameters
    ----------
    model : callable
        The model function. The first argument must be the x coordinates. Same
        signature as `scipy.optimize.curve_fit`.
    bounds : (float, float), default (-inf, inf)
        Lower and upper bounds that the function is defined.
    name : str, optional
        Name of the layer.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    InfCurve
        The infcurve layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)
    layer = _l.InfCurve(
        model, bounds=bounds, name=name, color=color, width=width, alpha=alpha,
        style=style, antialias=antialias, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_infline(pos=(0, 0), angle=0.0, *, name=None, color=None, width=None, style=None, alpha=1.0, antialias=True)

Add an infinitely long line to the canvas.

canvas.add_infline((0, 0), 45) # y = x canvas.add_infline((1, 0), 90) # x = 1 canvas.add_infline((0, -1), 0) # y = -1

Parameters:

Name	Type	Description	Default
pos	(float, float)	One of the points this line passes.	(0, 0)
angle	float	Angle of the line in degree, defined by the counter-clockwise rotation from the x axis.	0.0
name	str	Name of the layer.	None
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	None
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
InfLine	The infline layer.

Source code in whitecanvas\canvas\_base.py

def add_infline(
    self,
    pos: tuple[float, float] = (0, 0),
    angle: float = 0.0,
    *,
    name: str | None = None,
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str | None = None,
    alpha: float = 1.0,
    antialias: bool = True,
) -> _l.InfLine:
    """
    Add an infinitely long line to the canvas.

    >>> canvas.add_infline((0, 0), 45)  # y = x
    >>> canvas.add_infline((1, 0), 90)  # x = 1
    >>> canvas.add_infline((0, -1), 0)  # y = -1

    Parameters
    ----------
    pos : (float, float), default (0, 0)
        One of the points this line passes.
    angle : float, default 0.0
        Angle of the line in degree, defined by the counter-clockwise
        rotation from the x axis.
    name : str, optional
        Name of the layer.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    InfLine
        The infline layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)
    layer = _l.InfLine(
        pos, angle, name=name, color=color, alpha=alpha,
        width=width, style=style, antialias=antialias,
        backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_kde(data, *, bottom=0.0, name=None, orient='vertical', band_width='scott', color=None, width=None, style=None)

Add data as a band layer representing kernel density estimation (KDE).

Parameters:

Name	Type	Description	Default
data	array - like	1D data to calculate the KDE.	required
bottom	float	Scalar value that define the height of the bottom line.	0.0
name	str	Name of the layer, by default None	None
orient	(str, Orientation)	Orientation of the KDE.	"vertical"
band_width	float or str	Method to calculate the estimator bandwidth.	"scott"
color	color - like	Color of the band face.	None
width	float	Line width of the outline.	None
style	str or LineStyle	Line style of the outline.	None

Returns:

Type	Description
Kde	The KDE layer.

Source code in whitecanvas\canvas\_base.py

def add_kde(
    self,
    data: ArrayLike1D,
    *,
    bottom: float = 0.0,
    name: str | None = None,
    orient: OrientationLike = "vertical",
    band_width: KdeBandWidthType = "scott",
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str | None = None,
) -> _lg.Kde:
    """
    Add data as a band layer representing kernel density estimation (KDE).

    Parameters
    ----------
    data : array-like
        1D data to calculate the KDE.
    bottom : float, default 0.0
        Scalar value that define the height of the bottom line.
    name : str, optional
        Name of the layer, by default None
    orient : str, Orientation, default "vertical"
        Orientation of the KDE.
    band_width : float or str, default "scott"
        Method to calculate the estimator bandwidth.
    color : color-like, default None
        Color of the band face.
    width : float, optional
        Line width of the outline.
    style : str or LineStyle, optional
        Line style of the outline.

    Returns
    -------
    Kde
        The KDE layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)

    layer = _lg.Kde.from_array(
        data, bottom=bottom, scale=1, band_width=band_width, name=name,
        orient=orient, color=color, width=width, style=style,
        backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_layer(layer, *, over=None, under=None)

Add a layer to the canvas.

Source code in whitecanvas\canvas\_base.py

def add_layer(
    self,
    layer: _L,
    *,
    over: _l.Layer | Iterable[_l.Layer] | None = None,
    under: _l.Layer | Iterable[_l.Layer] | None = None,
) -> _L:
    """Add a layer to the canvas."""
    if over is None and under is None:
        self.layers.append(layer)
    elif over is not None:
        if under is not None:
            raise ValueError("Cannot specify both `over` and `under`")
        if isinstance(over, _l.Layer):
            idx = self.layers.index(over)
        else:
            idx = max([self.layers.index(l) for l in over])
        self.layers.insert(idx + 1, layer)
    else:
        if isinstance(under, _l.Layer):
            idx = self.layers.index(under)
        else:
            idx = min([self.layers.index(l) for l in under])
        self.layers.insert(idx, layer)
    return layer

add_legend(layers=None, *, location='top_right', title=None)

Add legend item to the canvas.

Parameters:

Name	Type	Description	Default
layers	sequence of layer or str	Which item to be added to the legend. If str is given, it will be converted into a title label.	None
location	LegendLocation	Location of the legend. Can be following strings. Combination of the following strings (e.g., "top_left", "center_right"). (2) left center right v v v (1) ┌─────────────────┐ top -> │ │ center -> │ canvas │ bottom -> │ │ └─────────────────┘ Some backends also support adding legend outside the canvas. Following strings suffixed with "_side" can be used in combination with those strings above (e.g., "bottom_side_rigth", "right_side_top"). top_side -> ┌────────┐ ┌──┼────────┼──┐ left_side ->│ │ canvas │ │<- right_side └──┼────────┼──┘ bottom_side -> └────────┘	"top_right"
title	str	If given, title label will be added as the first legend item.	None

Source code in whitecanvas\canvas\_base.py

def add_legend(
    self,
    layers: Sequence[str | _l.Layer] | None = None,
    *,
    location: Location | LocationStr = "top_right",
    title: str | None = None,
):
    """
    Add legend item to the canvas.

    Parameters
    ----------
    layers : sequence of layer or str, optional
        Which item to be added to the legend. If str is given, it will be converted
        into a title label.
    location : LegendLocation, default "top_right"
        Location of the legend. Can be following strings. Combination of the
        following strings (e.g., "top_left", "center_right").

        ```
               (2) left  center right
                     v     v     v
          (1)     ┌─────────────────┐
           top -> │                 │
        center -> │     canvas      │
        bottom -> │                 │
                  └─────────────────┘
        ```

        Some backends also support adding legend outside the canvas. Following
        strings suffixed with "_side" can be used in combination with those strings
        above (e.g., "bottom_side_rigth", "right_side_top").

        ```
           top_side -> ┌────────┐
                    ┌──┼────────┼──┐
        left_side ->│  │ canvas │  │<- right_side
                    └──┼────────┼──┘
        bottom_side -> └────────┘
        ```
    title : str, optional
        If given, title label will be added as the first legend item.
    """
    if layers is None:
        layers = list(self.layers)
    if title is not None:
        layers = [title, *layers]
    location = Location(location)

    items = list[tuple[str, _legend.LegendItem]]()
    for layer in layers:
        if isinstance(layer, str):
            items.append((layer, _legend.TitleItem()))
        elif isinstance(layer, _l.Layer):
            items.append((layer.name, layer._as_legend_item()))
        else:
            raise TypeError(f"Expected a list of layer or str, got {type(layer)}.")
    self._canvas()._plt_make_legend(items, location)

add_line(*args, name=None, color=None, width=None, style=None, alpha=1.0, antialias=True)

Add a Line layer to the canvas.

canvas.add_line(y, ...) canvas.add_line(x, y, ...)

Parameters:

Name	Type	Description	Default
name	str	Name of the layer.	None
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	None
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
Line	The line layer.

Source code in whitecanvas\canvas\_base.py

def add_line(
    self,
    *args,
    name=None,
    color=None,
    width=None,
    style=None,
    alpha=1.0,
    antialias=True,
):
    """
    Add a Line layer to the canvas.

    >>> canvas.add_line(y, ...)
    >>> canvas.add_line(x, y, ...)

    Parameters
    ----------
    name : str, optional
        Name of the layer.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    Line
        The line layer.
    """
    xdata, ydata = normalize_xy(*args)
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)
    layer = _l.Line(
        xdata, ydata, name=name, color=color, width=width, style=style,
        alpha=alpha, antialias=antialias, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_markers(*args, name=None, symbol=None, size=None, color=None, alpha=1.0, hatch=None)

Add markers (scatter plot).

canvas.add_markers(x, y) # standard usage canvas.add_markers(y) # use 0, 1, ... for the x values

Parameters:

Name	Type	Description	Default
name	str	Name of the layer.	None
symbol	str or Symbol	Marker symbols. Use the theme default if not specified.	None
size	float	Marker size. Use the theme default if not specified.	None
color	color - like	Color of the marker faces.	None
alpha	float	Alpha channel of the marker faces.	1.0
hatch	str or FacePattern	Pattern of the marker faces. Use the theme default if not specified.	None

Returns:

Type	Description
Markers	The markers layer.

Source code in whitecanvas\canvas\_base.py

def add_markers(
    self,
    *args,
    name=None,
    symbol=None,
    size=None,
    color=None,
    alpha=1.0,
    hatch=None,
):
    """
    Add markers (scatter plot).

    >>> canvas.add_markers(x, y)  # standard usage
    >>> canvas.add_markers(y)  # use 0, 1, ... for the x values

    Parameters
    ----------
    name : str, optional
        Name of the layer.
    symbol : str or Symbol, optional
        Marker symbols. Use the theme default if not specified.
    size : float, optional
        Marker size. Use the theme default if not specified.
    color : color-like, optional
        Color of the marker faces.
    alpha : float, default 1.0
        Alpha channel of the marker faces.
    hatch : str or FacePattern, optional
        Pattern of the marker faces. Use the theme default if not specified.

    Returns
    -------
    Markers
        The markers layer.
    """
    xdata, ydata = normalize_xy(*args)
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    symbol = theme._default("markers.symbol", symbol)
    size = theme._default("markers.size", size)
    hatch = theme._default("markers.hatch", hatch)
    layer = _l.Markers(
        xdata, ydata, name=name, symbol=symbol, size=size, color=color,
        alpha=alpha, hatch=hatch, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_rug(events, *, low=0.0, high=1.0, name=None, orient='vertical', color='black', width=1.0, style=LineStyle.SOLID, antialias=True, alpha=1.0)

Add input data as a rug plot.

canvas.add_rug([2, 4, 5, 8, 11])

  │ ││  │   │
──┴─┴┴──┴───┴──> x
  2 45  8   11

Parameters:

Name	Type	Description	Default
events	array - like	A 1D array of events.	required
low	float	The lower bound of the rug lines.	0.0
high	float	The upper bound of the rug lines.	1.0
name	str	Name of the layer.	None
orient	str or Orientation	Orientation of the errorbars. If vertical, rug lines will be parallel to the y axis.	"vertical"
color	color - like	Color of the bars.	'black'
width	float	Line width.	1.0
style	str or LineStyle	Line style.	LineStyle.SOLID
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
Rug	The rug layer.

Source code in whitecanvas\canvas\_base.py

def add_rug(
    self,
    events: ArrayLike1D,
    *,
    low: float = 0.0,
    high: float = 1.0,
    name: str | None = None,
    orient: OrientationLike = "vertical",
    color: ColorType = "black",
    width: float = 1.0,
    style: LineStyle | str = LineStyle.SOLID,
    antialias: bool = True,
    alpha: float = 1.0,
) -> _l.Rug:
    """
    Add input data as a rug plot.

    >>> canvas.add_rug([2, 4, 5, 8, 11])

    ```
      │ ││  │   │
    ──┴─┴┴──┴───┴──> x
      2 45  8   11
    ```

    Parameters
    ----------
    events : array-like
        A 1D array of events.
    low : float, default 0.0
        The lower bound of the rug lines.
    high : float, default 1.0
        The upper bound of the rug lines.
    name : str, optional
        Name of the layer.
    orient : str or Orientation, default "vertical"
        Orientation of the errorbars. If vertical, rug lines will be parallel
        to the y axis.
    color : color-like, optional
        Color of the bars.
    width : float, default 1.0
        Line width.
    style : str or LineStyle, default LineStyle.SOLID
        Line style.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    Rug
        The rug layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    layer = _l.Rug(
        events, low=low, high=high, name=name, color=color, alpha=alpha,
        width=width, style=style, antialias=antialias, orient=orient,
        backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_spans(spans, *, name=None, orient='vertical', color='blue', alpha=0.4, hatch=Hatch.SOLID)

Add spans that extends infinitely.

canvas.add_spans([[5, 10], [15, 20]])

::::		::::
───5────10────15───20─────>
::::		::::
::::		::::

Parameters:

Name	Type	Description	Default
spans	(N, 2) array-like	Array that contains the start and end points of the spans.	required
name	str	Name of the layer.	None
orient	str or Orientation	Orientation of the bars.	"vertical"
color	color - like	Color of the bars.	'blue'
alpha	float	Alpha channel of the bars.	0.4
hatch	str or FacePattern	Pattern of the bar faces.	FacePattern.SOLID

Returns:

Type	Description
Spans	The spans layer.

Source code in whitecanvas\canvas\_base.py

def add_spans(
    self,
    spans: ArrayLike,
    *,
    name: str | None = None,
    orient: OrientationLike = "vertical",
    color: ColorType = "blue",
    alpha: float = 0.4,
    hatch: str | Hatch = Hatch.SOLID,
) -> _l.Spans:
    """
    Add spans that extends infinitely.

    >>> canvas.add_spans([[5, 10], [15, 20]])

       |::::|     |::::|
       |::::|     |::::|
    ───5────10────15───20─────>
       |::::|     |::::|
       |::::|     |::::|

    Parameters
    ----------
    spans : (N, 2) array-like
        Array that contains the start and end points of the spans.
    name : str, optional
        Name of the layer.
    orient : str or Orientation, default "vertical"
        Orientation of the bars.
    color : color-like, optional
        Color of the bars.
    alpha : float, default 0.4
        Alpha channel of the bars.
    hatch : str or FacePattern, default FacePattern.SOLID
        Pattern of the bar faces.

    Returns
    -------
    Spans
        The spans layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    layer = _l.Spans(
        spans, name=name, orient=orient, color=color, alpha=alpha,
        hatch=hatch, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_text(x, y, string, *, color='black', size=12, rotation=0.0, anchor=Alignment.BOTTOM_LEFT, family=None)

Add a text layer to the canvas.

canvas.add_text([0, 0], [1, 1], ["text-0", "text-1]) canvas.add_text(...).with_face(color="red") # with background canvas.add_text(...).with_edge(color="red") # with outline

Parameters:

Name	Type	Description	Default
x	float or array - like	X position(s) of the text.	required
y	float or array - like	Y position(s) of the text.	required
string	str or list[str]	Text string to display.	required
color	ColorType	Color of the text string.	'black'
size	float	Point size of the text.	12
rotation	float	Rotation angle of the text in degrees.	0.0
anchor	str or Alignment	Anchor position of the text. The anchor position will be the coordinate given by (x, y).	Alignment.BOTTOM_LEFT
family	str	Font family of the text.	None

Returns:

Type	Description
Texts	The text layer.

Source code in whitecanvas\canvas\_base.py

def add_text(
    self,
    x,
    y,
    string,
    *,
    color="black",
    size=12,
    rotation=0.0,
    anchor=Alignment.BOTTOM_LEFT,
    family=None,
):
    """
    Add a text layer to the canvas.

    >>> canvas.add_text([0, 0], [1, 1], ["text-0", "text-1])
    >>> canvas.add_text(...).with_face(color="red")  # with background
    >>> canvas.add_text(...).with_edge(color="red")  # with outline

    Parameters
    ----------
    x : float or array-like
        X position(s) of the text.
    y : float or array-like
        Y position(s) of the text.
    string : str or list[str]
        Text string to display.
    color : ColorType, optional
        Color of the text string.
    size : float, default 12
        Point size of the text.
    rotation : float, default 0.0
        Rotation angle of the text in degrees.
    anchor : str or Alignment, default Alignment.BOTTOM_LEFT
        Anchor position of the text. The anchor position will be the coordinate
        given by (x, y).
    family : str, optional
        Font family of the text.

    Returns
    -------
    Texts
        The text layer.
    """
    if is_real_number(x) and is_real_number(y) and isinstance(string, str):
        x, y, string = [x], [y], [string]
    x_, y_ = normalize_xy(x, y)
    if isinstance(string, str):
        string = [string] * x_.size
    elif len(string) != x_.size:
        raise ValueError("Expected string to have the same size as x/y")
    layer = _l.Texts(
        x_, y_, string, color=color, size=size, rotation=rotation, anchor=anchor,
        family=family, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_vectors(x, y, vx, vy, *, name=None, color=None, width=None, style=None, alpha=1.0, antialias=True)

Add a vector field to the canvas.

canvas.add_vectors(x, y, vx, vy)

Parameters:

Name	Type	Description	Default
x	array - like	X coordinates of the vectors.	required
y	array - like	Y coordinates of the vectors.	required
vx	array - like	X components of the vectors.	required
vy	array - like	Y components of the vectors.	required
name	str	Name of the layer.	None
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	None
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
Vectors	The vectors layer.

Source code in whitecanvas\canvas\_base.py

def add_vectors(
    self,
    x: ArrayLike1D,
    y: ArrayLike1D,
    vx: ArrayLike1D,
    vy: ArrayLike1D,
    *,
    name: str | None = None,
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str | None = None,
    alpha: float = 1.0,
    antialias: bool = True,
) -> _l.Vectors:
    """
    Add a vector field to the canvas.

    >>> canvas.add_vectors(x, y, vx, vy)

    Parameters
    ----------
    x : array-like
        X coordinates of the vectors.
    y : array-like
        Y coordinates of the vectors.
    vx : array-like
        X components of the vectors.
    vy : array-like
        Y components of the vectors.
    name : str, optional
        Name of the layer.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    Vectors
        The vectors layer.
    """
    name = self._coerce_name(name)
    color = self._generate_colors(color)
    width = theme._default("line.width", width)
    style = theme._default("line.style", style)
    layer = _l.Vectors(
        as_array_1d(x, dtype=np.float32), as_array_1d(y, dtype=np.float32),
        as_array_1d(vx, dtype=np.float32), as_array_1d(vy, dtype=np.float32),
        name=name, color=color, width=width, style=style,
        alpha=alpha, antialias=antialias, backend=self._get_backend(),
    )  # fmt: skip
    return self.add_layer(layer)

add_vline(x, *, name=None, color=None, width=None, style=LineStyle.SOLID, alpha=1.0, antialias=True)

Add a infinite vertical line to the canvas.

Parameters:

Name	Type	Description	Default
x	float	X coordinate of the line.	required
name	str	Name of the layer.	None
color	color - like	Color of the bars.	None
width	float	Line width. Use the theme default if not specified.	None
style	str or LineStyle	Line style. Use the theme default if not specified.	SOLID
alpha	float	Alpha channel of the line.	1.0
antialias	bool	Antialiasing of the line.	True

Returns:

Type	Description
InfLine	The infline layer.

Source code in whitecanvas\canvas\_base.py

def add_vline(
    self,
    x: float,
    *,
    name: str | None = None,
    color: ColorType | None = None,
    width: float | None = None,
    style: LineStyle | str = LineStyle.SOLID,
    alpha: float = 1.0,
    antialias: bool = True,
) -> _l.InfLine:
    """
    Add a infinite vertical line to the canvas.

    Parameters
    ----------
    x : float
        X coordinate of the line.
    name : str, optional
        Name of the layer.
    color : color-like, optional
        Color of the bars.
    width : float, optional
        Line width. Use the theme default if not specified.
    style : str or LineStyle, optional
        Line style. Use the theme default if not specified.
    alpha : float, default 1.0
        Alpha channel of the line.
    antialias : bool, default True
        Antialiasing of the line.

    Returns
    -------
    InfLine
        The infline layer.
    """
    return self.add_infline(
        (x, 0), 90, name=name, color=color, width=width, style=style, alpha=alpha,
        antialias=antialias,
    )  # fmt: skip

autoscale(xpad=None, ypad=None)

Autoscale the canvas to fit the contents.

Parameters:

Name	Type	Description	Default
xpad	float or (float, float)	Padding in the x direction.	None
ypad	float or (float, float)	Padding in the y direction.	None

Source code in whitecanvas\canvas\_base.py

def autoscale(
    self,
    xpad: float | tuple[float, float] | None = None,
    ypad: float | tuple[float, float] | None = None,
) -> tuple[float, float, float, float]:
    """
    Autoscale the canvas to fit the contents.

    Parameters
    ----------
    xpad : float or (float, float), optional
        Padding in the x direction.
    ypad : float or (float, float), optional
        Padding in the y direction.
    """
    ar = np.stack([layer.bbox_hint() for layer in self.layers], axis=0)
    xmin = np.min(ar[:, 0])
    xmax = np.max(ar[:, 1])
    ymin = np.min(ar[:, 2])
    ymax = np.max(ar[:, 3])
    x0, x1 = self.x.lim
    y0, y1 = self.y.lim
    if np.isnan(xmin):
        xmin = x0
    if np.isnan(xmax):
        xmax = x1
    if np.isnan(ymin):
        ymin = y0
    if np.isnan(ymax):
        ymax = y1
    if xpad is not None:
        xrange = xmax - xmin
        if is_real_number(xpad):
            dx0 = dx1 = xpad * xrange
        else:
            dx0, dx1 = xpad[0] * xrange, xpad[1] * xrange
        xmin -= dx0
        xmax += dx1
    if ypad is not None:
        yrange = ymax - ymin
        if is_real_number(ypad):
            dy0 = dy1 = ypad * yrange
        else:
            dy0, dy1 = ypad[0] * yrange, ypad[1] * yrange
        ymin -= dy0
        ymax += dy1
    small_diff = 1e-6
    if xmax - xmin < small_diff:
        xmin -= 0.05
        xmax += 0.05
    if ymax - ymin < small_diff:
        ymin -= 0.05
        ymax += 0.05
    self.x.lim = xmin, xmax
    self.y.lim = ymin, ymax
    return xmin, xmax, ymin, ymax

cat(data, x=None, y=None, *, update_labels=True)

Categorize input data for plotting.

This method provides categorical plotting methods for the input data. Methods are very similar to seaborn and plotly.express.

Parameters:

Name	Type	Description	Default
data	tabular data	Any categorizable data. Currently, dict, pandas.DataFrame, and polars.DataFrame are supported.	required
x	str	Name of the column that will be used for the x-axis. Must be numerical.	None
y	str	Name of the column that will be used for the y-axis. Must be numerical.	None
update_labels	bool	If True, update the x/y labels to the corresponding names.	True

Returns:

Type	Description
CatPlotter	Plotter object.

Source code in whitecanvas\canvas\_base.py

def cat(
    self,
    data: _DF,
    x: str | None = None,
    y: str | None = None,
    *,
    update_labels: bool = True,
) -> _df.CatPlotter[Self, _DF]:
    """
    Categorize input data for plotting.

    This method provides categorical plotting methods for the input data.
    Methods are very similar to `seaborn` and `plotly.express`.

    Parameters
    ----------
    data : tabular data
        Any categorizable data. Currently, dict, pandas.DataFrame, and
        polars.DataFrame are supported.
    x : str, optional
        Name of the column that will be used for the x-axis. Must be numerical.
    y : str, optional
        Name of the column that will be used for the y-axis. Must be numerical.
    update_labels : bool, default True
        If True, update the x/y labels to the corresponding names.

    Returns
    -------
    CatPlotter
        Plotter object.
    """
    plotter = _df.CatPlotter(self, data, x, y, update_labels=update_labels)
    return plotter

cat_x(data, x=None, y=None, *, update_labels=True, numeric_axis=False)

Categorize input data for plotting with x-axis as a categorical axis.

Parameters:

Name	Type	Description	Default
data	tabular data	Any categorizable data. Currently, dict, pandas.DataFrame, and polars.DataFrame are supported.	required
x	str or sequence of str	Name of the column(s) that will be used for the x-axis. Must be categorical.	None
y	str	Name of the column that will be used for the y-axis. Must be numerical.	None
update_labels	bool	If True, update the x/y labels to the corresponding names.	True
numeric_axis	bool	If True, the x-axis will be treated as a numerical axis. For example, if categories are [2, 4, 8], the x coordinates will be mapped to [0, 1, 2] by default, but if this option is True, the x coordinates will be [2, 4, 8].	False

Returns:

Type	Description
XCatPlotter	Plotter object.

Source code in whitecanvas\canvas\_base.py

def cat_x(
    self,
    data: _DF,
    x: str | Sequence[str] | None = None,
    y: str | None = None,
    *,
    update_labels: bool = True,
    numeric_axis: bool = False,
) -> _df.XCatPlotter[Self, _DF]:
    """
    Categorize input data for plotting with x-axis as a categorical axis.

    Parameters
    ----------
    data : tabular data
        Any categorizable data. Currently, dict, pandas.DataFrame, and
        polars.DataFrame are supported.
    x : str or sequence of str, optional
        Name of the column(s) that will be used for the x-axis. Must be categorical.
    y : str, optional
        Name of the column that will be used for the y-axis. Must be numerical.
    update_labels : bool, default True
        If True, update the x/y labels to the corresponding names.
    numeric_axis : bool, default False
        If True, the x-axis will be treated as a numerical axis. For example, if
        categories are [2, 4, 8], the x coordinates will be mapped to [0, 1, 2] by
        default, but if this option is True, the x coordinates will be [2, 4, 8].

    Returns
    -------
    XCatPlotter
        Plotter object.
    """
    return _df.XCatPlotter(self, data, x, y, update_labels, numeric=numeric_axis)

cat_xy(data, x, y, *, update_labels=True)

Categorize input data for plotting with both axes as categorical.

Parameters:

Name	Type	Description	Default
data	tabular data	Any categorizable data. Currently, dict, pandas.DataFrame, and polars.DataFrame are supported.	required
x	str or sequence of str	Name of the column(s) that will be used for the x-axis. Must be categorical.	required
y	str or sequence of str	Name of the column(s) that will be used for the y-axis. Must be categorical.	required
update_labels	bool	If True, update the x/y labels to the corresponding names.	True

Returns:

Type	Description
XYCatPlotter	Plotter object

Source code in whitecanvas\canvas\_base.py

def cat_xy(
    self,
    data: _DF,
    x: str | Sequence[str],
    y: str | Sequence[str],
    *,
    update_labels: bool = True,
) -> _df.XYCatPlotter[Self, _DF]:
    """
    Categorize input data for plotting with both axes as categorical.

    Parameters
    ----------
    data : tabular data
        Any categorizable data. Currently, dict, pandas.DataFrame, and
        polars.DataFrame are supported.
    x : str or sequence of str, optional
        Name of the column(s) that will be used for the x-axis. Must be categorical.
    y : str or sequence of str, optional
        Name of the column(s) that will be used for the y-axis. Must be categorical.
    update_labels : bool, default True
        If True, update the x/y labels to the corresponding names.

    Returns
    -------
    XYCatPlotter
        Plotter object
    """
    return _df.XYCatPlotter(self, data, x, y, update_labels)

cat_y(data, x=None, y=None, *, update_labels=True, numeric_axis=False)

Categorize input data for plotting with y-axis as a categorical axis.

Parameters:

Name	Type	Description	Default
data	tabular data	Any categorizable data. Currently, dict, pandas.DataFrame, and polars.DataFrame are supported.	required
x	str	Name of the column that will be used for the x-axis. Must be numerical.	None
y	str or sequence of str	Name of the column(s) that will be used for the y-axis. Must be categorical.	None
update_labels	bool	If True, update the x/y labels to the corresponding names.	True
numeric_axis	bool	If True, the x-axis will be treated as a numerical axis. For example, if categories are [2, 4, 8], the y coordinates will be mapped to [0, 1, 2] by default, but if this option is True, the y coordinates will be [2, 4, 8].	False

Returns:

Type	Description
YCatPlotter	Plotter object

Source code in whitecanvas\canvas\_base.py

def cat_y(
    self,
    data: _DF,
    x: str | None = None,
    y: str | Sequence[str] | None = None,
    *,
    update_labels: bool = True,
    numeric_axis: bool = False,
) -> _df.YCatPlotter[Self, _DF]:
    """
    Categorize input data for plotting with y-axis as a categorical axis.

    Parameters
    ----------
    data : tabular data
        Any categorizable data. Currently, dict, pandas.DataFrame, and
        polars.DataFrame are supported.
    x : str, optional
        Name of the column that will be used for the x-axis. Must be numerical.
    y : str or sequence of str, optional
        Name of the column(s) that will be used for the y-axis. Must be categorical.
    update_labels : bool, default True
        If True, update the x/y labels to the corresponding names.
    numeric_axis : bool, default False
        If True, the x-axis will be treated as a numerical axis. For example, if
        categories are [2, 4, 8], the y coordinates will be mapped to [0, 1, 2] by
        default, but if this option is True, the y coordinates will be [2, 4, 8].

    Returns
    -------
    YCatPlotter
        Plotter object
    """
    return _df.YCatPlotter(self, data, y, x, update_labels, numeric=numeric_axis)

fit(layer)

The fit plotter namespace.

Source code in whitecanvas\canvas\_base.py

def fit(self, layer: _l.DataBoundLayer[_P]) -> FitPlotter[Self, _P]:
    """The fit plotter namespace."""
    return FitPlotter(self, layer)

group_layers(layers, *more_layers, name=None)

Group layers.

Parameters:

Name	Type	Description	Default
layers	iterable of Layer	Layers to group.	required

Returns:

Type	Description
LayerGroup	The grouped layer.

Source code in whitecanvas\canvas\_base.py

def group_layers(self, layers, *more_layers, name=None):
    """
    Group layers.

    Parameters
    ----------
    layers : iterable of Layer
        Layers to group.

    Returns
    -------
    LayerGroup
        The grouped layer.
    """
    if more_layers:
        if not isinstance(layers, _l.Layer):
            raise TypeError("No overload matches the arguments")
        layers = [layers, *more_layers]
    return _lg.LayerTuple(layers, name=name)

imref(layer)

The Image reference namespace.

Source code in whitecanvas\canvas\_base.py

@deprecated(
    "ImageRef is deprecated and will be removed in the future. "
    "Please use the Image methods `with_text`, `with_colorbar` instead.",
)
def imref(self, layer: _l.Image):
    """The Image reference namespace."""
    from whitecanvas.canvas._imageref import ImageRef

    while isinstance(layer, _l.LayerWrapper):
        layer = layer._base_layer
    if not isinstance(layer, _l.Image):
        raise TypeError(
            f"Expected an Image layer or its wrapper, got {type(layer)}."
        )
    return ImageRef(self, layer)

install_inset(*args, palette=None, **kwargs)

Install a new canvas pointing to an inset of the current canvas.

canvas.install_inset(left=0.1, right=0.9, bottom=0.1, top=0.9) canvas.install_inset([0.1, 0.9, 0.1, 0.9]) # or a sequence

Source code in whitecanvas\canvas\_base.py

def install_inset(self, *args, palette=None, **kwargs) -> Canvas:
    """
    Install a new canvas pointing to an inset of the current canvas.

    >>> canvas.install_inset(left=0.1, right=0.9, bottom=0.1, top=0.9)
    >>> canvas.install_inset([0.1, 0.9, 0.1, 0.9])  # or a sequence
    """
    # normalize input
    if len(args) == 1 and not kwargs:
        rect = args[0]
        if not isinstance(rect, Rect):
            rect = Rect.with_check(*rect)
    else:
        rect = Rect.with_check(*args, **kwargs)
    try:
        new = self._canvas()._plt_inset(rect)
    except AttributeError:
        raise NotImplementedError(
            f"Backend {self._get_backend()} does not support `install_inset`"
        ) from None
    canvas = Canvas.from_backend(new, palette=palette, backend=self._get_backend())
    canvas._init_canvas()
    return canvas

install_second_x(*, palette=None)

Create a twin canvas that has a secondary x-axis and shared y-axis.

Source code in whitecanvas\canvas\_base.py

def install_second_x(self, *, palette: ColormapType | None = None) -> Canvas:
    """Create a twin canvas that has a secondary x-axis and shared y-axis."""
    try:
        new = self._canvas()._plt_twiny()
    except AttributeError:
        raise NotImplementedError(
            f"Backend {self._get_backend()} does not support `install_second_x`."
        ) from None
    canvas = Canvas.from_backend(new, palette=palette, backend=self._get_backend())
    canvas._init_canvas()
    return canvas

install_second_y(*, palette=None)

Create a twin canvas that has a secondary y-axis and shared x-axis.

Source code in whitecanvas\canvas\_base.py

def install_second_y(self, *, palette: ColormapType | None = None) -> Canvas:
    """Create a twin canvas that has a secondary y-axis and shared x-axis."""
    try:
        new = self._canvas()._plt_twinx()
    except AttributeError:
        raise NotImplementedError(
            f"Backend {self._get_backend()} does not support `install_second_y`."
        ) from None
    canvas = Canvas.from_backend(new, palette=palette, backend=self._get_backend())
    canvas._init_canvas()
    return canvas

stack_over(layer)

Stack new data over the existing layer.

For example following code

bars_0 = canvas.add_bars(x, y0) bars_1 = canvas.stack_over(bars_0).add(y1) bars_2 = canvas.stack_over(bars_1).add(y2)

will result in a bar plot like this

 ┌───┐
 ├───│┌───┐
 │   │├───│
 ├───│├───│
─┴───┴┴───┴─

Source code in whitecanvas\canvas\_base.py

def stack_over(self, layer: _L0) -> StackOverPlotter[Self, _L0]:
    """
    Stack new data over the existing layer.

    For example following code

    >>> bars_0 = canvas.add_bars(x, y0)
    >>> bars_1 = canvas.stack_over(bars_0).add(y1)
    >>> bars_2 = canvas.stack_over(bars_1).add(y2)

    will result in a bar plot like this

    ```
     ┌───┐
     ├───│┌───┐
     │   │├───│
     ├───│├───│
    ─┴───┴┴───┴─
    ```
    """
    if not isinstance(layer, (_l.Bars, _l.Band, _lg.StemPlot, _lg.LabeledBars)):
        raise TypeError(
            f"Only Bars, StemPlot and Band are supported as an input, "
            f"got {type(layer)!r}."
        )
    return StackOverPlotter(self, layer)

update_axes(*, visible=None, color=None)

Update axes appearance.

Parameters:

Name	Type	Description	Default
visible	bool	Whether to show the axes.	None
color	color - like	Color of the axes.	None

Source code in whitecanvas\canvas\_base.py

def update_axes(
    self,
    *,
    visible: bool | None = None,
    color: ColorType | None = None,
):
    """
    Update axes appearance.

    Parameters
    ----------
    visible : bool, optional
        Whether to show the axes.
    color : color-like, optional
        Color of the axes.
    """
    if visible is not None:
        self.x.ticks.visible = self.y.ticks.visible = visible
    if color is not None:
        self.x.color = self.y.color = color
        self.x.ticks.color = self.y.ticks.color = color
        self.x.label.color = self.y.label.color = color
    return self

update_font(size=None, color=None, family=None)

Update all the fonts, including the title, x/y labels and x/y tick labels.

Parameters:

Name	Type	Description	Default
size	float	New font size.	None
color	color - like	New font color.	None
family	str	New font family.	None

Source code in whitecanvas\canvas\_base.py

def update_font(
    self,
    size: float | None = None,
    color: ColorType | None = None,
    family: str | None = None,
) -> Self:
    """
    Update all the fonts, including the title, x/y labels and x/y tick labels.

    Parameters
    ----------
    size : float, optional
        New font size.
    color : color-like, optional
        New font color.
    family : str, optional
        New font family.
    """
    if size is not None:
        self.title.size = self.x.label.size = self.y.label.size = size
        self.x.ticks.size = self.y.ticks.size = size
    if family is not None:
        self.title.family = self.x.label.family = self.y.label.family = family
        self.x.ticks.family = self.y.ticks.family = family
    if color is not None:
        self.title.color = self.x.label.color = self.y.label.color = color
        self.x.ticks.color = self.y.ticks.color = color
    return self

update_labels(title=None, x=None, y=None)

Helper function to update the title, x, and y labels.

from whitecanvas import new_canvas canvas = new_canvas("matplotlib").update_labels("Title", "X", "Y")

Source code in whitecanvas\canvas\_base.py

def update_labels(
    self,
    title: str | None = None,
    x: str | None = None,
    y: str | None = None,
) -> Self:
    """
    Helper function to update the title, x, and y labels.

    >>> from whitecanvas import new_canvas
    >>> canvas = new_canvas("matplotlib").update_labels("Title", "X", "Y")
    """
    if title is not None:
        self.title.text = title
        self.title.visible = True
    if x is not None:
        self.x.label.text = x
        self.x.label.visible = True
    if y is not None:
        self.y.label.text = y
        self.y.label.visible = True
    return self

CanvasGrid

Source code in whitecanvas\canvas\_grid.py

class CanvasGrid:
    _CURRENT_INSTANCE: CanvasGrid | None = None
    events: GridEvents

    def __init__(
        self,
        heights: list[int],
        widths: list[int],
        *,
        backend: Backend | str | None = None,
    ) -> None:
        self._heights = heights
        self._widths = widths
        self._backend = Backend(backend)
        self._backend_object = self._create_backend()
        self._canvas_array = np.empty((len(heights), len(widths)), dtype=object)
        self._canvas_array.fill(None)

        # link axes
        self._x_linked = False
        self._y_linked = False
        self._x_linker_ref = None
        self._y_linker_ref = None

        # update settings
        theme = get_theme()
        self.background_color = theme.background_color
        self.size = theme.canvas_size
        self.events = GridEvents()
        self.__class__._CURRENT_INSTANCE = self

    @property
    def shape(self) -> tuple[int, int]:
        """The (row, col) shape of the grid"""
        return self._canvas_array.shape

    def link_x(self, *, future: bool = True, hide_ticks: bool = True) -> Self:
        """
        Link all the x-axes of the canvases in the grid.

        >>> from whitecanvas import new_grid
        >>> g = new_grid(2, 2).link_x()  # link x-axes of all canvases

        Parameters
        ----------
        future : bool, default True
            If Ture, all the canvases added in the future will also be linked. Only link
            the existing canvases if False.
        """
        if self._x_linker_ref is not None:
            self._x_linker_ref.unlink_all()  # initialize linker
        to_link = []
        for (_r, _), _canvas in self._iter_canvas():
            to_link.append(_canvas.x)
            if hide_ticks and _r != self.shape[0] - 1:
                _canvas.x.ticks.visible = False
        self._x_linker_ref = link_axes(to_link)
        if future:
            self._x_linked = True
            if hide_ticks:
                self._backend_object._plt_set_spacings(6, 6)
        return self

    def link_y(self, *, future: bool = True, hide_ticks: bool = True) -> Self:
        """
        Link all the y-axes of the canvases in the grid.

        >>> from whitecanvas import new_grid
        >>> g = new_grid(2, 2).link_y()  # link y-axes of all canvases

        Parameters
        ----------
        future : bool, default True
            If Ture, all the canvases added in the future will also be linked. Only link
            the existing canvases if False.
        """
        if self._y_linker_ref is not None:
            self._y_linker_ref.unlink_all()
        to_link = []
        for (_, _c), _canvas in self._iter_canvas():
            to_link.append(_canvas.y)
            if hide_ticks and _c != 0:
                _canvas.y.ticks.visible = False
        self._y_linker_ref = link_axes(to_link)
        if future:
            self._y_linked = True
            if hide_ticks:
                self._backend_object._plt_set_spacings(6, 6)
        return self

    def __repr__(self) -> str:
        cname = type(self).__name__
        w, h = self._size
        hex_id = hex(id(self))
        return f"<{cname} ({w:.1f} x {h:.1f}) at {hex_id}>"

    def __getitem__(self, key: tuple[int, int]) -> Canvas:
        canvas = self._canvas_array[key]
        if canvas is None:
            raise ValueError(f"Canvas at {key} is not set")
        elif isinstance(canvas, np.ndarray):
            raise ValueError(f"Cannot index by {key}.")
        return canvas

    def _create_backend(self) -> protocols.CanvasGridProtocol:
        return self._backend.get("CanvasGrid")(
            self._heights, self._widths, self._backend._app
        )

    def fill(self, palette: ColormapType | None = None) -> Self:
        """Fill the grid with canvases."""
        for _ in self._iter_add_canvas(palette=palette):
            pass
        return self

    def add_canvas(
        self,
        row: int,
        col: int,
        rowspan: int = 1,
        colspan: int = 1,
        *,
        palette: str | None = None,
    ) -> Canvas:
        """Add a canvas to the grid at the given position"""
        for idx, item in np.ndenumerate(self._canvas_array[row, col]):
            if item is not None:
                raise ValueError(f"Canvas already exists at {idx}")
        backend_canvas = self._backend_object._plt_add_canvas(
            row, col, rowspan, colspan
        )
        canvas = self._canvas_array[row, col] = Canvas.from_backend(
            backend_canvas,
            backend=self._backend,
            palette=palette,
        )
        # Now backend axes/viewbox are created, we can install mouse events
        canvas._install_mouse_events()

        # link axes if needed
        if self._x_linked:
            self._x_linker_ref.link(canvas.x)
        if self._y_linked:
            self._y_linker_ref.link(canvas.y)
        canvas.events.drawn.connect(self.events.drawn.emit, unique=True, max_args=None)
        return canvas

    def add_canvas_3d(
        self,
        row: int,
        col: int,
        rowspan: int = 1,
        colspan: int = 1,
        *,
        palette: str | None = None,
    ):
        """Add a canvas to the grid at the given position"""
        from whitecanvas.canvas.canvas3d._base import Canvas3D

        for idx, item in np.ndenumerate(self._canvas_array[row, col]):
            if item is not None:
                raise ValueError(f"Canvas already exists at {idx}")
        backend_canvas = self._backend_object._plt_add_canvas_3d(
            row, col, rowspan, colspan
        )
        canvas = self._canvas_array[row, col] = Canvas3D.from_backend(
            backend_canvas,
            backend=self._backend,
            palette=palette,
        )
        # Now backend axes/viewbox are created, we can install mouse events
        # canvas._install_mouse_events()

        # link axes if needed
        if self._x_linked:
            self._x_linker_ref.link(canvas.x)
        if self._y_linked:
            self._y_linker_ref.link(canvas.y)
        canvas.events.drawn.connect(self.events.drawn.emit, unique=True, max_args=None)
        return canvas

    def _iter_add_canvas(self, **kwargs) -> Iterator[Canvas]:
        for row in range(len(self._heights)):
            for col in range(len(self._widths)):
                yield self.add_canvas(row, col, **kwargs)

    def _iter_canvas(self) -> Iterator[tuple[tuple[int, int], Canvas]]:
        yielded: set[int] = set()
        for idx, canvas in np.ndenumerate(self._canvas_array):
            _id = id(canvas)
            if canvas is None or _id in yielded:
                continue
            yield idx, canvas
            yielded.add(_id)

    def show(self, block=False) -> None:
        """Show the grid."""
        from whitecanvas.backend._app import get_app

        # TODO: implement other event loops
        app = get_app(self._backend._app)
        _backend_app = app.get_app()
        out = self._backend_object._plt_show()

        if out is NotImplemented:
            from whitecanvas.backend._window import view

            view(self, self._backend.app)

        if block:
            # TODO: automatically block the event loop or enable ipython
            # GUI mode if needed.
            app.run_app()

    @property
    def background_color(self) -> NDArray[np.floating]:
        """Background color of the canvas."""
        return arr_color(self._backend_object._plt_get_background_color())

    @background_color.setter
    def background_color(self, color):
        self._backend_object._plt_set_background_color(arr_color(color))

    def screenshot(self) -> NDArray[np.uint8]:
        """Return a screenshot of the grid."""
        return self._backend_object._plt_screenshot()

    @property
    def size(self) -> tuple[int, int]:
        """Size in width x height."""
        return self._size

    @size.setter
    def size(self, size: tuple[int, int]):
        w, h = size
        if w <= 0 or h <= 0:
            raise ValueError("Size must be positive")
        self._size = (int(w), int(h))
        self._backend_object._plt_set_figsize(*self._size)

    def _repr_png_(self):
        """Return PNG representation of the widget for QtConsole."""
        from io import BytesIO

        try:
            from imageio import imwrite
        except ImportError:
            return None

        rendered = self.screenshot()
        if rendered is not None:
            with BytesIO() as file_obj:
                imwrite(file_obj, rendered, format="png")
                file_obj.seek(0)
                return file_obj.read()
        return None

    def _ipython_display_(self, *args: Any, **kwargs: Any) -> Any:
        if hasattr(self._backend_object, "_ipython_display_"):
            return self._backend_object._ipython_display_(*args, **kwargs)
        raise NotImplementedError()

    def _repr_mimebundle_(self, *args: Any, **kwargs: Any) -> dict:
        if hasattr(self._backend_object, "_repr_mimebundle_"):
            return self._backend_object._repr_mimebundle_(*args, **kwargs)
        raise NotImplementedError()

    def _repr_html_(self, *args: Any, **kwargs: Any) -> str:
        if hasattr(self._backend_object, "_repr_html_"):
            return self._backend_object._repr_html_(*args, **kwargs)
        raise NotImplementedError()

    def to_html(self, file: str | None = None) -> str:
        """Return HTML representation of the grid."""
        html = self._backend.get("to_html")(self._backend_object)
        if file is not None:
            Path(file).write_text(html, encoding="utf-8")
        return html

background_color: NDArray[np.floating] property writable

Background color of the canvas.

shape: tuple[int, int] property

The (row, col) shape of the grid

size: tuple[int, int] property writable

Size in width x height.

add_canvas(row, col, rowspan=1, colspan=1, *, palette=None)

Add a canvas to the grid at the given position

Source code in whitecanvas\canvas\_grid.py

def add_canvas(
    self,
    row: int,
    col: int,
    rowspan: int = 1,
    colspan: int = 1,
    *,
    palette: str | None = None,
) -> Canvas:
    """Add a canvas to the grid at the given position"""
    for idx, item in np.ndenumerate(self._canvas_array[row, col]):
        if item is not None:
            raise ValueError(f"Canvas already exists at {idx}")
    backend_canvas = self._backend_object._plt_add_canvas(
        row, col, rowspan, colspan
    )
    canvas = self._canvas_array[row, col] = Canvas.from_backend(
        backend_canvas,
        backend=self._backend,
        palette=palette,
    )
    # Now backend axes/viewbox are created, we can install mouse events
    canvas._install_mouse_events()

    # link axes if needed
    if self._x_linked:
        self._x_linker_ref.link(canvas.x)
    if self._y_linked:
        self._y_linker_ref.link(canvas.y)
    canvas.events.drawn.connect(self.events.drawn.emit, unique=True, max_args=None)
    return canvas

add_canvas_3d(row, col, rowspan=1, colspan=1, *, palette=None)

Add a canvas to the grid at the given position

Source code in whitecanvas\canvas\_grid.py

def add_canvas_3d(
    self,
    row: int,
    col: int,
    rowspan: int = 1,
    colspan: int = 1,
    *,
    palette: str | None = None,
):
    """Add a canvas to the grid at the given position"""
    from whitecanvas.canvas.canvas3d._base import Canvas3D

    for idx, item in np.ndenumerate(self._canvas_array[row, col]):
        if item is not None:
            raise ValueError(f"Canvas already exists at {idx}")
    backend_canvas = self._backend_object._plt_add_canvas_3d(
        row, col, rowspan, colspan
    )
    canvas = self._canvas_array[row, col] = Canvas3D.from_backend(
        backend_canvas,
        backend=self._backend,
        palette=palette,
    )
    # Now backend axes/viewbox are created, we can install mouse events
    # canvas._install_mouse_events()

    # link axes if needed
    if self._x_linked:
        self._x_linker_ref.link(canvas.x)
    if self._y_linked:
        self._y_linker_ref.link(canvas.y)
    canvas.events.drawn.connect(self.events.drawn.emit, unique=True, max_args=None)
    return canvas

fill(palette=None)

Fill the grid with canvases.

Source code in whitecanvas\canvas\_grid.py

def fill(self, palette: ColormapType | None = None) -> Self:
    """Fill the grid with canvases."""
    for _ in self._iter_add_canvas(palette=palette):
        pass
    return self

link_x(*, future=True, hide_ticks=True)

Link all the x-axes of the canvases in the grid.

from whitecanvas import new_grid g = new_grid(2, 2).link_x() # link x-axes of all canvases

Parameters:

Name	Type	Description	Default
future	bool	If Ture, all the canvases added in the future will also be linked. Only link the existing canvases if False.	True

Source code in whitecanvas\canvas\_grid.py

def link_x(self, *, future: bool = True, hide_ticks: bool = True) -> Self:
    """
    Link all the x-axes of the canvases in the grid.

    >>> from whitecanvas import new_grid
    >>> g = new_grid(2, 2).link_x()  # link x-axes of all canvases

    Parameters
    ----------
    future : bool, default True
        If Ture, all the canvases added in the future will also be linked. Only link
        the existing canvases if False.
    """
    if self._x_linker_ref is not None:
        self._x_linker_ref.unlink_all()  # initialize linker
    to_link = []
    for (_r, _), _canvas in self._iter_canvas():
        to_link.append(_canvas.x)
        if hide_ticks and _r != self.shape[0] - 1:
            _canvas.x.ticks.visible = False
    self._x_linker_ref = link_axes(to_link)
    if future:
        self._x_linked = True
        if hide_ticks:
            self._backend_object._plt_set_spacings(6, 6)
    return self

link_y(*, future=True, hide_ticks=True)

Link all the y-axes of the canvases in the grid.

from whitecanvas import new_grid g = new_grid(2, 2).link_y() # link y-axes of all canvases

Parameters:

Name	Type	Description	Default
future	bool	If Ture, all the canvases added in the future will also be linked. Only link the existing canvases if False.	True

Source code in whitecanvas\canvas\_grid.py

def link_y(self, *, future: bool = True, hide_ticks: bool = True) -> Self:
    """
    Link all the y-axes of the canvases in the grid.

    >>> from whitecanvas import new_grid
    >>> g = new_grid(2, 2).link_y()  # link y-axes of all canvases

    Parameters
    ----------
    future : bool, default True
        If Ture, all the canvases added in the future will also be linked. Only link
        the existing canvases if False.
    """
    if self._y_linker_ref is not None:
        self._y_linker_ref.unlink_all()
    to_link = []
    for (_, _c), _canvas in self._iter_canvas():
        to_link.append(_canvas.y)
        if hide_ticks and _c != 0:
            _canvas.y.ticks.visible = False
    self._y_linker_ref = link_axes(to_link)
    if future:
        self._y_linked = True
        if hide_ticks:
            self._backend_object._plt_set_spacings(6, 6)
    return self

screenshot()

Return a screenshot of the grid.

Source code in whitecanvas\canvas\_grid.py

def screenshot(self) -> NDArray[np.uint8]:
    """Return a screenshot of the grid."""
    return self._backend_object._plt_screenshot()

show(block=False)

Show the grid.

Source code in whitecanvas\canvas\_grid.py

def show(self, block=False) -> None:
    """Show the grid."""
    from whitecanvas.backend._app import get_app

    # TODO: implement other event loops
    app = get_app(self._backend._app)
    _backend_app = app.get_app()
    out = self._backend_object._plt_show()

    if out is NotImplemented:
        from whitecanvas.backend._window import view

        view(self, self._backend.app)

    if block:
        # TODO: automatically block the event loop or enable ipython
        # GUI mode if needed.
        app.run_app()

to_html(file=None)

Return HTML representation of the grid.

Source code in whitecanvas\canvas\_grid.py

def to_html(self, file: str | None = None) -> str:
    """Return HTML representation of the grid."""
    html = self._backend.get("to_html")(self._backend_object)
    if file is not None:
        Path(file).write_text(html, encoding="utf-8")
    return html

JointGrid

Grid with a main (joint) canvas and two marginal canvases.

The marginal canvases shares the x-axis and y-axis with the main canvas.

Source code in whitecanvas\canvas\_joint.py

class JointGrid(CanvasGrid):
    """
    Grid with a main (joint) canvas and two marginal canvases.

    The marginal canvases shares the x-axis and y-axis with the main canvas.
    """

    def __init__(
        self,
        loc: tuple[_0_or_1, _0_or_1] = (1, 0),
        palette: str | ColormapType | None = None,
        ratio: int = 4,
        backend: Backend | str | None = None,
    ):
        widths = [1, 1]
        heights = [1, 1]
        rloc, cloc = loc
        if rloc not in (0, 1) or cloc not in (0, 1):
            raise ValueError(f"Invalid location {loc!r}.")
        widths[rloc] = heights[cloc] = ratio
        super().__init__(widths, heights, backend=Backend(backend))
        self._main_canvas = self.add_canvas(rloc, cloc, palette=palette)
        self._x_canvas = self.add_canvas(1 - rloc, cloc)
        self._y_canvas = self.add_canvas(rloc, 1 - cloc)

        # flip the axes if needed
        if rloc == 0:
            self._x_canvas.y.flipped = True
            self._x_namespace_canvas = self._x_canvas
            self._main_canvas.x.ticks.visible = False
            self._title_namespace_canvas = self._main_canvas
        else:
            self._x_namespace_canvas = self._main_canvas
            self._x_canvas.x.ticks.visible = False
            self._title_namespace_canvas = self._x_canvas
        if cloc == 0:
            self._ynamespace_canvas = self._main_canvas
            self._y_canvas.y.ticks.visible = False
        else:
            self._y_canvas.x.flipped = True
            self._ynamespace_canvas = self._y_canvas
            self._main_canvas.y.ticks.visible = False

        self._backend_object._plt_set_spacings(10, 10)

        # link axes
        self._x_linker = link_axes([self._main_canvas.x, self._x_canvas.x])
        self._y_linker = link_axes([self._main_canvas.y, self._y_canvas.y])

        # joint plotter
        self._x_plotters = []
        self._y_plotters = []

    def _iter_x_plotters(self) -> Iterator[MarginalPlotter]:
        if len(self._x_plotters) == 0:
            yield MarginalHistPlotter(Orientation.VERTICAL)
        else:
            yield from self._x_plotters

    def _iter_y_plotters(self) -> Iterator[MarginalPlotter]:
        if len(self._y_plotters) == 0:
            yield MarginalHistPlotter(Orientation.HORIZONTAL)
        else:
            yield from self._y_plotters

    @property
    def x_canvas(self) -> Canvas:
        """The canvas at the x-axis."""
        return self._x_canvas

    @property
    def y_canvas(self) -> Canvas:
        """The canvas at the y-axis."""
        return self._y_canvas

    @property
    def main_canvas(self) -> Canvas:
        """The main (joint) canvas."""
        return self._main_canvas

    @property
    def x(self) -> _ns.XAxisNamespace:
        """The x-axis namespace of the joint grid."""
        return self._x_namespace_canvas.x

    @property
    def y(self) -> _ns.YAxisNamespace:
        """The y-axis namespace of the joint grid."""
        return self._ynamespace_canvas.y

    @property
    def title(self) -> _ns.TitleNamespace:
        """Title namespace of the joint grid."""
        return self._title_namespace_canvas.title

    def cat(
        self,
        data: _DF,
        x: str | None = None,
        y: str | None = None,
        *,
        update_labels: bool = True,
    ) -> JointCatPlotter[Self, _DF]:
        """Create a joint categorical canvas."""
        from whitecanvas.canvas.dataframe import JointCatPlotter

        return JointCatPlotter(self, data, x, y, update_labels=update_labels)

    def _link_marginal_to_main(self, layer: _l.Layer, main: _l.Layer) -> None:
        # TODO: this is not the only thing to be done
        main.events.visible.connect_setattr(layer, "visible", maxargs=1)

    def add_legend(
        self,
        layers: Sequence[str | _l.Layer] | None = None,
        location: Location | LocationStr = "top_right",
        *,
        title: str | None = None,
    ):
        """Add legend to the main canvas."""
        self.main_canvas.add_legend(layers, location=location, title=title)
        return None

    def add_markers(
        self,
        xdata: ArrayLike1D,
        ydata: ArrayLike1D,
        *,
        name: str | None = None,
        symbol: Symbol | str | None = None,
        size: float | None = None,
        color: ColorType | None = None,
        alpha: float = 1.0,
        hatch: str | Hatch | None = None,
    ) -> _l.Markers[_mixin.ConstFace, _mixin.ConstEdge, float]:
        color = self._main_canvas._generate_colors(color)
        out = self._main_canvas.add_markers(
            xdata, ydata, name=name, symbol=symbol, size=size, color=color,
            alpha=alpha, hatch=hatch,
        )  # fmt: skip
        for _x_plt in self._iter_x_plotters():
            xlayer = _x_plt.add_layer_for_markers(
                xdata, color, hatch, backend=self._backend
            )
            self.x_canvas.add_layer(xlayer)
            self._link_marginal_to_main(xlayer, out)
        for _y_plt in self._iter_y_plotters():
            ylayer = _y_plt.add_layer_for_markers(
                ydata, color, hatch, backend=self._backend
            )
            self.y_canvas.add_layer(ylayer)
            self._link_marginal_to_main(ylayer, out)
        self._autoscale_layers()
        return out

    def with_hist_x(
        self,
        *,
        bins: HistBinType = "auto",
        limits: tuple[float, float] | None = None,
        kind: str | HistogramKind = HistogramKind.density,
        shape: str | HistogramShape = HistogramShape.bars,
    ) -> Self:
        """
        Configure the x-marginal canvas to have a histogram.

        Parameters
        ----------
        bins : int or 1D array-like, default "auto"
            Bins of the histogram. This parameter will directly be passed
            to `np.histogram`.
        limits : (float, float), optional
            Limits in which histogram will be built. This parameter will equivalent to
            the `range` paraneter of `np.histogram`.
        shape : {"step", "polygon", "bars"}, default "bars"
            Shape of the histogram. This parameter defines how to convert the data into
            the line nodes.
        kind : {"count", "density", "probability", "frequency", "percent"}, optional
            Kind of the histogram.
        """
        self._x_plotters.append(
            MarginalHistPlotter(
                Orientation.VERTICAL, bins=bins, limits=limits, kind=kind, shape=shape
            )
        )
        return self

    def with_hist_y(
        self,
        *,
        bins: HistBinType = "auto",
        limits: tuple[float, float] | None = None,
        kind: str | HistogramKind = HistogramKind.density,
        shape: str | HistogramShape = HistogramShape.bars,
    ) -> Self:
        """
        Configure the y-marginal canvas to have a histogram.

        Parameters
        ----------
        bins : int or 1D array-like, default "auto"
            Bins of the histogram. This parameter will directly be passed
            to `np.histogram`.
        limits : (float, float), optional
            Limits in which histogram will be built. This parameter will equivalent to
            the `range` paraneter of `np.histogram`.
        shape : {"step", "polygon", "bars"}, default "bars"
            Shape of the histogram. This parameter defines how to convert the data into
            the line nodes.
        kind : {"count", "density", "probability", "frequency", "percent"}, optional
            Kind of the histogram.
        """
        self._y_plotters.append(
            MarginalHistPlotter(
                Orientation.HORIZONTAL, bins=bins, limits=limits, kind=kind, shape=shape
            )
        )
        return self

    def with_hist(
        self,
        *,
        bins: HistBinType | tuple[HistBinType, HistBinType] = "auto",
        limits: tuple[float, float] | None = None,
        kind: str | HistogramKind = HistogramKind.density,
        shape: str | HistogramShape = HistogramShape.bars,
    ) -> Self:
        """
        Configure both of the marginal canvases to have histograms.

        Parameters
        ----------
        bins : int or 1D array-like, default "auto"
            Bins of the histogram. This parameter will directly be passed
            to `np.histogram`.
        limits : (float, float), optional
            Limits in which histogram will be built. This parameter will equivalent to
            the `range` paraneter of `np.histogram`.
        shape : {"step", "polygon", "bars"}, default "bars"
            Shape of the histogram. This parameter defines how to convert the data into
            the line nodes.
        kind : {"count", "density", "probability", "frequency", "percent"}, optional
            Kind of the histogram.
        """
        if isinstance(bins, tuple):
            bins_x, bins_y = bins
        else:
            bins_x = bins_y = bins
        self.with_hist_x(bins=bins_x, limits=limits, kind=kind, shape=shape)
        self.with_hist_y(bins=bins_y, limits=limits, kind=kind, shape=shape)
        return self

    def with_kde_x(
        self,
        *,
        width: float | None = None,
        band_width: KdeBandWidthType = "scott",
        fill_alpha: float = 0.2,
    ) -> Self:
        """
        Configure the x-marginal canvas to have a kernel density estimate (KDE) plot.

        Parameters
        ----------
        width : float, optional
            Width of the line. Use theme default if not specified.
        band_width : "scott", "silverman" or float, default "scott"
            Bandwidth of the kernel.
        fill_alpha : float, default 0.2
            Alpha value of the fill color.
        """
        width = theme._default("line.width", width)
        self._x_plotters.append(
            MarginalKdePlotter(
                Orientation.VERTICAL,
                width=width,
                band_width=band_width,
                fill_alpha=fill_alpha,
            )
        )
        return self

    def with_kde_y(
        self,
        *,
        width: float | None = None,
        band_width: KdeBandWidthType = "scott",
        fill_alpha: float = 0.2,
    ) -> Self:
        """
        Configure the y-marginal canvas to have a kernel density estimate (KDE) plot.

        Parameters
        ----------
        width : float, optional
            Width of the line. Use theme default if not specified.
        band_width : "scott", "silverman" or float, default "scott"
            Bandwidth of the kernel.
        fill_alpha : float, default 0.2
            Alpha value of the fill color.
        """
        width = theme._default("line.width", width)
        self._y_plotters.append(
            MarginalKdePlotter(
                Orientation.HORIZONTAL,
                width=width,
                band_width=band_width,
                fill_alpha=fill_alpha,
            )
        )
        return self

    def with_kde(
        self,
        *,
        width: float | None = None,
        band_width: KdeBandWidthType = "scott",
        fill_alpha: float = 0.2,
    ) -> Self:
        """
        Configure both of the marginal canvases to have KDE plots.

        Parameters
        ----------
        width : float, optional
            Width of the line. Use theme default if not specified.
        band_width : "scott", "silverman" or float, default "scott"
            Bandwidth of the kernel.
        fill_alpha : float, default 0.2
            Alpha value of the fill color.
        """
        self.with_kde_x(width=width, band_width=band_width, fill_alpha=fill_alpha)
        self.with_kde_y(width=width, band_width=band_width, fill_alpha=fill_alpha)
        return self

    def with_rug_x(self, *, width: float | None = None) -> Self:
        """
        Configure the x-marginal canvas to have a rug plot.

        Parameters
        ----------
        width : float, optional
            Width of the line. Use theme default if not specified.
        """
        width = theme._default("line.width", width)
        self._x_plotters.append(MarginalRugPlotter(Orientation.VERTICAL, width=width))
        return self

    def with_rug_y(self, *, width: float | None = None) -> Self:
        """
        Configure the y-marginal canvas to have a rug plot.

        Parameters
        ----------
        width : float, optional
            Width of the line. Use theme default if not specified.
        """
        width = theme._default("line.width", width)
        self._y_plotters.append(MarginalRugPlotter(Orientation.HORIZONTAL, width=width))
        return self

    def with_rug(self, *, width: float | None = None) -> Self:
        """
        Configure both of the marginal canvases to have rug plots.

        Parameters
        ----------
        width : float, optional
            Width of the line. Use theme default if not specified.
        """
        self.with_rug_x(width=width)
        self.with_rug_y(width=width)
        return self

    def _autoscale_layers(self):
        for layer in self.x_canvas.layers:
            if isinstance(layer, (_l.Rug, _lt.DFRug)):
                ylow, yhigh = self.x_canvas.y.lim
                layer.update_length((yhigh - ylow) * 0.1)
        for layer in self.y_canvas.layers:
            if isinstance(layer, (_l.Rug, _lt.DFRug)):
                xlow, xhigh = self.y_canvas.x.lim
                layer.update_length((xhigh - xlow) * 0.1)

main_canvas: Canvas property

The main (joint) canvas.

title: _ns.TitleNamespace property

Title namespace of the joint grid.

x: _ns.XAxisNamespace property

The x-axis namespace of the joint grid.

x_canvas: Canvas property

The canvas at the x-axis.

y: _ns.YAxisNamespace property

The y-axis namespace of the joint grid.

y_canvas: Canvas property

The canvas at the y-axis.

add_legend(layers=None, location='top_right', *, title=None)

Add legend to the main canvas.

Source code in whitecanvas\canvas\_joint.py

def add_legend(
    self,
    layers: Sequence[str | _l.Layer] | None = None,
    location: Location | LocationStr = "top_right",
    *,
    title: str | None = None,
):
    """Add legend to the main canvas."""
    self.main_canvas.add_legend(layers, location=location, title=title)
    return None

cat(data, x=None, y=None, *, update_labels=True)

Create a joint categorical canvas.

Source code in whitecanvas\canvas\_joint.py

def cat(
    self,
    data: _DF,
    x: str | None = None,
    y: str | None = None,
    *,
    update_labels: bool = True,
) -> JointCatPlotter[Self, _DF]:
    """Create a joint categorical canvas."""
    from whitecanvas.canvas.dataframe import JointCatPlotter

    return JointCatPlotter(self, data, x, y, update_labels=update_labels)

with_hist(*, bins='auto', limits=None, kind=HistogramKind.density, shape=HistogramShape.bars)

Configure both of the marginal canvases to have histograms.

Parameters:

Name	Type	Description	Default
bins	int or 1D array-like	Bins of the histogram. This parameter will directly be passed to np.histogram.	"auto"
limits	(float, float)	Limits in which histogram will be built. This parameter will equivalent to the range paraneter of np.histogram.	None
shape	('step', 'polygon', 'bars')	Shape of the histogram. This parameter defines how to convert the data into the line nodes.	"step"
kind	('count', 'density', 'probability', 'frequency', 'percent')	Kind of the histogram.	"count"

Source code in whitecanvas\canvas\_joint.py

def with_hist(
    self,
    *,
    bins: HistBinType | tuple[HistBinType, HistBinType] = "auto",
    limits: tuple[float, float] | None = None,
    kind: str | HistogramKind = HistogramKind.density,
    shape: str | HistogramShape = HistogramShape.bars,
) -> Self:
    """
    Configure both of the marginal canvases to have histograms.

    Parameters
    ----------
    bins : int or 1D array-like, default "auto"
        Bins of the histogram. This parameter will directly be passed
        to `np.histogram`.
    limits : (float, float), optional
        Limits in which histogram will be built. This parameter will equivalent to
        the `range` paraneter of `np.histogram`.
    shape : {"step", "polygon", "bars"}, default "bars"
        Shape of the histogram. This parameter defines how to convert the data into
        the line nodes.
    kind : {"count", "density", "probability", "frequency", "percent"}, optional
        Kind of the histogram.
    """
    if isinstance(bins, tuple):
        bins_x, bins_y = bins
    else:
        bins_x = bins_y = bins
    self.with_hist_x(bins=bins_x, limits=limits, kind=kind, shape=shape)
    self.with_hist_y(bins=bins_y, limits=limits, kind=kind, shape=shape)
    return self

with_hist_x(*, bins='auto', limits=None, kind=HistogramKind.density, shape=HistogramShape.bars)

Configure the x-marginal canvas to have a histogram.

Parameters:

Name	Type	Description	Default
bins	int or 1D array-like	Bins of the histogram. This parameter will directly be passed to np.histogram.	"auto"
limits	(float, float)	Limits in which histogram will be built. This parameter will equivalent to the range paraneter of np.histogram.	None
shape	('step', 'polygon', 'bars')	Shape of the histogram. This parameter defines how to convert the data into the line nodes.	"step"
kind	('count', 'density', 'probability', 'frequency', 'percent')	Kind of the histogram.	"count"

Source code in whitecanvas\canvas\_joint.py

def with_hist_x(
    self,
    *,
    bins: HistBinType = "auto",
    limits: tuple[float, float] | None = None,
    kind: str | HistogramKind = HistogramKind.density,
    shape: str | HistogramShape = HistogramShape.bars,
) -> Self:
    """
    Configure the x-marginal canvas to have a histogram.

    Parameters
    ----------
    bins : int or 1D array-like, default "auto"
        Bins of the histogram. This parameter will directly be passed
        to `np.histogram`.
    limits : (float, float), optional
        Limits in which histogram will be built. This parameter will equivalent to
        the `range` paraneter of `np.histogram`.
    shape : {"step", "polygon", "bars"}, default "bars"
        Shape of the histogram. This parameter defines how to convert the data into
        the line nodes.
    kind : {"count", "density", "probability", "frequency", "percent"}, optional
        Kind of the histogram.
    """
    self._x_plotters.append(
        MarginalHistPlotter(
            Orientation.VERTICAL, bins=bins, limits=limits, kind=kind, shape=shape
        )
    )
    return self

with_hist_y(*, bins='auto', limits=None, kind=HistogramKind.density, shape=HistogramShape.bars)

Configure the y-marginal canvas to have a histogram.

Parameters:

Name	Type	Description	Default
bins	int or 1D array-like	Bins of the histogram. This parameter will directly be passed to np.histogram.	"auto"
limits	(float, float)	Limits in which histogram will be built. This parameter will equivalent to the range paraneter of np.histogram.	None
shape	('step', 'polygon', 'bars')	Shape of the histogram. This parameter defines how to convert the data into the line nodes.	"step"
kind	('count', 'density', 'probability', 'frequency', 'percent')	Kind of the histogram.	"count"

Source code in whitecanvas\canvas\_joint.py

def with_hist_y(
    self,
    *,
    bins: HistBinType = "auto",
    limits: tuple[float, float] | None = None,
    kind: str | HistogramKind = HistogramKind.density,
    shape: str | HistogramShape = HistogramShape.bars,
) -> Self:
    """
    Configure the y-marginal canvas to have a histogram.

    Parameters
    ----------
    bins : int or 1D array-like, default "auto"
        Bins of the histogram. This parameter will directly be passed
        to `np.histogram`.
    limits : (float, float), optional
        Limits in which histogram will be built. This parameter will equivalent to
        the `range` paraneter of `np.histogram`.
    shape : {"step", "polygon", "bars"}, default "bars"
        Shape of the histogram. This parameter defines how to convert the data into
        the line nodes.
    kind : {"count", "density", "probability", "frequency", "percent"}, optional
        Kind of the histogram.
    """
    self._y_plotters.append(
        MarginalHistPlotter(
            Orientation.HORIZONTAL, bins=bins, limits=limits, kind=kind, shape=shape
        )
    )
    return self

with_kde(*, width=None, band_width='scott', fill_alpha=0.2)

Configure both of the marginal canvases to have KDE plots.

Parameters:

Name	Type	Description	Default
width	float	Width of the line. Use theme default if not specified.	None
band_width	('scott', 'silverman' or float)	Bandwidth of the kernel.	"scott"
fill_alpha	float	Alpha value of the fill color.	0.2

Source code in whitecanvas\canvas\_joint.py

def with_kde(
    self,
    *,
    width: float | None = None,
    band_width: KdeBandWidthType = "scott",
    fill_alpha: float = 0.2,
) -> Self:
    """
    Configure both of the marginal canvases to have KDE plots.

    Parameters
    ----------
    width : float, optional
        Width of the line. Use theme default if not specified.
    band_width : "scott", "silverman" or float, default "scott"
        Bandwidth of the kernel.
    fill_alpha : float, default 0.2
        Alpha value of the fill color.
    """
    self.with_kde_x(width=width, band_width=band_width, fill_alpha=fill_alpha)
    self.with_kde_y(width=width, band_width=band_width, fill_alpha=fill_alpha)
    return self

with_kde_x(*, width=None, band_width='scott', fill_alpha=0.2)

Configure the x-marginal canvas to have a kernel density estimate (KDE) plot.

Parameters:

Name	Type	Description	Default
width	float	Width of the line. Use theme default if not specified.	None
band_width	('scott', 'silverman' or float)	Bandwidth of the kernel.	"scott"
fill_alpha	float	Alpha value of the fill color.	0.2

Source code in whitecanvas\canvas\_joint.py

def with_kde_x(
    self,
    *,
    width: float | None = None,
    band_width: KdeBandWidthType = "scott",
    fill_alpha: float = 0.2,
) -> Self:
    """
    Configure the x-marginal canvas to have a kernel density estimate (KDE) plot.

    Parameters
    ----------
    width : float, optional
        Width of the line. Use theme default if not specified.
    band_width : "scott", "silverman" or float, default "scott"
        Bandwidth of the kernel.
    fill_alpha : float, default 0.2
        Alpha value of the fill color.
    """
    width = theme._default("line.width", width)
    self._x_plotters.append(
        MarginalKdePlotter(
            Orientation.VERTICAL,
            width=width,
            band_width=band_width,
            fill_alpha=fill_alpha,
        )
    )
    return self

with_kde_y(*, width=None, band_width='scott', fill_alpha=0.2)

Configure the y-marginal canvas to have a kernel density estimate (KDE) plot.

Parameters:

Name	Type	Description	Default
width	float	Width of the line. Use theme default if not specified.	None
band_width	('scott', 'silverman' or float)	Bandwidth of the kernel.	"scott"
fill_alpha	float	Alpha value of the fill color.	0.2

Source code in whitecanvas\canvas\_joint.py

def with_kde_y(
    self,
    *,
    width: float | None = None,
    band_width: KdeBandWidthType = "scott",
    fill_alpha: float = 0.2,
) -> Self:
    """
    Configure the y-marginal canvas to have a kernel density estimate (KDE) plot.

    Parameters
    ----------
    width : float, optional
        Width of the line. Use theme default if not specified.
    band_width : "scott", "silverman" or float, default "scott"
        Bandwidth of the kernel.
    fill_alpha : float, default 0.2
        Alpha value of the fill color.
    """
    width = theme._default("line.width", width)
    self._y_plotters.append(
        MarginalKdePlotter(
            Orientation.HORIZONTAL,
            width=width,
            band_width=band_width,
            fill_alpha=fill_alpha,
        )
    )
    return self

with_rug(*, width=None)

Configure both of the marginal canvases to have rug plots.

Parameters:

Name	Type	Description	Default
width	float	Width of the line. Use theme default if not specified.	None

Source code in whitecanvas\canvas\_joint.py

def with_rug(self, *, width: float | None = None) -> Self:
    """
    Configure both of the marginal canvases to have rug plots.

    Parameters
    ----------
    width : float, optional
        Width of the line. Use theme default if not specified.
    """
    self.with_rug_x(width=width)
    self.with_rug_y(width=width)
    return self

with_rug_x(*, width=None)

Configure the x-marginal canvas to have a rug plot.

Parameters:

Name	Type	Description	Default
width	float	Width of the line. Use theme default if not specified.	None

Source code in whitecanvas\canvas\_joint.py

def with_rug_x(self, *, width: float | None = None) -> Self:
    """
    Configure the x-marginal canvas to have a rug plot.

    Parameters
    ----------
    width : float, optional
        Width of the line. Use theme default if not specified.
    """
    width = theme._default("line.width", width)
    self._x_plotters.append(MarginalRugPlotter(Orientation.VERTICAL, width=width))
    return self

with_rug_y(*, width=None)

Configure the y-marginal canvas to have a rug plot.

Parameters:

Name	Type	Description	Default
width	float	Width of the line. Use theme default if not specified.	None

Source code in whitecanvas\canvas\_joint.py

def with_rug_y(self, *, width: float | None = None) -> Self:
    """
    Configure the y-marginal canvas to have a rug plot.

    Parameters
    ----------
    width : float, optional
        Width of the line. Use theme default if not specified.
    """
    width = theme._default("line.width", width)
    self._y_plotters.append(MarginalRugPlotter(Orientation.HORIZONTAL, width=width))
    return self

SingleCanvas

A canvas without other subplots.

This class is the simplest form of canvas. In matplotlib terms, it is a figure with a single axes.

Source code in whitecanvas\canvas\_grid.py

class SingleCanvas(_CanvasWithGrid):
    """
    A canvas without other subplots.

    This class is the simplest form of canvas. In `matplotlib` terms, it is a figure
    with a single axes.
    """

    def __init__(self, grid: CanvasGrid):
        if grid.shape != (1, 1):
            raise ValueError(f"Grid shape must be (1, 1), got {grid.shape}")
        self._grid = grid
        _it = grid._iter_canvas()
        _, canvas = next(_it)
        if next(_it, None) is not None:
            raise ValueError("Grid must have only one canvas")
        self._main_canvas = canvas
        super().__init__(canvas, grid)

        # NOTE: events, dims etc are not shared between the main canvas and the
        # SingleCanvas instance. To avoid confusion, the first and the only canvas
        # should be replaces with the SingleCanvas instance.
        self.mouse = grid[0, 0].mouse
        grid._canvas_array[0, 0] = self
        self.events.drawn.connect(
            self._main_canvas.events.drawn.emit, unique=True, max_args=None
        )

link_axes(*axes)

Link multiple axes.

Source code in whitecanvas\canvas\_linker.py

def link_axes(*axes: AxisNamespace):
    """Link multiple axes."""
    linker = AxisLinker.link_axes(*axes)
    return AxisLinkerRef(linker)

AxisNamespace

Source code in whitecanvas\canvas\_namespaces.py

class AxisNamespace(Namespace):
    events: AxisSignals
    _attrs = ("lim", "color", "flipped")

    def __init__(self, canvas: CanvasBase | None = None):
        super().__init__(canvas)
        self.events = AxisSignals()
        self._flipped = False

    def _get_object(self) -> protocols.AxisProtocol:
        raise NotImplementedError

    @property
    def lim(self) -> tuple[float, float]:
        """Limits of the axis."""
        return self._get_object()._plt_get_limits()

    @lim.setter
    def lim(self, lim: tuple[float, float]):
        low, high = lim
        if low >= high:
            a = type(self).__name__[0].lower()
            raise ValueError(
                f"low must be less than high, but got {lim!r}. If you "
                f"want to flip the axis, use `canvas.{a}.flipped = True`."
            )
        # Manually emit signal. This is needed when the plot backend is
        # implemented in JS (such as bokeh) and the python callback is not
        # enabled. Otherwise axis linking fails.
        with self.events.blocked():
            self._get_object()._plt_set_limits(lim)
        self.events.lim.emit(lim)
        return None

    @property
    def color(self):
        """Color of the axis."""
        return self._get_object()._plt_get_color()

    @color.setter
    def color(self, color):
        self._get_object()._plt_set_color(np.array(Color(color)))
        self._draw_canvas()

    @property
    def flipped(self) -> bool:
        """Return true if the axis is flipped."""
        return self._flipped

    @flipped.setter
    def flipped(self, flipped: bool):
        """Set the axis to be flipped."""
        if flipped != self._flipped:
            self._get_object()._plt_flip()
            self._flipped = flipped

    def set_gridlines(
        self,
        visible: bool = True,
        color: ColorType = "gray",
        width: float = 1.0,
        style: str | LineStyle = LineStyle.SOLID,
    ):
        color = arr_color(color)
        style = LineStyle(style)
        if width < 0:
            raise ValueError("width must be non-negative.")
        self._get_object()._plt_set_grid_state(visible, color, width, style)

color property writable

Color of the axis.

flipped: bool property writable

Return true if the axis is flipped.

lim: tuple[float, float] property writable

Limits of the axis.

AxisSignals

Signals emitted by an axis.

Source code in whitecanvas\canvas\_namespaces.py

class AxisSignals(SignalGroup):
    """Signals emitted by an axis."""

    lim = Signal(tuple)

MouseNamespace

Namespace that contains the mouse events.

Source code in whitecanvas\canvas\_namespaces.py

class MouseNamespace(AxisNamespace):
    """Namespace that contains the mouse events."""

    clicked = MouseSignal(object)
    """Signal emitted when a mouse button is clicked."""

    moved = MouseMoveSignal()
    """Signal emitted when the mouse is moved."""

    double_clicked = MouseSignal(object)
    """Signal emitted when a mouse button is double-clicked."""

    @property
    def enabled(self) -> bool:
        """Return whether pan/zoom is enabled."""
        return self._get_canvas()._plt_get_mouse_enabled()

    @enabled.setter
    def enabled(self, enabled: bool):
        self._get_canvas()._plt_set_mouse_enabled(enabled)

    def emulate_click(
        self,
        position: tuple[float, float],
        *,
        button: str | MouseButton = MouseButton.LEFT,
        modifiers: str | Modifier | Sequence[str | Modifier] = (),
    ) -> None:
        """Emulate a mouse press event."""
        ev = MouseEvent(
            MouseButton(button),
            _norm_modifiers(modifiers),
            Point(*position),
            MouseEventType.PRESS,
        )
        self.clicked.emit(ev)
        return None

    def emulate_double_click(
        self,
        position: tuple[float, float],
        *,
        button: str | MouseButton = MouseButton.LEFT,
        modifiers: str | Modifier | Sequence[str | Modifier] = (),
    ) -> None:
        """Emulate a mouse double-click event."""
        ev = MouseEvent(
            MouseButton(button),
            _norm_modifiers(modifiers),
            Point(*position),
            MouseEventType.DOUBLE_CLICK,
        )
        self.double_clicked.emit(ev)

    def emulate_hover(
        self,
        positions: Sequence[tuple[float, float]],
        *,
        modifiers: str | Modifier | Sequence[str | Modifier] = (),
    ) -> None:
        """Emulate a mouse move event."""
        _modifiers = _norm_modifiers(modifiers)

        for pos in positions:
            ev = MouseEvent(
                MouseButton.NONE,
                _modifiers,
                Point(*pos),
                MouseEventType.MOVE,
            )
            self.moved.emit(ev)
        return None

    def emulate_drag(
        self,
        positions: Sequence[tuple[float, float]],
        *,
        button: str | MouseButton = MouseButton.LEFT,
        modifiers: str | Modifier | Sequence[str | Modifier] = (),
    ):
        """Emulate a mouse press-move-release event."""
        _modifiers = _norm_modifiers(modifiers)

        ev = MouseEvent(
            MouseButton(button),
            _modifiers,
            Point(*positions[0]),
            MouseEventType.PRESS,
        )
        self.moved.emit(ev)

        for pos in positions[1:]:
            ev = MouseEvent(
                MouseButton(button),
                _modifiers,
                Point(*pos),
                MouseEventType.MOVE,
            )
            self.moved.emit(ev)

        ev = MouseEvent(
            MouseButton(button),
            _modifiers,
            Point(*positions[-1]),
            MouseEventType.RELEASE,
        )
        self.moved.emit(ev)
        return None

clicked = MouseSignal(object) class-attribute instance-attribute

Signal emitted when a mouse button is clicked.

double_clicked = MouseSignal(object) class-attribute instance-attribute

Signal emitted when a mouse button is double-clicked.

enabled: bool property writable

Return whether pan/zoom is enabled.

moved = MouseMoveSignal() class-attribute instance-attribute

Signal emitted when the mouse is moved.

emulate_click(position, *, button=MouseButton.LEFT, modifiers=())

Emulate a mouse press event.

Source code in whitecanvas\canvas\_namespaces.py

def emulate_click(
    self,
    position: tuple[float, float],
    *,
    button: str | MouseButton = MouseButton.LEFT,
    modifiers: str | Modifier | Sequence[str | Modifier] = (),
) -> None:
    """Emulate a mouse press event."""
    ev = MouseEvent(
        MouseButton(button),
        _norm_modifiers(modifiers),
        Point(*position),
        MouseEventType.PRESS,
    )
    self.clicked.emit(ev)
    return None

emulate_double_click(position, *, button=MouseButton.LEFT, modifiers=())

Emulate a mouse double-click event.

Source code in whitecanvas\canvas\_namespaces.py

def emulate_double_click(
    self,
    position: tuple[float, float],
    *,
    button: str | MouseButton = MouseButton.LEFT,
    modifiers: str | Modifier | Sequence[str | Modifier] = (),
) -> None:
    """Emulate a mouse double-click event."""
    ev = MouseEvent(
        MouseButton(button),
        _norm_modifiers(modifiers),
        Point(*position),
        MouseEventType.DOUBLE_CLICK,
    )
    self.double_clicked.emit(ev)

emulate_drag(positions, *, button=MouseButton.LEFT, modifiers=())

Emulate a mouse press-move-release event.

Source code in whitecanvas\canvas\_namespaces.py

def emulate_drag(
    self,
    positions: Sequence[tuple[float, float]],
    *,
    button: str | MouseButton = MouseButton.LEFT,
    modifiers: str | Modifier | Sequence[str | Modifier] = (),
):
    """Emulate a mouse press-move-release event."""
    _modifiers = _norm_modifiers(modifiers)

    ev = MouseEvent(
        MouseButton(button),
        _modifiers,
        Point(*positions[0]),
        MouseEventType.PRESS,
    )
    self.moved.emit(ev)

    for pos in positions[1:]:
        ev = MouseEvent(
            MouseButton(button),
            _modifiers,
            Point(*pos),
            MouseEventType.MOVE,
        )
        self.moved.emit(ev)

    ev = MouseEvent(
        MouseButton(button),
        _modifiers,
        Point(*positions[-1]),
        MouseEventType.RELEASE,
    )
    self.moved.emit(ev)
    return None

emulate_hover(positions, *, modifiers=())

Emulate a mouse move event.

Source code in whitecanvas\canvas\_namespaces.py

def emulate_hover(
    self,
    positions: Sequence[tuple[float, float]],
    *,
    modifiers: str | Modifier | Sequence[str | Modifier] = (),
) -> None:
    """Emulate a mouse move event."""
    _modifiers = _norm_modifiers(modifiers)

    for pos in positions:
        ev = MouseEvent(
            MouseButton.NONE,
            _modifiers,
            Point(*pos),
            MouseEventType.MOVE,
        )
        self.moved.emit(ev)
    return None