add_nd_timeseries#

NDWSubplot.add_nd_timeseries(data, dims, display_dims, *args, graphic_type=LineStack, x_range_mode='auto', 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]#

Add n-dimensional timeseries data to this subplot, where the p dim is a time-like x-axis.

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.

A LinearSelector that marks the current index of the p dim is added to the subplot. Dragging it sets that index in the ReferenceIndex, so it drives every other graphic that uses this dim. Only one is created per subplot.

Parameters:

  • data (ArrayProtocol or None) –

    n-dimensional timeseries data. The value dim holds the (x, y) of each datapoint, where x is the time-like coordinate.

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

    Pass None to create the NDTimeseries without a graphic and set the data later using nd_timeseries.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 traces in the collection, the number of datapoints p in each of them, and the value dim which holds the xy or xyz coordinate. A heatmap requires a value dim of size exactly 2. 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 | ImageGraphic], default LineStack) – The graphical representation used to display the data slice. ImageGraphic renders the traces as a heatmap, one row per trace, where the color represents the y coordinate. The x coordinates are applied as the offset and scale of the image, and the y values are interpolated onto a uniform x grid if the x sampling is not uniform.

  • x_range_mode ("fixed" | "auto" | None, default "auto") –

    How the camera x-range is coupled to the p dim.

    • None: the camera is left alone.

    • "fixed": the x-range is set from display_window, centered on the current p index, on every update.

    • "auto": as "fixed", and the camera x-range is also polled on every render. Panning or zooming then sets display_window to the new width and the p index to the new center, with a lower bound of 3 datapoints on the width.

    Forced to None when display_window is None.

  • 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, which also forces x_range_mode to None. 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. The transform for the p dim is typically the array of x values, ex: a timestamps array, so the slider is in seconds rather than sample indices. 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 traces. 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 traces, always static. A single name for every graphic, or an iterable of [n_graphics] names for a colormap per graphic. Mutually exclusive with colors. It is the only feature that is carried over to the heatmap representation.

  • 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.

Return type:

NDTimeseries

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. The heatmap representation uses only cmap.