Package: radiatR 0.4.0

radiatR: Analysis and Visualisation of Headings and Trajectories in Circular Space

A complete pipeline for analysing directional data -- headings and trajectories in circular space. Supply a table of angles directly, or reconstruct headings from movement trajectories imported from 20+ tracking tools (EthoVision, DeepLabCut, SLEAP, TRex, ANY-maze, TrackMate, idtracker.ai, Ctrax, and others) via a unified dialect-based loader system, including multi-bodypart pose estimation with likelihood-weighted centroid. Derives per-trial heading directions using multiple rules (ring-crossing, distal point, pose body-axis, velocity-based, and more). Computes circular statistics including mean direction, resultant length, von Mises and wrapped Cauchy parametric fits, circular correlation (circular-linear and circular-circular), and multi-sample hypothesis tests (Watson-Williams, Rayleigh, and others) with multiple-comparison correction. Renders publication-quality ggplot2 radial plots with overlaid rose diagrams, parametric density curves, and non-parametric kernel density estimates. Includes a browser-based graphical interface requiring no R coding via launch_app().

Authors:John D. Kirwan [aut, cre]

radiatR_0.4.0.tar.gz
radiatR_0.4.0.zip(r-4.7)radiatR_0.4.0.zip(r-4.6)radiatR_0.4.0.zip(r-4.5)
radiatR_0.4.0.tgz(r-4.6-any)radiatR_0.4.0.tgz(r-4.5-any)
radiatR_0.4.0.tar.gz(r-4.7-any)radiatR_0.4.0.tar.gz(r-4.6-any)
radiatR_0.4.0.tgz(r-4.6-emscripten)
manual.pdf |manual.html✨
card.svg |card.png
radiatR/json (API)
NEWS

# Install 'radiatR' in R:
install.packages('radiatR', repos = c('https://johnkirwan.r-universe.dev', 'https://cloud.r-project.org'))

Bug tracker:https://github.com/johnkirwan/radiatr/issues

Pkgdown/docs site:https://johnkirwan.github.io

Datasets:
  • cpunctatus - *Cylindroiulus punctatus* visual orientation trajectory dataset
  • cpunctatus_tracks - *Cylindroiulus punctatus* trajectory tibble

On CRAN:

Conda:

4.43 score 12 scripts 119 exports 26 dependencies

Last updated from:e93c38dd4e. Checks:7 OK, 2 ERROR. Indexed: yes.

TargetResultTimeFilesSyslog
linux-devel-x86_64OK359
source / vignettesOK404
linux-release-x86_64OK353
macos-release-arm64ERROR248
macos-oldrel-arm64ERROR232
windows-develOK374
windows-releaseOK374
windows-oldrelOK354
wasm-releaseOK132

Exports:add_angle_roseadd_circadd_circ_intervaladd_circ_meanadd_circular_boxplotadd_circular_densityadd_circular_kdeadd_critical_radd_critical_v_lineadd_heading_arrowadd_heading_densityadd_heading_intervaladd_heading_pointsadd_heading_vectorsadd_multiple_circlesadd_origin_pointadd_quadrant_linesadd_radial_gridadd_stacked_headingsadd_ticksadd_vonmises_densityadd_wrappedcauchy_densityangular_velocityapply_transformassign_color_keyassign_colour_keyassign_cycle_colorsassign_cycle_coloursbin_anglescalibrate_distancecirc_boxplot_statscirc_corcirc_dispersioncirc_displaycirc_model_selectcirc_regressioncirc_summarisecirc_summarycirc_summary_headingscompute_circ_intervalcompute_circ_meancompute_circular_densitycount_goal_entriescycle_colorscycle_coloursdegree_labsderive_coordsderive_headingsdirectedness_arrowdistance_scaledistance_unitdraw_tracksdtrack_readelapsed_secondsfitted_directionsframe_rateget_all_object_posget_tracked_object_posget_trial_limitsgg_trajguess_columnsheadings_framehf_color_colhf_colour_colhf_coordshf_displayhf_heading_colimport_infoimport_tracksinstantaneous_speedlaunch_appline_circle_interceptline_circle_intercept_dfline_circle_intercept_trajlist_heading_ruleslist_loader_dialectslist_loader_formatsload_manifestload_tracksload_tracks2log_transformnew_headings_framepath_straightnesspath_tortuositypose_to_headingsrad_shepherdradial_themeradiateread_tracksread_tracks_dirread_tracks_formatreferenceregister_heading_ruleregister_loader_dialectregister_loader_formatsector_summaryset_distance_scaleset_frame_rateset_referenceset_transform_historysimulate_tracksstack_headingsstep_speedstraightness_indextest_concentrationtest_mean_directionstest_uniformitytortuosity_ratiotrack_durationtrack_lengthtrack_speedtrack_turningtrack_velocitytrackstransform_historyvelocity_vectorvonmises_fitwrappedcauchy_fitzone_dwell

