render_array#
- treescope.render_array(array: ArrayInRegistry, *, columns: Sequence[AxisName | int] = (), rows: Sequence[AxisName | int] = (), sliders: Sequence[AxisName | int] = (), valid_mask: Any | None = None, continuous: bool | Literal['auto'] = 'auto', around_zero: bool | Literal['auto'] = 'auto', vmax: float | None = None, vmin: float | None = None, trim_outliers: bool = True, dynamic_colormap: bool | Literal['auto'] = 'auto', colormap: list[tuple[int, int, int]] | None = None, truncate: bool = False, maximum_size: int = 10000, cutoff_size_per_axis: int = 512, minimum_edge_items: int = 5, axis_item_labels: dict[AxisName | int, list[str]] | None = None, value_item_labels: dict[int, str] | None = None, axis_labels: dict[AxisName | int, str] | None = None, pixels_per_cell: int | float = 7) figures_impl.TreescopeFigure [source]#
Renders an array (positional or named) to a displayable HTML object.
Each element of the array is rendered to a fixed-size square, with its position determined based on its index, and with each level of x and y axis represented by a “faceted” plot.
Out-of-bounds or otherwise unusual data is rendered with an annotation:
“X” means a value was NaN (for continuous data) or went out-of-bounds for the integer palette (for discrete data).
“I” or “-I” means a value was infinity or negative infinity.
“+” or “-” means a value was finite but went outside the bounds of the colormap (e.g. it was larger than
vmax
or smaller thanvmin
). By default this applies to values more than 3 standard deviations outside the mean.Four light dots on grey means a value was masked out by
valid_mask
, or truncated due to the maximum size or axis cutoff thresholds.
By default, this method automatically chooses a color rendering strategy based on the arguments:
If an explicit colormap is provided:
If
continuous
is True, the provided colors are interpreted as color stops and interpolated between.If
continuous
is False, the provided colors are interpreted as an indexed color palette, and each index of the palette is used to render the corresponding integer, starting from zero.
Otherwise:
If
continuous
is True:If
around_zero
is True, uses the diverging colormapdefault_diverging_colormap
. The initial value of this is a truncated version of the perceptually-uniform “Balance” colormap from cmocean, with blue for positive numbers and red for negative ones.If
around_zero
is False, uses the sequential colormapdefault_sequential_colormap
.The initial value of this is the perceptually-uniform “Viridis” colormap from matplotlib.
If
continuous
is False, uses a pattern-based “digitbox” rendering strategy to render integers up to 9,999,999 as nested squares, with one square per integer digit and digit colors drawn from the D3 Category20 colormap.
- Parameters:
array – The array to render. The type of this array must be registered in the
type_registries.NDARRAY_ADAPTER_REGISTRY
.columns – Sequence of axis names or positional axis indices that should be placed on the x axis, from innermost to outermost. If not provided, inferred automatically.
rows – Sequence of axis names or positional axis indices that should be placed on the y axis, from innermost to outermost. If not provided, inferred automatically.
sliders – Sequence of axis names or positional axis indices for which we should show only a single slice at a time, with the index determined with a slider.
valid_mask – Optionally, a boolean array with the same shape (and, if applicable, axis names) as
array
, which is True for the locations that we should actually render, and False for locations that do not have valid array data.continuous – Whether to interpret this array as numbers along the real line, and visualize using an interpolated colormap. If “auto”, inferred from the dtype of
array
.around_zero – Whether the array data should be rendered symmetrically around zero using a diverging colormap, scaled based on the absolute magnitude of the inputs, instead of rescaled to be between the min and max of the data. If “auto”, treated as True unless both
vmin
andvmax
are set to incompatible values.vmax – Largest value represented in the colormap. If omitted and around_zero is True, inferred as
max(abs(array))
or as-vmin
. If omitted and around_zero is False, inferred asmax(array)
.vmin – Smallest value represented in the colormap. If omitted and around_zero is True, inferred as
-max(abs(array))
or as-vmax
. If omitted and around_zero is False, inferred asmin(array)
.trim_outliers – Whether to try to trim outliers when inferring
vmin
andvmax
. If True, clips them to 3 standard deviations away from the mean (or 3 sqrt-second-moments around zero) if they would otherwise exceed it.dynamic_colormap – Whether to dynamically adjust the colormap based on mouse hover. Requires a continuous colormap, and
around_zero=True
. If “auto”, will be enabled for continuous arrays ifaround_zero
is True and neithervmin
norvmax
are provided.colormap – An optional explicit colormap to use, represented as a list of
(r,g,b)
tuples, where each channel is between 0 and 255. A good place to get colormaps is thepalettable
package, e.g. you can pass something likepalettable.matplotlib.Inferno_20.colors
.truncate – Whether or not to truncate the array to a smaller size before rendering.
maximum_size – Maximum numer of elements of an array to show. Arrays larger than this will be truncated along one or more axes. Ignored unless
truncate
is True.cutoff_size_per_axis – Maximum number of elements of each individual axis to show without truncation. Any axis longer than this will be truncated, with their visual size increasing logarithmically with the true axis size beyond this point. Ignored unless
truncate
is True.minimum_edge_items – How many values to keep along each axis for truncated arrays. We may keep more than this up to the budget of maximum_size. Ignored unless
truncate
is True.axis_item_labels – An optional mapping from axis names/positions to a list of strings, of the same length as the axis length, giving a label to each item along that axis. For instance, this could be the token string corresponding to each position along a sequence axis, or the class label corresponding to each category across a classifier’s output axis. This is shown in the tooltip when hovering over a pixel, and shown below the array when a pixel is clicked on. For convenience, names in this dictionary that don’t match any axes in the input are simply ignored, so that you can pass the same labels while rendering arrays that may not have the same axis names.
value_item_labels – For categorical data, an optional mapping from each value to a string. For instance, this could be the token value corresponding to each token ID in a sequence of tokens.
axis_labels – Optional mapping from axis names / indices to the labels we should use for that axis. If not provided, we label the named axes with their names and the positional axes with “axis {i}”, and also add th axis size.
pixels_per_cell – Size of each rendered array element in pixels, between 1 and 21 inclusive. This controls the zoom level of the rendering. Array elements are always drawn at 7 pixels per cell and then rescaled, so out-of-bounds annotations and “digitbox” integer value patterns may not display correctly at fewer than 7 pixels per cell.
- Returns:
An object which can be rendered in an IPython notebook, containing the HTML source of an arrayviz rendering.