Package index • radiatR

Launch the app

Browser-based interface – no R coding required.

launch_app(): Launch the radiatR Shiny companion app

Loading tracking data

Read and normalise trajectory files from 20+ tracking tools. Use dialect_args to pass tool-specific options (bodypart selection, likelihood thresholds, zone selection, etc.).

read_tracks(): Construct a Tracks from a data.frame or file(s)
read_tracks_dir(): Read all matching files from a directory and bind into a Tracks
read_tracks_format(): Construct a Tracks from a *format* spec (registered name or inline list)
load_manifest(): Load trajectories listed in a file table into a Tracks
dtrack_read(): Read a dtrack trajectory file into a Tracks
import_info(): Import landmark coordinates from text files
import_tracks(): Discover dtrack (or compatible) landmark/track file pairs in a directory
load_tracks(): Legacy helper to merge manifest metadata with a track table
load_tracks2(): Flexible metadata join for track tables
get_all_object_pos(): Aggregate track positions across all videos in a manifest.
get_trial_limits(): Summarise per-trial metadata for a single video.
get_tracked_object_pos(): Derive trial-level track positions in polar coordinates.
guess_columns(): Guess the role of each column in a track table

Loader registry

Register custom file formats or query which dialects are available.

register_loader_dialect(): Register a custom loader dialect The function must accept (x, ...) and return a data.frame in long form with columns at least id,time and one of (angle) or (x,y)
list_loader_dialects(): List registered loader dialects
register_loader_format(): Register a declarative loader *format* (list or YAML/JSON file) The spec maps cleanly onto read_tracks() args and supports regex-based column finding.
list_loader_formats(): List registered declarative formats

The Tracks class

S4 container holding a long-form trajectory data frame together with column mappings and metadata.

tracks() length(<Tracks>) `[`(<Tracks>,<ANY>,<missing>,<missing>) c(<Tracks>): Tracks container for circular trajectories
transform_history() log_transform() set_transform_history(): Transform history helpers for Tracks objects

Simulation

Generate synthetic circular-space trajectories for teaching, pipeline testing, and power analysis.

simulate_tracks(): Simulate trajectory sets under configurable experimental conditions

Deriving headings

Extract one or more heading angles per trial from trajectory or pose data using built-in rules or custom functions.

derive_headings(): Derive heading angle(s) from trajectories using specified rule
circ_summary_headings(): Circular statistics over derived headings
pose_to_headings(): Derive per-frame headings from pose data without a Tracks
headings_frame(): Construct a headings frame from a data frame of angles
new_headings_frame(): Low-level headings_frame constructor
hf_display() hf_heading_col() hf_colour_col() hf_color_col() hf_coords(): Read the canonical attributes of a heading frame
register_heading_rule(): Register a custom heading derivation rule
list_heading_rules(): List registered custom heading rules
bin_angles(): Snap angles to fixed-width circular bin centres

Circular statistics – summaries

Mean direction, resultant length, concentration, and within-trial dispersion.

circ_summary(): Circular summaries per trajectory
circ_summarise(): Tidy circular summary of a grouped data frame
circ_dispersion(): Per-group circular dispersion statistics for a dense heading series
circ_boxplot_stats(): Circular boxplot statistics (Tukey-like, for circular and axial data)
sector_summary(): Proportion of time spent in angular sectors
compute_circ_mean(): Compute circular mean direction and resultant length from a headings data frame
compute_circ_interval(): Compute a circular interval arc from heading angles

Circular statistics – parametric fitting

Fit von Mises or wrapped Cauchy distributions via MLE. Pass fitted objects to the density overlay functions for visual model comparison.

vonmises_fit(): Fit a von Mises distribution to per-group heading data
wrappedcauchy_fit(): Fit a wrapped Cauchy distribution to per-group heading data
circ_model_select(): Select among candidate circular models by AICc

Circular statistics – correlation & regression

Measure the association between heading directions and a continuous covariate (circular-linear) or a second set of angles (circular-circular), and model a heading on linear covariates (Fisher-Lee regression).

