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.).

TrajSet_read(): Construct a TrajSet from a data.frame or file(s)
TrajSet_read_dir(): Read all matching files from a directory and bind into a TrajSet
TrajSet_read_format(): Construct a TrajSet from a *format* spec (registered name or inline list)
TrajSet_load_manifest(): Load trajectories listed in a file table into a TrajSet
dtrack_read(): Read a dtrack trajectory file into a TrajSet
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.

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 TrajSet_read() args and supports regex-based column finding.
list_loader_formats(): List registered declarative formats

The TrajSet class

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

TrajSet() length(<TrajSet>) `[`(<TrajSet>,<ANY>,<missing>,<missing>) c(<TrajSet>): TrajSet container for circular trajectories
calibrate_positions(): Calibrate TrajSet positions using a camera model
transform_history() log_transform() set_transform_history(): Transform history helpers for TrajSet objects

Simulation

Generate synthetic circular-arena 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 TrajSet
headings_frame(): Construct a headings frame from a data frame of angles
register_heading_rule(): Register a custom heading derivation rule
list_heading_rules(): List registered custom heading rules

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
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

Circular statistics – correlation

Measure the association between heading directions and a continuous covariate (circular-linear) or a second set of angles (circular-circular).

circ_cor(): Circular correlation between headings and a covariate

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 (Watson-Williams)
test_concentration(): Test whether groups share the same concentration (dispersion)

Visualisation – core

The main radiate() function and its building blocks.

radiate(): Make ggplot object of tracks radiating from circle centre.
gg_traj(): Plot trajectories from a TrajSet (overlay or faceted)
draw_tracks(): Create geom layers for Cartesian track coordinates
add_ticks(): Create tick marks at the cardinal directions.
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 cycling colour indices to trajectories
add_multiple_circles(): Add multiple concentric circles to a ggplot object

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

Visualisation – arena 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 circular arena trajectories

Calibration

Import camera intrinsics and distortion coefficients from MATLAB, OpenCV, or a plain CSV, then apply them to undistort pixel tracks. radiatR does not estimate calibrations itself.

read_calibration(): Import a camera calibration from an external toolbox
cal_model(): Build a camera calibration model from intrinsic coefficients
cam_cal_pt(): Calibrate the camera on the given xy coordinate
cam_cal_many(): Calibrate the camera on the given set of points
CalModel-class: Camera calibration model for trajectory correction

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 TrajSet trajectories

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.

CalModel-class: Camera calibration model for trajectory correction
TrajSet() length(<TrajSet>) `[`(<TrajSet>,<ANY>,<missing>,<missing>) c(<TrajSet>): TrajSet container for circular trajectories
TrajSet_load_manifest(): Load trajectories listed in a file table into a TrajSet
TrajSet_read(): Construct a TrajSet from a data.frame or file(s)
TrajSet_read_dir(): Read all matching files from a directory and bind into a TrajSet
TrajSet_read_format(): Construct a TrajSet from a *format* spec (registered name or inline list)
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_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_multiple_circles(): Add multiple concentric circles to a ggplot object
add_quadrant_lines(): Add quadrant lines to a radial plot
add_stacked_headings(): Add stacked heading dots as a ggplot2 layer
add_ticks(): Create tick marks at the cardinal directions.
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
as.data.frame(<TrajSet>): Coerce a TrajSet to a data frame
assign_colour_key(): Assign a shared colour-key column to a TrajSet or data frame
assign_cycle_colours(): Assign cycling colour indices to trajectories
bin_angles(): Snap angles to fixed-width circular bin centres
cal_model(): Build a camera calibration model from intrinsic coefficients
calibrate_positions(): Calibrate TrajSet positions using a camera model
cam_cal_many(): Calibrate the camera on the given set of points
cam_cal_pt(): Calibrate the camera on the given xy coordinate
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_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
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
count_goal_entries(): Count entries into a goal zone for circular arena trajectories
cpunctatus: *Cylindroiulus punctatus* visual orientation trajectory dataset
cpunctatus_tracks: *Cylindroiulus punctatus* trajectory tibble
cycle_colours(): Cycle a bounded set of colour indices over the values of a key
degree_labs(): Label the four diagonal directions.
derive_headings(): Derive heading angle(s) from trajectories using specified rule
directedness_arrow(): Make mean resultant length arrow
.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 TrajSet
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 TrajSet (overlay or faceted)
headings_frame(): Construct a headings frame from a data frame of angles
import_info(): Import landmark coordinates from text files
import_tracks(): Discover dtrack (or compatible) landmark/track file pairs in a directory
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 TrajSet trajectories
list_heading_rules(): List registered custom heading rules
list_loader_dialects(): List registered loader dialects
list_loader_formats(): List registered declarative formats
load_tracks(): Legacy helper to merge manifest metadata with a track table
load_tracks2(): Flexible metadata join for track tables
path_straightness(): Path straightness index for a single trajectory
path_tortuosity(): Tortuosity ratio for a single trajectory
pose_to_headings(): Derive per-frame headings from pose data without a TrajSet
rad_shepherd(): Wrap angles to the interval (-pi, pi]
radial_distort(): Remove radial/tangential distortion from a point on the image plane.
radial_theme(): Themes for radial track plots, named for the ggplot2 base themes.
radiate(): Make ggplot object of tracks radiating from circle centre.
read_calibration(): Import a camera calibration from an external toolbox
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 TrajSet_read() args and supports regex-based column finding.
sector_summary(): Proportion of time spent in angular sectors
simulate_tracks(): Simulate trajectory sets under configurable experimental conditions
stack_headings(): Add stacking columns to a headings data frame
straightness_index(): Per-trajectory straightness index for a TrajSet
test_concentration(): Test whether groups share the same concentration (dispersion)
test_mean_directions(): Test whether groups share the same mean direction (Watson-Williams)
test_uniformity(): Per-group tests of circular uniformity
tortuosity_ratio(): Per-trajectory tortuosity ratio for a TrajSet
transform_history() log_transform() set_transform_history(): Transform history helpers for TrajSet objects
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