Skip to content

transition_time

transition_time(
    time: str, *, range: Sequence[TimeValue] | None = None
) -> FeatureSpec

Animate over a time column: frames evenly spaced in time, marks moving between times.

The frames cover the range of time in equal steps (gganimate transition_time); each time in the data is drawn at its nearest frame, and between two times the marks move from one to the next, matched by group (as transition_states; set groups with aes(group=...)). Numbers and sizes move by the plot's ease_aes(), colors through CIE Lab. Each layer uses its own times: before its first time and after its last it draws nothing. When two times fall on the same frame, only the earlier one is drawn (a warning says how many; raise nframes to draw more). Stats and positions run per time; axes and legends cover every frame. Layers without the time column are drawn in every frame.

Titles, subtitles and captions can show {frame_time}, the time the frame stands for (whole numbers for integer columns, YYYY-MM-DD for dates, date-times in UTC), plus {frame}, {nframes} and {progress}.

Parameters:

  • time (str) –

    The column of the times: numbers, dates, date-times or times of day.

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

    The (low, high) times the frames cover, in the column's type (numbers, datetime.date, datetime.datetime, numpy.datetime64). Default: the data's range. A range of another kind than the column (numbers for a date column) raises SpecError when the frames are planned.

Returns:

  • FeatureSpec –

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

Raises:

  • SpecError –

    If time is not a non-empty string, or range is not two increasing time values.

Examples:

>>> from ggrust import *
>>> data = {
...     "year": [2000, 2000, 2010, 2010, 2020, 2020],
...     "city": ["Oslo", "Lima"] * 3,
...     "income": [30, 8, 42, 11, 55, 15],
...     "life": [79, 72, 81, 75, 83, 77],
... }
>>> plot = (
...     ggplot(data, aes("income", "life", color="city"))
...     + geom_point(size=5)
...     + transition_time("year")
...     + ggtitle("Year: {frame_time}")
... )
>>> animate(plot, nframes=21).nframes
21

Only the first ten years, by range:

>>> plot = (
...     ggplot(data, aes("income", "life", color="city"))
...     + geom_point(size=5)
...     + transition_time("year", range=[2000, 2010])
... )

Only the first ten years, by range