Creates a ggplot of the x-y trajectory from an anipoint. One path is drawn
per trajectory group, where a group is the combination of the frame's
grouping columns (anicore::get_keys()): its identity columns and its
temporal context, such as session or trial.
Usage
plot_trajectory(data, ...)
# Default S3 method
plot_trajectory(data, ..., mode = c("light", "dark"), palette = "Dark 3")Arguments
- data
An anipoint object.
- ...
Additional arguments (currently unused).
- mode
Either
"light"(default) or"dark"; passed totheme_animovement().- palette
Name of a qualitative palette accepted by
grDevices::hcl.colors(); controls the hue family across grouping levels.
Details
The positions are read from the columns the frame declares for its x and
y axes (anicore::get_axes()), and time from its index column
(anicore::get_index()), so neither has to be named x, y or time. The
axes are labelled by role. A three-dimensional frame is drawn in its x-y
plane. A frame without x and y axes, such as a polar one, is an error.
Colours adapt to the dataset shape:
single trajectory (no grouping): the line is coloured continuously by time using the Material gradient scale (
scale_colour_material_c()), shown as atimecolour bar.what-only or when-only grouping (one varying axis): each line gets its own hue from a qualitative palette, with
timemapped to alpha so the line fades in from start to end — shown in atimelegend.matrix grouping (both axes vary): each line is solid, coloured by the hue × shade matrix from
palette_animovement()— hue perwhat, shade perwhen; time reads from the start/end markers.
Every trajectory is annotated with a filled circle at its first point and a filled triangle at its last point, identified in a start/end legend. Gaps from missing data are bridged with a dashed line so the path stays traceable.
Examples
af <- anicore::example_anipoint(n_obs = 20, n_individuals = 2, n_keypoints = 1)
plot_trajectory(af)