Skip to content

streamplot

Streamlines of a 2D vector field, computed in Rust (matplotlib's streamplot).

Not in lets-plot. streamplot() integrates the same lines and arrows as matplotlib.pyplot.streamplot without matplotlib, and returns them as polars frames to draw with geom_path and geom_segment(arrow=arrow()).

Matrix module-attribute 

Matrix = (
    collections.abc.Sequence[
        collections.abc.Sequence[float]
    ]
    | ggrust.streamplot._ArrayLike
)

Represent a union type

E.g. for int | str

Vector module-attribute 

Vector = (
    collections.abc.Sequence[float]
    | ggrust.streamplot._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

StreamplotSet 

StreamplotSet(lines: DataFrame, arrows: DataFrame)

Streamlines and their arrows, as matplotlib's StreamplotSet.

Attributes:

  • lines (DataFrame) –

    Columns x, y and group: the vertices of each line in order, one group per line (draw with geom_path(aes(group="group"))).

  • arrows (DataFrame) –

    Columns x, y, xend, yend and group: one short segment per line at half its arc length, pointing along the flow (draw with geom_segment(arrow=arrow())).

Examples:

>>> from ggrust import *
>>> x = [0, 1, 2, 3]
>>> y = [0, 1, 2]
>>> streams = streamplot(x, y, [[1.0] * 4] * 3, [[0.5] * 4] * 3)
>>> streams.lines.columns
['x', 'y', 'group']
>>> streams.arrows.columns
['x', 'y', 'xend', 'yend', 'group']

streamplot 

streamplot(
    x: Vector | Matrix,
    y: Vector | Matrix,
    u: Matrix,
    v: Matrix,
    *,
    density: float | tuple[float, float] = 1,
    minlength: float = 0.1,
    maxlength: float = 4.0,
    integration_direction: Literal = "both",
    broken_streamlines: bool = True,
    start_points: Matrix | None = None,
) -> StreamplotSet

Streamlines of the vector field (u, v), as matplotlib.pyplot.streamplot.

A line-by-line port of matplotlib's integrator (adaptive Heun steps, a 30 * density occupancy mask, seeds spiralling in from the boundary), so the lines and arrows match matplotlib's for the same input.

Parameters:

  • x (sequence of float or 2D array) –

    Evenly spaced, strictly increasing grid coordinates. 2D arrays as from numpy.meshgrid are accepted when every row of x (column of y) is the same.

  • y (sequence of float or 2D array) –

    Evenly spaced, strictly increasing grid coordinates. 2D arrays as from numpy.meshgrid are accepted when every row of x (column of y) is the same.

  • u (2D array) –

    x and y components of the field, with one row per y value and one column per x value. Non-finite values and masked entries (numpy masked arrays) are missing: lines stop there.

  • v (2D array) –

    x and y components of the field, with one row per y value and one column per x value. Non-finite values and masked entries (numpy masked arrays) are missing: lines stop there.

  • density (float or tuple of float, default: 1 ) –

    Closeness of the lines. density=1 divides the domain into a 30x30 mask, each cell crossed by at most one line. A tuple sets x and y apart.

  • minlength (float, default: 0.1 ) –

    Lines shorter than this (in axes coordinates, the domain being 1 x 1) are dropped.

  • maxlength (float, default: 4.0 ) –

    Longest line, in axes coordinates.

  • integration_direction ((both, forward, backward), default: "both" ) –

    Integrate along the field, against it, or both (each half as long).

  • broken_streamlines (bool, default: True ) –

    Stop a line when it comes too close to another. False lets lines run on.

  • start_points (2D array, default: None ) –

    (x, y) seed points in data coordinates, inside the grid. By default seeds spiral in from the boundary of the mask.

Returns:

  • StreamplotSet –

    lines (x, y, group) and arrows (x, y, xend, yend, group) frames.

Raises:

  • SpecError –

    If the grid is not evenly spaced and increasing, u or v does not match it, density is too small, integration_direction is unknown, or a start point lies outside the grid.

Examples:

>>> from ggrust import *
>>> x = [i / 10 for i in range(-20, 21)]
>>> y = x
>>> u = [[-yi for xi in x] for yi in y]
>>> v = [[xi for xi in x] for yi in y]
>>> streams = streamplot(x, y, u, v, density=1.5)
>>> 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()
... )