fastplotlib.NDPositionsSlicer#

class NDPositionsSlicer(data, dims, display_dims, slider_maps=None, display_window=100, max_display_datapoints=1_000, datapoints_window_func=None, **kwargs)[source]#

NDSlicer subclass for n-dimensional positional and timeseries data.

Produces [n_graphics, p, <value dim>] slices for a LineCollection, LineStack, ScatterCollection, or ScatterStack, where p is the datapoints dim.

The p dim is simultaneously a slider dim and a spatial dim. Rather than the general window_funcs mechanism, it is windowed by display_window, which selects the datapoints that are rendered, and by datapoints_window_func, which aggregates over them.

Parameters:

data (ArrayProtocol) – n-dimensional positional data, must have 3 or more dims.
dims (Sequence[str]) –
names for each dimension in data. Dimensions not listed in display_dims are treated as slider dimensions and must appear as keys in the parent NDWidget’s ref_ranges.

Examples:
```
("trial", "line", "time", "xy")
("keypoints", "time", "xyz")
```
dims in the array do not need to be in the order that you want to display them, the data slice is transposed into the order given by display_dims.
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.
slider_maps (dict[str, Callable[[Any], int] | ArrayLike], optional) – See NDSlicer. The transform for the p dim is also used to map display_window and the datapoints_window_func window size from reference units to array indices.
display_window (int, float or None, default 100) – 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.
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.
Important note: if used, display_window is approximate and not exact due to padding from the window size. The window function is skipped when display_window is 0, or when the display window spans more than 2 * max_display_datapoints array indices, which would be too expensive to compute.
kwargs – passed to NDSlicer, i.e. window_funcs, window_order and spatial_func.