Skip to content

transition_reveal

transition_reveal(
    along: str,
    *,
    range: Sequence[TimeValue] | None = None,
    keep_last: bool = True,
) -> FeatureSpec

Animate by revealing the data along a column: lines grow, points travel.

The frames cover the range of along in equal steps (gganimate transition_reveal). In each group (sorted by along), lines, paths, areas and polygons show every row up to the frame plus an end point interpolated at the frame, so they grow smoothly. Other geoms (points, texts) show only the interpolated row: a mark that travels along its group. Each row's along is rounded to its nearest frame first, as gganimate does. Axes and legends cover the whole data. Layers without the along column are drawn in every frame.

Titles, subtitles and captions can show {frame_along}, the along value the frame stands for, plus {frame}, {nframes} and {progress}.

Parameters:

  • along (str) –

    The column to reveal along: numbers, dates, date-times or times of day.

  • range (sequence of two values, default: None ) –

    The (low, high) values the frames cover, in the column's type (numbers, dates, date-times or times of day). Default: the data's range. A range of another kind than the column raises SpecError when the frames are planned.

  • keep_last (bool, default: True ) –

    Keep a point (or another geom that does not join its rows) at the end of its group once the reveal has passed it. Lines always keep every row reached.

Returns:

  • FeatureSpec –

    The transition (kind "animation"), added to a plot with +.

Raises:

  • SpecError –

    If along is not a non-empty string, range is not two increasing values, or keep_last is not a bool.

Examples:

>>> from ggrust import *
>>> data = {"day": [1, 2, 3, 4, 5], "visitors": [120, 180, 150, 210, 260]}
>>> plot = (
...     ggplot(data, aes("day", "visitors"))
...     + geom_line()
...     + geom_point(size=4)
...     + transition_reveal("day")
...     + ggtitle("Day {frame_along}")
... )
>>> animate(plot, nframes=9).nframes
9

An area that grows, without the point kept at its end:

>>> plot = (
...     ggplot(data, aes("day", "visitors"))
...     + geom_area(alpha=0.4)
...     + geom_point(size=4)
...     + transition_reveal("day", keep_last=False)
... )

An area that grows, without the point kept at its end