Skip to content

shadow_wake

shadow_wake(
    wake_length: float,
    *,
    size: bool | float = True,
    alpha: bool | float = True,
    colour: str | None = None,
    fill: str | None = None,
    falloff: str = "cubic-in",
    wrap: bool = True,
    exclude_layer: int | Sequence[int] | None = None,
    exclude_phase: Literal | Sequence[Literal] | None = (
        "enter",
        "exit",
    ),
    color: str | None = None,
) -> FeatureSpec

Leave a fading wake behind moving marks (gganimate shadow_wake).

Each frame also draws the marks of the frames just before it, oldest first, each step closer to the mark itself: the oldest starts from the wake's end values (size, alpha, colour, fill) and the steps move toward the mark's own values, eased by falloff. Only marks drawn in the frame keep a wake, and not while they enter or exit (exclude_phase). Each mark's wake is drawn right before the mark. Layers without the transition's column never get a wake.

Parameters:

  • wake_length (float) –

    Length of the wake as a share of the frames (0.1: the last tenth of the frames), above 0 and at most 1.

  • size (bool or float, default: True ) –

    The size the wake shrinks to: True is 0, False keeps the size, a number is the end size relative to nothing (0.5 ends at half). Only marks with a mark size (points, texts) change.

  • alpha (bool or float, default: True ) –

    The opacity the wake fades to: True is 0, False keeps it.

  • colour (str, default: None ) –

    A color the wake's outline color moves to.

  • fill (str, default: None ) –

    A color the wake's fill moves to.

  • falloff (str, default: "cubic-in" ) –

    The ease of the steps (any ease_aes() name).

  • wrap (bool, default: True ) –

    Whether the first frames take their wake from the last frames (for animations that loop).

  • exclude_layer (int or sequence of int, default: None ) –

    Layers (counted from 1, as gganimate) that get no wake.

  • exclude_phase (str or sequence of str, default: ("enter", "exit") ) –

    Marks in these phases get no wake: "enter", "exit", "raw" (shown as is on a state's last frame), "static" (held) or "transition" (moving). None excludes none.

  • color (str, default: None ) –

    Alias of colour.

Returns:

  • FeatureSpec –

    The shadow (kind "animation"), added to a plot with +. A later shadow replaces an earlier one.

Raises:

  • SpecError –

    If an argument has the wrong type or is out of range, or an ease or phase name is unknown (with a close match when there is one).

Examples:

>>> from ggrust import *
>>> data = {"time": [1, 2, 3], "x": [1.0, 2.0, 3.0], "y": [1.0, 4.0, 9.0]}
>>> plot = (
...     ggplot(data, aes("x", "y"))
...     + geom_point(size=5)
...     + transition_time("time")
...     + shadow_wake(0.1)
... )
>>> plot.as_dict()["animation"]["shadow"]["wake_length"]
0.1

A longer trail that keeps its size and fades evenly:

>>> plot = (
...     ggplot(data, aes("x", "y"))
...     + geom_point(size=5)
...     + transition_time("time")
...     + shadow_wake(0.3, size=False, falloff="linear")
... )

A trail behind the second layer only (layers are counted from 1):

>>> plot = (
...     ggplot(data, aes("x", "y"))
...     + geom_point(size=9, shape=1)
...     + geom_point(size=4)
...     + transition_time("time")
...     + shadow_wake(0.3, exclude_layer=1)
... )

A longer trail that keeps its size and fades evenly

A trail behind the second layer only (layers are counted from 1)