fastplotlib.NDPositions#

class NDPositions(ref_index, nd_subplot, data, dims, display_dims, *args, graphic_type, slicer=NDPositionsSlicer, display_window=10, window_funcs=None, window_order=None, spatial_func=None, slider_maps=None, max_display_datapoints=1_000, datapoints_window_func=None, colors=None, cmap=None, cmap_transform=None, cmap_range=None, thickness=None, sizes=None, markers=None, name=None, graphic_kwargs=None, slicer_kwargs=None)[source]#

NDGraphic subclass for n-dimensional positional data.

Uses an NDPositionsSlicer to produce the data slices and manages one of four interchangeable graphical representations: LineStack, LineCollection, ScatterStack, and ScatterCollection. The representation can be changed at runtime by setting graphic_type.

Every dimension that is not listed in spatial_dims becomes a slider dimension. Each slider dim must have a ReferenceRange defined in the ReferenceIndex of the parent NDWidget. The datapoints dim, p, is both a spatial dim and a slider dim, it is windowed by display_window and datapoints_window_func rather than by window_funcs.

Parameters:

ref_index (ReferenceIndices) – The shared reference index that delivers slider updates to this graphic.
nd_subplot (NDWSubplot) – parent NDWSubplot the NDGraphic is in
data (array-like or None) –
n-dimensional positional data.

Ex: an array of shape [n_trials, n_lines, n_timepoints, 2] with dims of ("trial", "line", "time", "xy") and display_dims of ("line", "time", "xy").

Pass None to create the NDPositions without a graphic and set the data later using data.
dims (Sequence[str]) – Name for every dimension of data, in order. Non-spatial dims must match keys in ref_index.
display_dims (tuple[str, str, str]) – The 3 spatial dims in display order: (n_graphics, p, <value dim>), i.e. the number of lines or scatters in the collection, the number of datapoints p in each of them, and the value dim which holds the xy or xyz coordinate and must be of size 2 or 3. The dims do not need to be in this order in the array, the data slice is transposed into display order.
args – extra positional arguments passed to the slicer constructor.
graphic_type (type[LineCollection | LineStack | ScatterCollection | ScatterStack]) – The graphical representation used to display the data slice.
slicer (type[NDPositionsSlicer], default NDPositionsSlicer) – NDPositionsSlicer subclass that manages the data and produces the data slices.
display_window (int, float or None, default 10) – Size of the window of the p dim to render, in the reference units of that dim, centered on its current index. Use None to render every datapoint, or 0 to render only the datapoint at the current index. This is what makes out-of-core rendering possible, i.e. rendering a window of a dataset that is larger than GPU VRAM.
window_funcs (dict[str, tuple[WindowFuncCallable | None, int | float | None]], optional) – Per-slider-dim window functions applied around the current slider position, see NDSlicer. Not used for the p dim, see datapoints_window_func.
window_order (tuple[str, ...], optional) – Order in which the window functions are applied across dims. Only dims listed here have their window function applied, see NDSlicer.
spatial_func (Callable[[ArrayProtocol], ArrayProtocol], optional) – A function applied to the spatial slice after the window funcs, right before rendering. It is given the slice as [n_graphics, p, xy(z)], i.e. the array as it is rendered, and must return an array with those same dims.
slider_maps (dict[str, Callable[[Any], int] | ArrayLike], optional) – Per-slider-dim mapping from reference-space values to local array indices, see NDSlicer.
max_display_datapoints (int | None, default 1_000) – Maximum number of datapoints to render per graphic. The step size of the display window slice is set from this using floor division. None renders every datapoint in the window, with no decimation. Neither None nor a very large value is recommended: the entire window is then read into RAM and uploaded, which is slow for a large window over a large array.
datapoints_window_func (tuple[Callable, str, int | float], optional) – Window function applied along the p dim, as (func, apply_dims, window_size), see NDPositionsSlicer.
colors (str | Sequence[str] | np.ndarray | FeatureCallable, optional) –
Colors of the graphics. Mutually exclusive with cmap, setting one clears the other.
- static, a single color for every graphic, ex: "cyan" or an RGBA sequence of 4 floats
- static, one color per graphic, [n_graphics] of str or [n_graphics, 4] RGBA
- windowed, one color per datapoint, [n_graphics, p, 4] RGBA
- windowed, a FeatureCallable
cmap (str | Sequence[str], optional) – Colormap applied to the graphics, always static. A single name for every graphic, or an iterable of [n_graphics] names for a colormap per graphic. Mutually exclusive with colors.
cmap_transform (np.ndarray | FeatureCallable, optional) –
Values that the colormap colors are mapped from.
- static, one value per graphic, [n_graphics], so each graphic gets a single color
- windowed, one value per datapoint, [n_graphics, p]
- windowed, a FeatureCallable
cmap_range ((float, float) | np.ndarray, optional) – The (min, max) of cmap_transform mapped onto the colormap, or [n_graphics, 2] for a range per graphic. A windowed array cmap_transform defaults to its own (min, max) over the full p dim, so the display window keeps its position within the colormap. A FeatureCallable transform requires an explicit range, its full range is not knowable without evaluating it everywhere.
thickness (float | Sequence[float], optional) – Thickness of the lines, always static. A single value for every graphic, or [n_graphics] values for a thickness per graphic.
sizes (float | Sequence[float] | np.ndarray | FeatureCallable, optional) –
Size of the scatter points.
- static, a single size for every graphic, or [n_graphics] sizes for one size per graphic
- windowed, one size per datapoint, [n_graphics, p]
- windowed, a FeatureCallable
markers (str | Sequence[str] | np.ndarray | FeatureCallable, optional) –
Marker shape of the scatter points.
- static, a single marker for every graphic, or [n_graphics] markers for one per graphic
- windowed, one marker per datapoint, [n_graphics, p]
- windowed, a FeatureCallable
name (str, optional) – Name for this NDGraphic, used to retrieve it with nd_subplot[name].
graphic_kwargs (dict, optional) – passed to the graphic_type constructor.
slicer_kwargs (dict, optional) – passed to the slicer constructor.

Notes

Each of the other graphic features is either windowed or static, decided from the value itself:

windowed: a FeatureCallable, or an array whose axis 1 spans the p dim. It is re-sliced with the same display window slice as the data on every update, so the feature carries a value per displayed datapoint. An array must span the full p dim of the data, i.e. [n_graphics, p, <value dim>], since it is indexed with an index into the full p dim. A FeatureCallable is passed the data slice and that display window slice, and returns the feature values for the displayed datapoints.
static: anything else. It is set once on the collection, ex: a single value for every graphic, [n_graphics] values for one per graphic, or an iterator of per-graphic values such as itertools.cycle(["jet", "viridis"]).

A feature the graphic type does not have is ignored, ex: thickness for scatters, markers for lines.