add_nd_vectors#

NDWSubplot.add_nd_vectors(data, dims, display_dims, window_funcs=None, window_order=None, spatial_func=None, slider_maps=None, name=None, graphic_kwargs=None)[source]#

Add n-dimensional vectors to this subplot, similar to matplotlib quiver.

Every dim that is not listed in display_dims becomes a slider dim.

Parameters:

  • data (ArrayProtocol or None) – n-dimensional vector data of shape [..., n_vectors, 2, 2] or [..., n_vectors, 2, 3], where data[..., 0, :] are the vector positions and data[..., 1, :] are the vector directions. Pass None to create the NDVectors without a graphic and set the data later using nd_vectors.data, the slider dims then require an explicit reference range in the NDWidget.

  • dims (Sequence[str]) – name for every dim of data, in order. They do not need to be in display order.

  • display_dims (tuple[str, str, str]) – The 3 spatial dims in order: (n_vectors, positions_and_directions, xy(z)). The positions/directions dim must be of size 2 and the coordinate dim of size 2 or 3.

  • window_funcs (dict[str, tuple[WindowFuncCallable | None, int | float | None]], optional) –

    Per-slider-dim window functions applied around the current slider position, ex: {"time": (np.mean, 2.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 (ex: 2.5 seconds).

  • 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 mapping dim_name -> Callable, an ArrayLike, or None, 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.

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

  • graphic_kwargs (dict, optional) – passed to the underlying VectorsGraphic, ex: {"color": "cyan", "size": 0.5}

Return type:

NDVectors