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]
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
- 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
- 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
- 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
- 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
- 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]
- 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.
- 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
- 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.
- property size: tuple[float, float]
Size of the canvas