whitecanvas.canvas package

Submodules

whitecanvas.canvas.layerlist module

class whitecanvas.canvas.layerlist.LayerList(data: Iterable[whitecanvas.layers._base.Layer] = ())[source]

Bases: psygnal.containers._evented_list.EventedList[whitecanvas.layers._base.Layer]

events: LayerListEvents
get(idx: str, default: Optional[whitecanvas.canvas.layerlist._V] = None) Optional[Union[whitecanvas.layers._base.Layer, whitecanvas.canvas.layerlist._V]][source]
iter_primitives() Iterable[whitecanvas.layers._base.PrimitiveLayer][source]
class whitecanvas.canvas.layerlist.LayerListEvents[source]

Bases: psygnal._group.SignalGroup

changed
inserted
inserting
moved
moving
removed
removing
renamed
reordered

Module contents

class whitecanvas.canvas.Canvas(backend: str | None = None, *, palette: Optional[Union[str, cmap._colormap.Colormap, Any]] = None)[source]

Bases: whitecanvas.canvas._base.CanvasBase

classmethod from_backend(obj: protocols.CanvasProtocol, *, palette: ColormapType | None = None, backend: str | None = None) Self[source]

Create a canvas object from a backend object.

class whitecanvas.canvas.CanvasBase(palette: Optional[Union[str, cmap._colormap.Colormap, Any]] = None)[source]

Bases: abc.ABC

Base class for any canvas object.

add_band(xdata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], ydata0: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], ydata1: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, name: str | None = None, orient: str | whitecanvas.types._enums.Orientation = Orientation.VERTICAL, color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = None, alpha: float = 1.0, pattern: str | whitecanvas.types._enums.FacePattern = FacePattern.SOLID) whitecanvas.layers.primitive.band.Band[source]
add_bars(center: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], height: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, bottom: Optional[Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]]] = 'None', name='None', orient: str | whitecanvas.types._enums.Orientation = 'Orientation.VERTICAL', extent: float = '0.8', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = 'None', alpha: float = '1.0', pattern: str | whitecanvas.types._enums.FacePattern = 'FacePattern.SOLID') whitecanvas.layers.primitive.bars.Bars[whitecanvas.layers._mixin.ConstFace, whitecanvas.layers._mixin.ConstEdge][source]
add_bars(height: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, bottom: Optional[Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]]] = 'None', name='None', orient: str | whitecanvas.types._enums.Orientation = 'Orientation.VERTICAL', extent: float = '0.8', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = 'None', alpha: float = '1.0', pattern: str | whitecanvas.types._enums.FacePattern = 'FacePattern.SOLID') whitecanvas.layers.primitive.bars.Bars[whitecanvas.layers._mixin.ConstFace, whitecanvas.layers._mixin.ConstEdge]

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 is Orientation.VERTICAL) – Orientation of the bars.

  • extent (float, default is 0.8) – Bar width in the canvas coordinate

  • color (color-like, optional) – Color of the bars.

  • alpha (float, default is 1.0) – Alpha channel of the bars.

  • pattern (str or FacePattern, default is FacePattern.SOLID) – Pattern of the bar faces.

Returns

The bars layer.

Return type

Bars

add_errorbars(xdata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], ylow: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], yhigh: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, name: str | None = None, orient: str | whitecanvas.types._enums.Orientation = Orientation.VERTICAL, color: Union[str, Iterable[int | float], cmap._color.Color] = 'blue', width: float = 1, style: whitecanvas.types._enums.LineStyle | str = LineStyle.SOLID, antialias: bool = False, capsize: float = 0.0) whitecanvas.layers.primitive.errorbars.Errorbars[source]
add_hist(data: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, bins: Union[int, Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]] = 10, range: tuple[float, float] | None = None, density: bool = False, name: str | None = None, color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = None, alpha: float = 1.0, pattern: str | whitecanvas.types._enums.FacePattern = FacePattern.SOLID) whitecanvas.layers.primitive.bars.Bars[source]
add_image(image: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]], *, cmap: Union[str, cmap._colormap.Colormap, Any] = 'gray', clim: tuple[float | None, float | None] | None = None, flip_canvas: bool = True, lock_aspect: bool = True) whitecanvas.layers.primitive.image.Image[source]

