add_nd_lines

NDWSubplot.add_nd_lines(data, dims, display_dims, *args, 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, name=None, graphic_kwargs=None, slicer_kwargs=None)

Add n-dimensional positional data to this subplot, rendered as a LineCollection.

Every dim that is not listed in display_dims becomes a slider dim. 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:

• data (ArrayProtocol or None) –

  n-dimensional positional data.

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

  Pass None to create the NDPositions without a graphic and set the data later using nd_positions.data, the slider dims then require an explicit reference range in the NDWidget.

• dims (Sequence[str]) – name for every dim of data, in order.

• display_dims (tuple[str, str, str]) – The 3 spatial dims in display order: (n_graphics, p, <value dim>), i.e. the number of lines 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.

• 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, ex: {"trial": (np.mean, 5)}. Each value is a (func, window_size) pair where:

  • func must accept axis: int and keepdims: bool kwargs (ex: np.mean, np.max). It must return an array that has the same dims as the input, therefore the size of any dim along which it was applied should reduce to 1. These dims must not be removed by the window func.

  • window_size is in reference-space units.

  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, window_funcs are ignored for any dim not specified in window_order.

• 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 in display_dims order, 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. An array of reference values may be given instead of a Callable, searchsorted is then used as the transform (ex: a timestamps array). Any dim without a transform uses the identity mapping, i.e. the current reference value is rounded to the nearest integer and used as the array index.

• 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 after the display window has been taken, as (func, apply_dims, window_size) where:

  • func must accept an axis: int kwarg (ex: np.mean, np.max). It is given a sliding window view of the data and is reduced along the window axis.

  • apply_dims names the coordinates of the value dim to apply it to, one of "all", "x", "y", "z", "xy", "xz", "yz", "xyz". Coordinates that are not named are passed through unchanged.

  • window_size is in the reference units of the p dim. It is mapped to array indices, clamped to a minimum of 3, and rounded up to an odd size.

  If used, display_window is approximate and not exact due to padding from the window size.

• colors (str | Sequence[str] | np.ndarray | FeatureCallable, optional) –

  Colors of the lines. 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 lines, 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.

• name (str, optional) – Name for this NDGraphic, used to retrieve it with nd_subplot[name].

• graphic_kwargs (dict, optional) – passed to the underlying LineCollection

• slicer_kwargs (dict, optional) – passed to the slicer constructor.

Return type:

NDPositions

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"]).