Skip to content

velocity_grid

Cell velocities averaged onto a regular grid, computed in Rust (scVelo's gridding).

Not in lets-plot. velocity_grid() ports scVelo's compute_velocity_on_grid (scvelo 0.3.4), so RNA velocity streams need neither scVelo nor matplotlib: its result feeds straight into streamplot().

Pairs module-attribute 

Pairs = (
    collections.abc.Sequence[
        collections.abc.Sequence[float]
    ]
    | ggrust.velocity_grid._ArrayLike
)

Represent a union type

E.g. for int | str

SpecError 

SpecError(
    message: str, *, path: str = "", reason: str = ""
)

Bases: ggrust.errors.GgrustError, builtins.ValueError

Raised when the plot specification holds an invalid value.

Parameters:

  • message (str) –

    The full message, including the location.

  • path (str, default: "" ) –

    Spec path of the offending value, e.g. "layers[0].size" or "theme.axis_text.size"; empty when the error concerns the whole spec.

  • reason (str, default: "" ) –

    What was wrong and what is accepted, without the location.

Examples:

>>> from ggrust import *
>>> from ggrust.errors import SpecError
>>> data = {"weight": [2.6, 2.9, 3.2, 3.4, 3.6, 4.1], "mpg": [31, 28, 24, 22, 19, 15]}
>>> chart = ggplot(data, aes("weight", "mpg")) + geom_point(shape="star")
>>> try:
...     svg = chart.to_svg()
... except SpecError as error:
...     print(error.path)
layers[0].shape

VelocityGrid 

VelocityGrid(
    x: list[float],
    y: list[float],
    u: list[list[float]],
    v: list[list[float]],
)

Velocities on a regular grid, laid out for streamplot(x, y, u, v).

Attributes:

  • x (list of float) –

    Grid x coordinates, increasing (constant when the points do not spread in x, which only adjust_for_stream=False accepts, as scVelo).

  • y (list of float) –

    Grid y coordinates, increasing.

  • u (list of list of float) –

    x component of the velocity, one row per y value and one column per x value. Hidden grid points are NaN.

  • v (list of list of float) –

    y component of the velocity, laid out as u. NaN where u is NaN only when adjust_for_stream=False (as scVelo, which hides stream points through u alone; streamplot treats either as missing).

Examples:

>>> from ggrust import *
>>> points = [[i % 10, i // 10] for i in range(100)]
>>> vectors = [[1.0, 0.5]] * 100
>>> grid = velocity_grid(points, vectors, n_neighbors=5)
>>> len(grid.x), len(grid.y), len(grid.u), len(grid.u[0])
(50, 50, 50, 50)

velocity_grid 

velocity_grid(
    points: Pairs,
    vectors: Pairs,
    *,
    density: float = 1,
    smooth: float = 0.5,
    n_neighbors: int | None = None,
    min_mass: float = 1,
    cutoff_percentile: float = 5,
    adjust_for_stream: bool = True,
) -> VelocityGrid

Average cell velocities onto a regular grid, as scVelo's compute_velocity_on_grid.

Each grid point takes the Gaussian-weighted mean velocity of its n_neighbors nearest cells (exact Euclidean neighbours). The grid spans the points' range widened by 1 percent on each side. With adjust_for_stream (the default), grid points with almost no velocity, or whose neighbours move slowest (below the cutoff_percentile), are hidden, as scVelo prepares the field for a stream plot. Pass the result to streamplot().

Parameters:

  • points ((n, 2) array) –

    Cell coordinates in the embedding (e.g. UMAP), one (x, y) row per cell: a numpy array, nested sequences or a two-column data frame. Rows with a non-finite coordinate or velocity (or a masked entry) are dropped.

  • vectors ((n, 2) array) –

    Cell velocities in the embedding, one (dx, dy) row per cell.

  • density (float, default: 1 ) –

    Grid points per axis: int(50 * density), from 2 to 3162 (density from 0.04 to about 63).

  • smooth (float, default: 0.5 ) –

    Width of the Gaussian kernel, in units of the mean grid step.

  • n_neighbors (int, default: None ) –

    Cells averaged per grid point. By default int(n_cells / 50). From n_cells // 2 on, scikit-learn (and so scVelo) switches to less accurate brute-force distances; ggrust keeps exact ones, so the results differ slightly.

  • min_mass (float, default: 1 ) –

    Hide grid points whose velocity is below 10 ** (min_mass - 6) (at most 90 percent of the largest). With adjust_for_stream=False, hide those whose kernel mass is at most min_mass percent of the 99th percentile mass, as scVelo selects quiver arrows.

  • cutoff_percentile (float, default: 5 ) –

    Hide grid points whose neighbours' mean absolute velocity is below this percentile of all grid points (adjust_for_stream only).

  • adjust_for_stream (bool, default: True ) –

    Hide points as scVelo does for stream plots (True) or for quiver arrows (False; scVelo's autoscale is not applied).

Returns:

  • VelocityGrid –

    Grid x and y and velocity components u and v.

Raises:

  • SpecError –

    If points or vectors is not an (n, 2) array of numbers, they differ in length, the points have no spread on an axis (streams) or on both axes, n_neighbors is not between 1 and the number of finite points (the default needs at least 50 points), or an option is out of range.

Examples:

>>> import math
>>> from ggrust import *
>>> points = [[math.cos(i / 20) * (1 + i / 400), math.sin(i / 20) * (1 + i / 400)]
...           for i in range(400)]
>>> vectors = [[-y, x] for x, y in points]
>>> grid = velocity_grid(points, vectors, density=0.6)
>>> streams = streamplot(grid.x, grid.y, grid.u, grid.v)
>>> plot = (
...     ggplot()
...     + geom_path(aes("x", "y", group="group"), data=streams.lines)
...     + geom_segment(
...         aes("x", "y", xend="xend", yend="yend"), data=streams.arrows, arrow=arrow()
...     )
...     + coord_fixed()
... )