Add an image layer to the canvas.

This method automatically flips the image vertically by default.

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 is "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 is True) – If True, flip the canvas vertically so that the image looks normal.

Returns

The image layer.

Return type

Image

add_infcurve(model: Callable[Concatenate[Any, _P], Any], *, bounds: tuple[float, float] = (- inf, inf), name: str | None = None, color: ColorType | None = None, width: float = 1.0, style: str | LineStyle = LineStyle.SOLID, antialias: bool = True) _l.InfCurve[_P][source]

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)).with_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 is (-np.inf, np.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, default is 1.0) – Line width.

  • style (str or LineStyle, default is LineStyle.SOLID) – Line style.

  • alpha (float, default is 1.0) – Alpha channel of the line.

  • antialias (bool, default is True) – Antialiasing of the line.

Returns

The infcurve layer.

Return type

InfCurve

add_infline(pos: tuple[float, float] = (0, 0), angle: float = 0.0, *, name: str | None = None, color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = None, width: float = 1.0, style: whitecanvas.types._enums.LineStyle | str = LineStyle.SOLID, antialias: bool = True)[source]
add_kde(data: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, bottom: float = 0.0, name: str | None = None, orient: str | whitecanvas.types._enums.Orientation = Orientation.VERTICAL, band_width: float | str = 'scott', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = None, alpha: float = 1.0, pattern: str | whitecanvas.types._enums.FacePattern = FacePattern.SOLID)[source]
add_layer(layer: whitecanvas.canvas._base._L, *, over: Optional[Union[whitecanvas.layers._base.Layer, Iterable[whitecanvas.layers._base.Layer]]] = None, under: Optional[Union[whitecanvas.layers._base.Layer, Iterable[whitecanvas.layers._base.Layer]]] = None) whitecanvas.canvas._base._L[source]

Add a layer to the canvas.

add_line(ydata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, name: str | None = 'None', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = 'None', width: float = '1.0', style: whitecanvas.types._enums.LineStyle | str = 'LineStyle.SOLID', alpha: float = '1.0', antialias: bool = 'True') whitecanvas.layers.primitive.line.Line[source]
add_line(xdata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], ydata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, name: str | None = 'None', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = 'None', width: float = '1.0', style: whitecanvas.types._enums.LineStyle | str = 'LineStyle.SOLID', alpha: float = '1.0', antialias: bool = 'True') whitecanvas.layers.primitive.line.Line
add_line(xdata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], ydata: Callable[[Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]]], Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]]], *, name: str | None = 'None', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = 'None', width: float = '1.0', style: whitecanvas.types._enums.LineStyle | str = 'LineStyle.SOLID', alpha: float = '1.0', antialias: bool = 'True') whitecanvas.layers.primitive.line.Line

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, default is 1.0) – Line width.

  • style (str or LineStyle, default is LineStyle.SOLID) – Line style.

  • alpha (float, default is 1.0) – Alpha channel of the line.

  • antialias (bool, default is True) – Antialiasing of the line.

Returns

The line layer.

Return type

Line

add_markers(xdata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], ydata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, name: str | None = 'None', symbol: whitecanvas.types._enums.Symbol | str = 'Symbol.CIRCLE', size: float = '12', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = 'None', alpha: float = '1.0', pattern: str | whitecanvas.types._enums.FacePattern = 'FacePattern.SOLID') whitecanvas.layers.primitive.markers.Markers[whitecanvas.layers._mixin.ConstFace, whitecanvas.layers._mixin.ConstEdge, float][source]
add_markers(ydata: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, name: str | None = 'None', symbol: whitecanvas.types._enums.Symbol | str = 'Symbol.CIRCLE', size: float = '12', color: Optional[Union[str, Iterable[int | float], cmap._color.Color]] = 'None', alpha: float = '1.0', pattern: str | whitecanvas.types._enums.FacePattern = 'FacePattern.SOLID') whitecanvas.layers.primitive.markers.Markers[whitecanvas.layers._mixin.ConstFace, whitecanvas.layers._mixin.ConstEdge, float]

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, default is Symbol.CIRCLE) – Marker symbols.

  • size (float, default is 15) – Marker size.

  • color (color-like, optional) – Color of the marker faces.

  • alpha (float, default is 1.0) – Alpha channel of the marker faces.

  • pattern (str or FacePattern, default is FacePattern.SOLID) – Pattern of the marker faces.

