fastplotlib.NDTimeseries#

class NDTimeseries(ref_index, nd_subplot, data, dims, display_dims, *args, graphic_type=LineStack, 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, linear_selector=False, x_range_mode=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]#

NDPositions subclass for timeseries data, where the p dim is a time-like x-axis.

Supports the same LineStack, LineCollection, ScatterStack and ScatterCollection representations plus a heatmap (ImageGraphic) view. It also manages a linear selector that tracks the current p index, and couples the camera x-range to it through x_range_mode.

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 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 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 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.
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.
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, 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. 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.
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.
linear_selector (bool, default False) – Add a LinearSelector that marks the current index of the p dim. Dragging it sets that index in the ReferenceIndex, so it drives every other graphic that uses this dim. Only one is created per subplot, if one is already present this is ignored.
x_range_mode (“fixed” | “auto” | None, default None) –
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.
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. 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.

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.

Examples#

NDWidget Timeseries

NDWidget Timeseries cmaps

Highlight Selector