Dependencies:bootcircularclicpp11farverggplot2gluegtableisobandlabelinglifecyclemagrittrmvtnormpillarpkgconfigpurrrR6RColorBrewerrlangS7scalestibbleutf8vctrsviridisLitewithr

Circular Statistics and Distribution Overlays

Rendered fromcircular-statistics.Rmdusingknitr::rmarkdownon Jun 21 2026.

Last update: 2026-06-20
Started: 2026-06-03

radiatR

Rendered fromradiatR.Rmdusingknitr::rmarkdownon Jun 21 2026.

Last update: 2026-06-21
Started: 2022-01-21

radiatR design contract

Rendered fromdesign.Rmdusingknitr::rmarkdownon Jun 21 2026.

Last update: 2026-06-20
Started: 2026-06-19

Simulating Trajectories

Rendered fromsimulate.Rmdusingknitr::rmarkdownon Jun 21 2026.

Last update: 2026-06-20
Started: 2026-05-31

Working with Loaders

Rendered fromloaders.Rmdusingknitr::rmarkdownon Jun 21 2026.

Last update: 2026-06-20
Started: 2025-10-26

Readme and manuals

Help Manual

Help pageTopics
Build a data frame of arrow segments representing mean direction vectors Length equals resultant_R; angle equals mean_dir.heading_registry
Add a rose diagram of heading angles to a radiate plotadd_angle_rose
Draw a circular guide.add_circ
Render a pre-computed circular interval arc on a radial plotadd_circ_interval
Render pre-computed circular mean arrows on a radial plotadd_circ_mean
Add a circular boxplot layer to a radial plotadd_circular_boxplot
Wrap a pre-computed circular density around the unit circleadd_circular_density
Overlay a non-parametric circular kernel density estimate on a radiate plotadd_circular_kde
Add a critical resultant-length circle to a radiate plotadd_critical_r
Add a V-test significance boundary to a radiate plotadd_critical_v_line
Compute a circular mean arrow and add it to a radial plot in one stepadd_heading_arrow
Compute a circular density and add it to a radial plot in one stepadd_heading_density
Compute a circular interval arc and add it to a radial plot in one stepadd_heading_interval
Add heading endpoint markers on the unit circleadd_heading_points
Add heading vector segments from inner crossing to unit circleadd_heading_vectors
Add multiple concentric circles to a ggplot objectadd_multiple_circles
Mark the centre of a radial plotadd_origin_point
Add quadrant lines to a radial plotadd_quadrant_lines
Radial grid layers (the radial analogue of a Cartesian grid)add_radial_grid
Add stacked heading dots as a ggplot2 layeradd_stacked_headings
Create evenly spaced radial tick marks.add_ticks
Overlay a fitted von Mises density curve on a radiate plotadd_vonmises_density
Overlay a fitted wrapped Cauchy density curve on a radiate plotadd_wrappedcauchy_density
Per-observation angular (turning-rate) velocity for a Tracksangular_velocity
Apply a bespoke transformation to a Tracksapply_transform
Coerce a Tracks to a data frameas.data.frame.Tracks
Assign a shared colour-key column to a Tracks or data frameassign_color_key assign_colour_key
Assign cycling colour indices to trajectoriesassign_cycle_colors assign_cycle_colours
Snap angles to fixed-width circular bin centresbin_angles
Circular boxplot statistics (Tukey-like, for circular and axial data)circ_boxplot_stats
Circular correlation between headings and a covariatecirc_cor
Per-group circular dispersion statistics for a dense heading seriescirc_dispersion
Circular display convention specificationcirc_display
Select among candidate circular models by AICccirc_model_select
Circular-linear regression of a heading on linear covariatescirc_regression fitted.circ_regression predict.circ_regression print.circ_regression summary.circ_regression
Tidy circular summary of a grouped data framecirc_summarise
Circular summaries per trajectorycirc_summary circ_summary,Tracks-method
Circular statistics over derived headingscirc_summary_headings
Circular coordinate utilitiescircular_mapping
Compute a circular interval arc from heading anglescompute_circ_interval
Compute circular mean direction and resultant length from a headings data framecompute_circ_mean
Compute a circular density data frame from heading observationscompute_circular_density
Count entries into a goal zone for trajectories in a circular fieldcount_goal_entries
*Cylindroiulus punctatus* visual orientation trajectory datasetcpunctatus
*Cylindroiulus punctatus* trajectory tibblecpunctatus_tracks
Cycle a bounded set of colour indices over the values of a keycycle_colors cycle_colours
Label the four diagonal directions.degree_labs
Derive polar and reference-relative coordinates from unit-circle positionderive_coords
Derive heading angle(s) from trajectories using specified rulederive_headings derive_headings,Tracks-method
Make mean resultant length arrowdirectedness_arrow
Distance calibration for a Tracks objectcalibrate_distance distance_scale distance_scale,Tracks-method distance_unit distance_unit,Tracks-method set_distance_scale set_distance_scale,Tracks-method
Create geom layers for Cartesian track coordinatesdraw_tracks
Read a dtrack trajectory file into a Tracksdtrack_read
Elapsed time per observation of a Tracks objectelapsed_seconds
Fitted mean directions from a circular regression, for plottingfitted_directions
Frame rate of a Tracks objectframe_rate frame_rate,Tracks-method set_frame_rate set_frame_rate,Tracks-method
Aggregate track positions across all videos in a manifest.get_all_object_pos
Derive trial-level track positions in polar coordinates.get_tracked_object_pos
Summarise per-trial metadata for a single video.get_trial_limits
Plot trajectories from a Tracks (overlay or faceted)gg_traj gg_traj,Tracks-method
Guess the role of each column in a track tableguess_columns
Construct a headings frame from a data frame of anglesheadings_frame
Read the canonical attributes of a heading framehf_accessors hf_color_col hf_colour_col hf_coords hf_display hf_heading_col
Import landmark coordinates from text filesimport_info
Discover dtrack (or compatible) landmark/track file pairs in a directoryimport_tracks
Per-observation instantaneous speed for a Tracksinstantaneous_speed
Launch the radiatR Shiny companion applaunch_app
Find the intercept of a line with the unit circleline_circle_intercept
Intersection helper using track rowsline_circle_intercept_df
Intersection helper for Tracks trajectoriesline_circle_intercept_traj
List registered custom heading ruleslist_heading_rules
List registered loader dialectslist_loader_dialects
List registered declarative formatslist_loader_formats
Load trajectories listed in a file table into a Tracksload_manifest
Legacy helper to merge manifest metadata with a track tableload_tracks
Flexible metadata join for track tablesload_tracks2
Low-level headings_frame constructornew_headings_frame
Path straightness index for a single trajectorypath_straightness
Tortuosity ratio for a single trajectorypath_tortuosity
Derive per-frame headings from pose data without a Trackspose_to_headings
Wrap angles to the interval (-pi, pi]rad_shepherd
Themes for radial track plots, named for the ggplot2 base themes.radial_theme
Make ggplot object of tracks radiating from circle centre.radiate radiate.default radiate.headings_frame radiate.Tracks
Construct a Tracks from a data.frame or file(s)read_tracks
Read all matching files from a directory and bind into a Tracksread_tracks_dir
Construct a Tracks from a *format* spec (registered name or inline list)read_tracks_format
Per-trajectory reference direction of a Tracksreference reference,Tracks-method
Register a custom heading derivation ruleregister_heading_rule
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_dialect
Register a declarative loader *format* (list or YAML/JSON file) The spec maps cleanly onto read_tracks() args and supports regex-based column finding.register_loader_format
Proportion of time spent in angular sectorssector_summary
Set the per-trajectory reference and re-derive the relative frameset_reference set_reference,Tracks-method
Simulate trajectory sets under configurable experimental conditionssimulate_tracks
Add stacking columns to a headings data framestack_headings
Per-step speed along a trajectorystep_speed
Per-trajectory straightness index for a Tracksstraightness_index
Test whether groups share the same concentration (dispersion)test_concentration
Test whether groups share the same mean direction (Watson-Williams)test_mean_directions
Per-group tests of circular uniformitytest_uniformity
Per-trajectory tortuosity ratio for a Trackstortuosity_ratio
Duration of each tracktrack_duration
Per-trajectory path length for a Trackstrack_length
Per-trajectory speed for a Tracks, in real unitstrack_speed
Per-trajectory turning-rate summary for a Trackstrack_turning
Per-trajectory net velocity for a Trackstrack_velocity
Tracks container for circular trajectoriesc,Tracks-method length,Tracks-method tracks Tracks-class [,Tracks,ANY,missing,missing-method
Transform history helpers for Tracks objectslog_transform log_transform,Tracks-method set_transform_history set_transform_history,Tracks-method transform_history transform_history,Tracks-method
Per-observation velocity vector for a Tracksvelocity_vector
Fit a von Mises distribution to per-group heading datavonmises_fit
Fit a wrapped Cauchy distribution to per-group heading datawrappedcauchy_fit
Dwell-time proportions across quadrant x ring zoneszone_dwell