Returns

The markers layer.

Return type

Markers

add_rug(events: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], *, low: float = 0.0, high: float = 1.0, name: str | None = None, color: Union[str, Iterable[int | float], cmap._color.Color] = 'black', alpha: float = 1.0, orient: str | whitecanvas.types._enums.Orientation = Orientation.VERTICAL) whitecanvas.layers.primitive.rug.Rug[source]
add_spans(spans: Union[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]], numpy._typing._nested_sequence._NestedSequence[numpy._typing._array_like._SupportsArray[numpy.dtype[Any]]], bool, int, float, complex, str, bytes, numpy._typing._nested_sequence._NestedSequence[Union[bool, int, float, complex, str, bytes]]], *, name: str | None = None, orient: str | whitecanvas.types._enums.Orientation = Orientation.VERTICAL, color: Union[str, Iterable[int | float], cmap._color.Color] = 'blue', alpha: float = 0.2, pattern: str | whitecanvas.types._enums.FacePattern = FacePattern.SOLID) whitecanvas.layers.primitive.spans.Spans[source]
add_text(x: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], y: Union[Sequence[Union[int, float, numpy.number]], numpy.ndarray[Any, numpy.dtype[numpy.number]]], string: list[str], *, color: Union[str, Iterable[int | float], cmap._color.Color] = 'black', size: float = 12, rotation: float = 0.0, anchor: str | whitecanvas.types._enums.Alignment = Alignment.BOTTOM_LEFT, fontfamily: str | None = None) whitecanvas.layers.primitive.text.Texts[source]

Add a text layer to the canvas.

Parameters
  • x (float or array-like) – X position of the text.

  • y (float or array-like) – Y position of the text.

  • string (str or list[str]) – Text string to display.

  • color (ColorType, optional) – Color of the text string.

  • size (float, default is 12) – Point size of the text.

  • rotation (float, default is 0.0) – Rotation angle of the text in degrees.

  • anchor (str or Alignment, default is Alignment.BOTTOM_LEFT) – Anchor position of the text. The anchor position will be the coordinate given by (x, y).

  • fontfamily (str, optional) – Font family of the text.

Returns

The text layer.

Return type

Text

property aspect_ratio: float | None

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

autoscale(xpad: float | tuple[float, float] | None = None, ypad: float | tuple[float, float] | None = None)[source]
between(l0, l1) BetweenPlotter[Self][source]
cat(data: Any, by: str | None = None, *, orient: str | Orientation = Orientation.VERTICAL, offsets: float | ArrayLike1D | None = None, palette: ColormapType | None = None, update_labels: bool = True) _cat.CategorizedDataPlotter[Self][source]

Categorize input data for plotting.

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