circ_cor(): Circular correlation between headings and a covariate
circ_regression() summary(<circ_regression>) predict(<circ_regression>) fitted(<circ_regression>) print(<circ_regression>): Circular-linear regression of a heading on linear covariates
concentration_regression() summary(<concentration_regression>) predict(<concentration_regression>) fitted(<concentration_regression>) print(<concentration_regression>): Von Mises regression of concentration on covariates
fitted_directions(): Fitted mean directions from a circular regression, for plotting

Circular statistics – hypothesis tests

Uniformity, equal mean directions, and equal concentrations. All functions return tidy data frames; use p_adjust for family-wise or FDR correction when testing multiple groups.

test_uniformity(): Per-group tests of circular uniformity
test_mean_directions(): Test whether groups share the same mean direction
boot_mean_ci(): Bootstrap confidence interval for a mean direction
test_concentration(): Test whether groups share the same concentration (dispersion)
boot_kappa_ci(): Bootstrap confidence intervals for circular concentration
boot_kappa_contrast(): Bootstrap confidence interval for a between-condition concentration contrast

Visualisation – core

The main radiate() function and its building blocks.

radiate(): Make ggplot object of tracks radiating from circle centre.
plot_profile(): Kinematics profile plot for a Tracks
plot_speed_direction(): Speed-vs-direction scatter for a Tracks
plot_speed_histogram(): Speed distribution histogram for a Tracks
gg_traj(): Plot trajectories from a Tracks (overlay or faceted)
draw_tracks(): Create geom layers for Cartesian track coordinates
add_ticks(): Create evenly spaced radial tick marks.
add_circ(): Draw a circular guide.
degree_labs(): Label the four diagonal directions.
radial_theme(): Themes for radial track plots, named for the ggplot2 base themes.
directedness_arrow(): Make mean resultant length arrow
assign_cycle_colours() assign_cycle_colors(): Assign cycling colour indices to trajectories
add_multiple_circles(): Add multiple concentric circles to a ggplot object
circ_display(): Circular display convention specification
add_radial_grid(): Radial grid layers (the radial analogue of a Cartesian grid)
add_origin_point(): Mark the centre of a radial plot
assign_colour_key() assign_color_key(): Assign a shared colour-key column to a Tracks or data frame
cycle_colours() cycle_colors(): Cycle a bounded set of colour indices over the values of a key

Visualisation – circumference scales

Label the circumference of a radial plot in domain units – compass points, clock hours, months, or seconds.

circumference_labs(): Label the circumference of a radial plot in domain units
scale_cardinal(): Circumference scale: cardinal compass directions
scale_clock(): Circumference scale: clock hours
scale_months(): Circumference scale: months of the year
scale_seconds(): Circumference scale: seconds (or minutes)
as_angle(): Map periodic time, date, or numeric data onto circular angles

Visualisation – heading overlays

Per-trial heading markers, vectors, and mean-direction arrows.

add_heading_points(): Add heading endpoint markers on the unit circle
add_heading_vectors(): Add heading vector segments from inner crossing to unit circle
add_heading_arrow(): Compute a circular mean arrow and add it to a radial plot in one step
add_heading_density(): Compute a circular density and add it to a radial plot in one step
add_heading_interval(): Compute a circular interval arc and add it to a radial plot in one step
add_stacked_headings(): Add stacked heading dots as a ggplot2 layer
stack_headings(): Add stacking columns to a headings data frame
add_circ_mean(): Render pre-computed circular mean arrows on a radial plot
add_circ_interval(): Render a pre-computed circular interval arc on a radial plot
add_critical_r(): Add a critical resultant-length circle to a radiate plot
add_critical_v_line(): Add a V-test significance boundary to a radiate plot

Visualisation – distribution overlays

Overlay empirical and fitted angular distributions on a radiate plot. Default colours: rose grey, von Mises steelblue, wrapped Cauchy darkorange, KDE tomato.

add_angle_rose(): Add a rose diagram of heading angles to a radiate plot
add_vonmises_density(): Overlay a fitted von Mises density curve on a radiate plot
add_wrappedcauchy_density(): Overlay a fitted wrapped Cauchy density curve on a radiate plot
add_circular_kde(): Overlay a non-parametric circular kernel density estimate on a radiate plot
add_circular_density(): Wrap a pre-computed circular density around the unit circle
add_circular_boxplot(): Add a circular boxplot layer to a radial plot
compute_circular_density(): Compute a circular density data frame from heading observations

Visualisation – zone & quadrant guides

Zone dwell-time, quadrant lines, and goal-entry counting.

add_quadrant_lines(): Add quadrant lines to a radial plot
zone_dwell(): Dwell-time proportions across quadrant x ring zones
count_goal_entries(): Count entries into a goal zone for trajectories in a circular field

Coordinate utilities

Angle-convention conversions and geometric helpers.

rad_shepherd(): Wrap angles to the interval (-pi, pi]
line_circle_intercept(): Find the intercept of a line with the unit circle
line_circle_intercept_df(): Intersection helper using track rows
line_circle_intercept_traj(): Intersection helper for Tracks trajectories
derive_coords(): Derive polar and reference-relative coordinates from unit-circle position

Reference frame & transforms

Read or change a Tracks’s per-trajectory reference direction, and apply bespoke transformations (recorded in the transform history).

reference(): Per-trajectory reference direction of a Tracks
set_reference(): Set the per-trajectory reference and re-derive the relative frame
apply_transform(): Apply a bespoke transformation to a Tracks
restrict_to_circumference(): Restrict a Tracks to within the unit circle
transform_history() log_transform() set_transform_history(): Transform history helpers for Tracks objects

Path metrics

Per-trajectory straightness and tortuosity of the movement path.

straightness_index(): Per-trajectory straightness index for a Tracks
tortuosity_ratio(): Per-trajectory tortuosity ratio for a Tracks
path_straightness(): Path straightness index for a single trajectory
path_tortuosity(): Tortuosity ratio for a single trajectory
track_speed(): Per-trajectory speed for a Tracks, in real units
track_velocity(): Per-trajectory net velocity for a Tracks
track_turning(): Per-trajectory turning-rate summary for a Tracks
track_length(): Per-trajectory path length for a Tracks
step_speed(): Per-step speed along a trajectory
instantaneous_speed(): Per-observation instantaneous speed for a Tracks
velocity_vector(): Per-observation velocity vector for a Tracks
velocity_angle(): Per-row movement direction
angular_velocity(): Per-observation angular (turning-rate) velocity for a Tracks

Track timing

Attach a capture frame rate to a Tracks object and report real elapsed time per observation or per trajectory.

frame_rate() set_frame_rate(): Frame rate of a Tracks object
elapsed_seconds(): Elapsed time per observation of a Tracks object
track_duration(): Duration of each track
distance_scale() distance_unit() set_distance_scale() calibrate_distance(): Distance calibration for a Tracks object

Datasets

Bundled example data from a Cylindroiulus punctatus (millipede) visual orientation experiment (Kirwan & Nilsson 2019).

cpunctatus: *Cylindroiulus punctatus* visual orientation trajectory dataset
cpunctatus_tracks: *Cylindroiulus punctatus* trajectory tibble

Miscellaneous

Any remaining exported topics.