>>> df = sns.load_dataset("iris")
>>> canvas.cat(df, by="species").to_violinplot(y="sepal_width)
>>> canvas.cat(df, by="species").mean().to_line(y="sepal_width)
Parameters
  • data (tabular data) – Any categorizable data. Currently, dict, pandas.DataFrame, and polars.DataFrame are supported.

  • by (str, optional) – Which column to use for grouping.

  • orient (str or Orientation, default is Orientation.VERTICAL) – Orientation of the plot.

  • offsets (scalar or sequence, optional) – Offset for each category. If scalar, the same offset is used for all.

  • palette (ColormapType, optional) – Color palette used for plotting the categories.

  • update_labels (bool, default is True) – If True, update the x/y labels to the corresponding names.

Returns

Plotter object.

Return type

CategorizedDataPlotter

colorize(data: Any, by: str | None = None, *, update_labels: bool = True, palette: ColormapType | None = None) _cat.ColorizedPlotter[Self][source]
events: whitecanvas.canvas._base.CanvasEvents
layers
property lims: whitecanvas.types._tuples.Rect

Return the x/y limits of the canvas.

property native: Any

Return the native canvas object.

refer_image(layer: _l.Image) ImageRef[Self][source]
stack_over(layer: _L0) StackPlotter[Self, _L0][source]

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

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

─┴───┴┴───┴─

title
update_axes(visible: bool = <whitecanvas.types._alias._Void object>, color: typing.Optional[typing.Union[str, typing.Iterable[int | float], cmap._color.Color]] = <whitecanvas.types._alias._Void object>)[source]
property visible

Show the canvas.

x
y
class whitecanvas.canvas.CanvasGrid(heights: list[int], widths: list[int], *, link_x: bool = False, link_y: bool = False, backend: whitecanvas.backend._instance.Backend | str | None = None)[source]

Bases: object

add_canvas(row: int, col: int, rowspan: int = 1, colspan: int = 1, palette: str | None = None) whitecanvas.canvas._base.Canvas[source]

Add a canvas to the grid at the given position

property background_color: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Background color of the canvas.

iter_add_canvas(**kwargs) Iterator[whitecanvas.canvas._base.Canvas][source]
iter_canvas() Iterator[tuple[tuple[int, int], whitecanvas.canvas._base.Canvas]][source]
screenshot() numpy.ndarray[Any, numpy.dtype[numpy.uint8]][source]

Return a screenshot of the grid.

property shape: tuple[int, int]

The (row, col) shape of the grid

show(block=False) None[source]

Show the grid.

property size: tuple[float, float]
classmethod uniform(nrows: int = 1, ncols: int = 1, *, link_x: bool = False, link_y: bool = False, backend: whitecanvas.backend._instance.Backend | str | None = None) whitecanvas.canvas._grid.CanvasGrid[source]

Create a canvas grid with uniform row and column sizes.

Parameters
  • nrows (int) – The number of rows in the grid.

  • ncols (int) – The number of columns in the grid.

  • backend (backend-like, optional) – The backend to use for the grid.

property x_linked: bool

Whether the x-axis of all canvases are linked.

property y_linked: bool

Whether the y-axis of all canvases are linked.

class whitecanvas.canvas.CanvasHGrid(widths: list[int], *, link_x: bool = False, link_y: bool = False, backend: whitecanvas.backend._instance.Backend | str | None = None)[source]

Bases: whitecanvas.canvas._grid.CanvasGrid

add_canvas(col: int, **kwargs) whitecanvas.canvas._base.Canvas[source]

Add a canvas to the grid at the given position

classmethod uniform(ncols: int = 1, *, link_x: bool = False, link_y: bool = False, backend: whitecanvas.backend._instance.Backend | str | None = None) whitecanvas.canvas._grid.CanvasHGrid[source]

Create a canvas grid with uniform row and column sizes.

Parameters
  • nrows (int) – The number of rows in the grid.

  • ncols (int) – The number of columns in the grid.

  • backend (backend-like, optional) – The backend to use for the grid.

class whitecanvas.canvas.CanvasVGrid(heights: list[int], *, link_x: bool = False, link_y: bool = False, backend: whitecanvas.backend._instance.Backend | str | None = None)[source]

Bases: whitecanvas.canvas._grid.CanvasGrid

add_canvas(row: int, **kwargs) whitecanvas.canvas._base.Canvas[source]

Add a canvas to the grid at the given position

classmethod uniform(nrows: int = 1, *, link_x: bool = False, link_y: bool = False, backend: whitecanvas.backend._instance.Backend | str | None = None) whitecanvas.canvas._grid.CanvasVGrid[source]

Create a canvas grid with uniform row and column sizes.

Parameters
  • nrows (int) – The number of rows in the grid.

  • ncols (int) – The number of columns in the grid.

  • backend (backend-like, optional) – The backend to use for the grid.

class whitecanvas.canvas.SingleCanvas(grid: whitecanvas.canvas._grid.CanvasGrid)[source]

Bases: whitecanvas.canvas._base.CanvasBase

property background_color: numpy.ndarray[Any, numpy.dtype[numpy.floating]]

Background color of the canvas.

events: CanvasEvents
property native: Any

The native backend object.

screenshot() numpy.ndarray[Any, numpy.dtype[numpy.uint8]][source]

Return a screenshot of the grid.

show(block: bool = False) None[source]

Show the canvas using the method defined in the backend.

property size: tuple[float, float]

Size of the canvas