tracks() length(<Tracks>) `[`(<Tracks>,<ANY>,<missing>,<missing>) c(<Tracks>): Tracks container for circular trajectories
add_angle_rose(): Add a rose diagram of heading angles to a radiate plot
add_circ(): Draw a circular guide.
add_circ_interval(): Render a pre-computed circular interval arc on a radial plot
add_circ_mean(): Render pre-computed circular mean arrows on a radial plot
add_circular_boxplot(): Add a circular boxplot layer to a radial plot
add_circular_density(): Wrap a pre-computed circular density around the unit circle
add_circular_kde(): Overlay a non-parametric circular kernel density estimate on a radiate plot
add_critical_r(): Add a critical resultant-length circle to a radiate plot
add_critical_v_line(): Add a V-test significance boundary to a radiate plot
add_heading_arrow(): Compute a circular mean arrow and add it to a radial plot in one step
add_heading_density(): Compute a circular density and add it to a radial plot in one step
add_heading_interval(): Compute a circular interval arc and add it to a radial plot in one step
add_heading_points(): Add heading endpoint markers on the unit circle
add_heading_vectors(): Add heading vector segments from inner crossing to unit circle
add_landmark(): Add a landmark marker to a circular plot
add_multiple_circles(): Add multiple concentric circles to a ggplot object
add_origin_point(): Mark the centre of a radial plot
add_quadrant_lines(): Add quadrant lines to a radial plot
add_radial_grid(): Radial grid layers (the radial analogue of a Cartesian grid)
add_stacked_headings(): Add stacked heading dots as a ggplot2 layer
add_stimulus_arc(): Add a stimulus arc to a circular plot
add_ticks(): Create evenly spaced radial tick marks.
add_vonmises_density(): Overlay a fitted von Mises density curve on a radiate plot
add_wrappedcauchy_density(): Overlay a fitted wrapped Cauchy density curve on a radiate plot
angular_velocity(): Per-observation angular (turning-rate) velocity for a Tracks
apply_transform(): Apply a bespoke transformation to a Tracks
as.data.frame(<Tracks>): Coerce a Tracks to a data frame
as_angle(): Map periodic time, date, or numeric data onto circular angles
assign_colour_key() assign_color_key(): Assign a shared colour-key column to a Tracks or data frame
assign_cycle_colours() assign_cycle_colors(): Assign cycling colour indices to trajectories
bin_angles(): Snap angles to fixed-width circular bin centres
boot_kappa_ci(): Bootstrap confidence intervals for circular concentration
boot_kappa_contrast(): Bootstrap confidence interval for a between-condition concentration contrast
boot_mean_ci(): Bootstrap confidence interval for a mean direction
circ_boxplot_stats(): Circular boxplot statistics (Tukey-like, for circular and axial data)
circ_cor(): Circular correlation between headings and a covariate
circ_dispersion(): Per-group circular dispersion statistics for a dense heading series
circ_display(): Circular display convention specification
circ_model_select(): Select among candidate circular models by AICc
circ_regression() summary(<circ_regression>) predict(<circ_regression>) fitted(<circ_regression>) print(<circ_regression>): Circular-linear regression of a heading on linear covariates
circ_summarise(): Tidy circular summary of a grouped data frame
circ_summary(): Circular summaries per trajectory
circ_summary_headings(): Circular statistics over derived headings
circular_mapping: Circular coordinate utilities
circumference_labs(): Label the circumference of a radial plot in domain units
compute_circ_interval(): Compute a circular interval arc from heading angles
compute_circ_mean(): Compute circular mean direction and resultant length from a headings data frame
compute_circular_density(): Compute a circular density data frame from heading observations
concentration_regression() summary(<concentration_regression>) predict(<concentration_regression>) fitted(<concentration_regression>) print(<concentration_regression>): Von Mises regression of concentration on covariates
count_goal_entries(): Count entries into a goal zone for trajectories in a circular field
cpunctatus: *Cylindroiulus punctatus* visual orientation trajectory dataset
cpunctatus_tracks: *Cylindroiulus punctatus* trajectory tibble
cycle_colours() cycle_colors(): Cycle a bounded set of colour indices over the values of a key
degree_labs(): Label the four diagonal directions.
derive_coords(): Derive polar and reference-relative coordinates from unit-circle position
derive_headings(): Derive heading angle(s) from trajectories using specified rule
directedness_arrow(): Make mean resultant length arrow
distance_scale() distance_unit() set_distance_scale() calibrate_distance(): Distance calibration for a Tracks object
.heading_registry: Build a data frame of arrow segments representing mean direction vectors Length equals resultant_R; angle equals mean_dir
draw_tracks(): Create geom layers for Cartesian track coordinates
dtrack_read(): Read a dtrack trajectory file into a Tracks
elapsed_seconds(): Elapsed time per observation of a Tracks object
fitted_directions(): Fitted mean directions from a circular regression, for plotting
frame_rate() set_frame_rate(): Frame rate of a Tracks object
get_all_object_pos(): Aggregate track positions across all videos in a manifest.
get_tracked_object_pos(): Derive trial-level track positions in polar coordinates.
get_trial_limits(): Summarise per-trial metadata for a single video.
gg_traj(): Plot trajectories from a Tracks (overlay or faceted)
guess_columns(): Guess the role of each column in a track table
headings_frame(): Construct a headings frame from a data frame of angles
hf_display() hf_heading_col() hf_colour_col() hf_color_col() hf_coords(): Read the canonical attributes of a heading frame
ids(): Trajectory identifiers of a Tracks
import_info(): Import landmark coordinates from text files
import_tracks(): Discover dtrack (or compatible) landmark/track file pairs in a directory
instantaneous_speed(): Per-observation instantaneous speed for a Tracks
launch_app(): Launch the radiatR Shiny companion app
line_circle_intercept(): Find the intercept of a line with the unit circle
line_circle_intercept_df(): Intersection helper using track rows
line_circle_intercept_traj(): Intersection helper for Tracks trajectories
list_heading_rules(): List registered custom heading rules
list_loader_dialects(): List registered loader dialects
list_loader_formats(): List registered declarative formats
load_manifest(): Load trajectories listed in a file table into a Tracks
load_tracks(): Legacy helper to merge manifest metadata with a track table
load_tracks2(): Flexible metadata join for track tables
new_headings_frame(): Low-level headings_frame constructor
path_sinuosity(): Sinuosity index for a single trajectory
path_straightness(): Path straightness index for a single trajectory
path_tortuosity(): Tortuosity ratio for a single trajectory
plot_profile(): Kinematics profile plot for a Tracks
plot_speed_direction(): Speed-vs-direction scatter for a Tracks
plot_speed_histogram(): Speed distribution histogram for a Tracks
pose_to_headings(): Derive per-frame headings from pose data without a Tracks
rad_shepherd(): Wrap angles to the interval (-pi, pi]
radial_theme(): Themes for radial track plots, named for the ggplot2 base themes.
radiate(): Make ggplot object of tracks radiating from circle centre.
read_tracks(): Construct a Tracks from a data.frame or file(s)
read_tracks_dir(): Read all matching files from a directory and bind into a Tracks
read_tracks_format(): Construct a Tracks from a *format* spec (registered name or inline list)
reference(): Per-trajectory reference direction of a Tracks
register_heading_rule(): Register a custom heading derivation rule
register_loader_dialect(): Register a custom loader dialect The function must accept (x, ...) and return a data.frame in long form with columns at least id,time and one of (angle) or (x,y)
register_loader_format(): Register a declarative loader *format* (list or YAML/JSON file) The spec maps cleanly onto read_tracks() args and supports regex-based column finding.
restrict_to_circumference(): Restrict a Tracks to within the unit circle
scale_cardinal(): Circumference scale: cardinal compass directions
scale_clock(): Circumference scale: clock hours
scale_months(): Circumference scale: months of the year
scale_seconds(): Circumference scale: seconds (or minutes)
sector_summary(): Proportion of time spent in angular sectors
set_reference(): Set the per-trajectory reference and re-derive the relative frame
simulate_tracks(): Simulate trajectory sets under configurable experimental conditions
sinuosity(): Per-trajectory sinuosity for a Tracks
stack_headings(): Add stacking columns to a headings data frame
step_speed(): Per-step speed along a trajectory
straightness_index(): Per-trajectory straightness index for a Tracks
test_concentration(): Test whether groups share the same concentration (dispersion)
test_distributions(): Test whether groups share the same circular distribution
test_gof(): Goodness-of-fit test against a wrapped Cauchy distribution
test_mean_directions(): Test whether groups share the same mean direction
test_symmetry(): Test a circular distribution for reflective symmetry
test_uniformity(): Per-group tests of circular uniformity
test_unimodality(): Test a circular sample for unimodality against bimodality
tortuosity_ratio(): Per-trajectory tortuosity ratio for a Tracks
track_duration(): Duration of each track
track_length(): Per-trajectory path length for a Tracks
track_speed(): Per-trajectory speed for a Tracks, in real units
track_turning(): Per-trajectory turning-rate summary for a Tracks
track_velocity(): Per-trajectory net velocity for a Tracks
transform_history() log_transform() set_transform_history(): Transform history helpers for Tracks objects
velocity_angle(): Per-row movement direction
velocity_vector(): Per-observation velocity vector for a Tracks
vonmises_fit(): Fit a von Mises distribution to per-group heading data
wrappedcauchy_fit(): Fit a wrapped Cauchy distribution to per-group heading data
zone_dwell(): Dwell-time proportions across quadrant x ring zones