Package 'radiatR'

Description

Draws angular frequency as filled wedge polygons in the Cartesian coordinate space used by radiate. Each wedge spans one angular bin; its outer radius is proportional to the proportion (or count) of frames in that bin. The layer can be faceted by passing the same column used in the parent radiate(facets = ...) call.

Usage

add_angle_rose(
  hd,
  bins = 12L,
  angle_col = "heading",
  group_col = NULL,
  scale = 0.4,
  inner_r = 0,
  normalize = TRUE,
  fill = "steelblue",
  colour = NA,
  alpha = 0.5,
  arc_pts = 20L,
  display = NULL,
  axial = FALSE,
  color = NULL
)

Arguments

Value

A geom_polygon layer that can be added to a radiate() plot with +.

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
radiate(cpunctatus[1:5]) + add_angle_rose(hd)

Description

Creates a list of annotation layers that render a circle with the requested radius and appearance. The returned list can be added directly to a ggplot.

Usage

add_circ(
  radius = 1,
  circle_colour = "grey60",
  circle_alpha = 1,
  circle_size = 1,
  linetype = "solid",
  colour = NULL,
  linewidth = NULL,
  circle_color = NULL,
  color = NULL
)

Arguments

Value

A list containing a single ggplot annotation layer.

Examples

library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ(radius = 1)

Description

Takes a data frame produced by [compute_circ_interval()] (or equivalent) and renders it as a 'geom_path()' arc at radius 'radius'. Each row produces one arc. Rows where 'lower' or 'upper' is 'NA' are silently skipped.

Usage

add_circ_interval(
  interval_df,
  colour_col = NULL,
  radius = 1.05,
  linewidth = 1.5,
  colour = NULL,
  linetype = "solid",
  n_theta = 500L,
  axial = FALSE,
  color_col = NULL,
  color = NULL
)

Arguments

Details

For the Bayesian extension, replace 'lower' and 'upper' in the output of [compute_circ_interval()] with credible interval bounds from any model before calling this function: “'r iv <- compute_circ_interval(hd) iv$lower <- posterior_lower iv$upper <- posterior_upper ggplot() + coord_fixed() + add_circ_interval(iv) “'

Value

A 'geom_path()' layer.

See Also

[compute_circ_interval()], [add_heading_interval()]

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
iv <- compute_circ_interval(hd, stat = "sd")
library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ() +
  add_circ_interval(iv)

Description

Takes a data frame produced by [compute_circ_mean()] and renders each row as a 'geom_segment()' arrow. 'mean_dir' must be in unit-circle convention (0 = East, CCW), as returned by [compute_circ_mean()]. Rows where 'mean_dir' or 'resultant_R' is 'NA' are silently skipped.

Usage

add_circ_mean(
  summary_df,
  colour_col = NULL,
  linewidth = 1,
  colour = NULL,
  arrow_length_cm = 0.2,
  axial = FALSE,
  ...,
  color_col = NULL,
  color = NULL
)

Arguments

Value

A 'geom_segment()' layer.

See Also

[compute_circ_mean()], [add_heading_arrow()]

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
sm <- compute_circ_mean(hd)
library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ() +
  add_circ_mean(sm)

Description

Renders the [circ_boxplot_stats()] summary onto a [radiate()] polar plot in the Buttarazzi et al. (2018) style: a filled box band between the hinges, whisker arcs, short crossbars at the median and hinges, far-out points, and an optional median arrow. For 'axial = TRUE' every element is drawn at both poles of the axis (offsets are computed with mod-pi arithmetic so the box is a short band even when the axis sits on the 0/pi seam). Composable with '+'.

Usage

add_circular_boxplot(
  hd,
  angle_col = "heading",
  axial = FALSE,
  radius = 1.1,
  width = 0.05,
  colour = "black",
  box_fill = "grey90",
  farout_shape = 8,
  show_median_arrow = FALSE,
  linewidth = 0.8,
  n_theta = 200L,
  display = NULL,
  facets = NULL,
  group_col = NULL,
  group_gap = 0.06,
  theme = NULL,
  color = NULL
)

Arguments

Value

A list of ggplot2 layers, or 'NULL' when the boxplot is not drawable (a 'warning()' is emitted with the reason).

References

Buttarazzi, D., Pandolfo, G. & Porzio, G. C. (2018). A boxplot for circular data. Biometrics 74(4), 1492–1501. doi:10.1111/biom.12889

See Also

[circ_boxplot_stats()], [radiate()]

Examples

tr <- simulate_tracks(output = "trajset", seed = 1)
hd <- derive_headings(tr, rule = "distal")
radiate(tr) + add_circular_boxplot(hd)

Description

Takes a data frame of '(theta, density)' pairs – from any source: MLE, kernel estimation, Bayesian posterior predictive, or hand-crafted – and renders it as a radial path (and optionally a filled polygon) around the unit circle boundary. At each angle theta the plotted radius is '1 + scale * density(theta) / max(density)'.

Usage

add_circular_density(
  density_df,
  theta_col = "theta",
  density_col = "density",
  colour_col = NULL,
  scale = 0.4,
  colour = "black",
  fill = NA,
  alpha = 0.2,
  linewidth = 0.8,
  ci_fill = "grey70",
  ci_alpha = 0.3,
  color_col = NULL,
  color = NULL
)

Arguments

Details

Because this function only handles rendering, it is agnostic to how the density was produced. To compute from raw headings use [compute_circular_density()] first, or call the convenience wrapper [add_heading_density()] which combines both steps.

For an **axial** (bidirectional) density, do not mirror this pre-computed frame (that would double-count a full-circle density). Instead estimate it with [compute_circular_density()]'(..., axial = TRUE)', which augments the raw sample before estimation, then pass the result here.

Value

A list of one, two, or three ggplot2 layers: optional CI band polygon, optional fill polygon between density and unit circle, and density path line.

See Also

[compute_circular_density()], [add_heading_density()]

Examples

library(ggplot2)
# From compute_circular_density:
hd <- data.frame(heading = c(0.2, 0.3, 0.4, 0.5, -0.1, 0.1, 0.6, 0.2))
dens_df <- compute_circular_density(hd)
ggplot() + coord_fixed() + add_circular_density(dens_df)

# From an external model (e.g. brms posterior predictive):
theta_grid <- seq(-pi, pi, length.out = 200)
external_dens <- data.frame(
  theta   = theta_grid,
  density = exp(-2 * (1 - cos(theta_grid - 0.5)))  # von Mises-like
)
ggplot() + coord_fixed() + add_circular_density(external_dens, fill = "steelblue")

Description

Estimates the circular density using density.circular (no distributional assumptions) and draws it as a closed polygon in the same Cartesian coordinate space used by radiate and add_angle_rose. Unlike add_vonmises_density, this makes no assumption about the shape of the distribution and handles multimodal data naturally.

Usage

add_circular_kde(
  hd,
  angle_col = "heading",
  group_col = NULL,
  bw = NULL,
  scale = 0.4,
  inner_r = 0,
  n_pts = 512L,
  kernel = "vonmises",
  colour = "tomato",
  linewidth = 0.8,
  fill = NA,
  alpha = 0.8,
  display = NULL,
  axial = FALSE,
  color = NULL
)

Arguments

Details

The bw parameter is a concentration parameter (analogous to $\kappa$ of the von Mises kernel) – larger values produce a sharper, data-following estimate; smaller values over-smooth towards uniform. NULL (default) selects bandwidth automatically via bw.nrd.circular.

Value

A geom_polygon layer, or NULL if estimation fails.

Examples

hd <- derive_headings(cpunctatus[1:10], rule = "distal")
radiate(cpunctatus[1:10]) + add_circular_kde(hd)

Description

Draws an inner reference circle at the critical mean resultant length – the smallest $\bar R$ at which a circular significance test reaches alpha for the given sample size. If a group's mean-direction arrow (add_heading_arrow) extends beyond this circle, that group's headings are significantly directed at the alpha level. This is the convention used by Oriana and similar circular-statistics software.

Usage

add_critical_r(
  hd,
  alpha = 0.05,
  test = c("rayleigh", "vtest"),
  angle_col = "heading",
  facets = NULL,
  group_col = NULL,
  colour = "firebrick",
  linetype = "dashed",
  linewidth = 0.6,
  n_pts = 200L
)

Arguments

Details

Two tests are supported:

"rayleigh" (default)

Tests against uniformity with no hypothesised direction. Critical value $\bar R_{crit} = \sqrt{-\log(\alpha) / n}$ (asymptotic; accurate for $n \ge 10$).

"vtest"

Tests against a specific direction. Critical value $\bar R_{crit} = z_\alpha / \sqrt{2n}$ at its most powerful (when the observed mean direction equals the hypothesised $\mu_0$); the effective threshold rises as the observed direction departs from $\mu_0$, so this circle is a lower bound.

Sample size n is taken per occupied cell from hd. Pass the same column(s) to facets as you pass to radiate(rows=)/radiate(cols=) so one circle is drawn per panel at the radius appropriate to that panel's n. Pass group_col to split each cell further by colour.

Value

A geom_path layer, or NULL if no group has n >= 2.

See Also

add_heading_arrow, add_circ

Examples

hd <- derive_headings(cpunctatus[1:10], rule = "distal")
radiate(cpunctatus[1:10]) +
  add_heading_arrow(hd) +
  add_critical_r(hd)

Description

Draws the decision boundary for the Rayleigh V test against a specified direction mu0. Unlike the Rayleigh test (a circle, see add_critical_r), the V test privileges one direction, so its boundary is a straight line perpendicular to mu0 at distance $c = z_\alpha / \sqrt{2n}$ from the centre. A mean-direction arrow (add_heading_arrow) is V-significant if and only if its tip falls on the far side of this line – equivalently, if its projection onto mu0 exceeds $c$.

Usage

add_critical_v_line(
  hd,
  mu0,
  alpha = 0.05,
  angle_col = "heading",
  facets = NULL,
  group_col = NULL,
  show_region = FALSE,
  colour = "firebrick",
  linetype = "dashed",
  linewidth = 0.6,
  region_fill = "firebrick",
  region_alpha = 0.08,
  axial = FALSE,
  n_pts = 100L
)

Arguments

Details

The line is clipped to the unit circle (drawn as a chord). With show_region = TRUE the circular segment beyond the line – the rejection region – is shaded.

Sample size n is taken per boundary from hd: one boundary per occupied combination of facets and group_col columns, or a single pooled boundary when both are NULL.

Value

A list of ggplot2 layers, or NULL if no group has a boundary inside the unit circle.

See Also

add_critical_r, add_heading_arrow

Examples

hd <- derive_headings(cpunctatus[1:10], rule = "distal")
radiate(cpunctatus[1:10]) +
  add_heading_arrow(hd) +
  add_critical_v_line(hd, mu0 = 0)

Description

Convenience wrapper that calls [compute_circ_mean()] followed by [add_circ_mean()]. Use the two-step form directly when you need to inspect or modify the summary data frame before rendering.

Usage

add_heading_arrow(
  headings_df,
  heading_col = "heading",
  colour_col = NULL,
  display = NULL,
  linewidth = 1,
  colour = NULL,
  arrow_length_cm = 0.2,
  axial = FALSE,
  ...,
  color_col = NULL,
  color = NULL
)

Arguments

Value

A 'geom_segment()' layer.

See Also

[compute_circ_mean()], [add_circ_mean()]

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ() +
  add_heading_arrow(hd)

Description

Convenience wrapper that calls [compute_circular_density()] followed by [add_circular_density()]. Equivalent to: “'r add_circular_density( compute_circular_density(headings_df, heading_col, colour_col, method, ...), colour_col = colour_col, scale = scale, ... ) “'

Usage

add_heading_density(
  headings_df,
  heading_col = "heading",
  colour_col = NULL,
  method = c("vonmises", "kernel", "histogram"),
  n_theta = 500L,
  bins = 36L,
  bw = NULL,
  boot_reps = 0L,
  boot_alpha = 0.05,
  scale = 0.4,
  colour = "black",
  fill = NA,
  alpha = 0.2,
  linewidth = 0.8,
  ci_fill = "grey70",
  ci_alpha = 0.3,
  axial = FALSE,
  color_col = NULL,
  color = NULL
)

Arguments

Details

Use [compute_circular_density()] + [add_circular_density()] directly when you need to inspect or replace the density values before plotting (e.g. to substitute a Bayesian posterior predictive density from 'brms').

Value

A list of one or two ggplot2 layers.

See Also

[compute_circular_density()], [add_circular_density()]

Examples

library(ggplot2)
hd <- data.frame(heading = c(0.2, 0.3, 0.4, 0.5, -0.1, 0.1, 0.6, 0.2))
ggplot() + coord_fixed() + add_heading_density(hd, fill = "steelblue", scale = 0.5)

Description

Convenience wrapper that calls [compute_circ_interval()] followed by [add_circ_interval()]. Use [compute_circ_interval()] + [add_circ_interval()] directly when you need to replace 'lower'/'upper' with Bayesian credible interval bounds before rendering.

Usage

add_heading_interval(
  headings_df,
  heading_col = "heading",
  facets = NULL,
  group_col = NULL,
  display = NULL,
  stat = c("bootstrap_ci", "sd"),
  boot_reps = 1000L,
  boot_alpha = 0.05,
  radius = 1.05,
  linewidth = 1.5,
  colour = NULL,
  linetype = "solid",
  n_theta = 500L,
  axial = FALSE,
  color = NULL
)

Arguments

Value

A 'geom_path()' layer.

See Also

[compute_circ_interval()], [add_circ_interval()]

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ() +
  add_heading_interval(hd, stat = "sd")

Description

Draws a hollow circle at '(cos(heading), sin(heading))' for each row of a headings data frame, placing one marker per trajectory on the unit-circle boundary at the derived heading direction. The data frame is normally the output of [derive_headings()].

Usage

add_heading_points(
  headings_df,
  colour_col = NULL,
  colour = NULL,
  size = 2,
  alpha = 1,
  axial = FALSE,
  color_col = NULL,
  color = NULL
)

Arguments

Value

A 'geom_point()' layer (shape = 1, hollow circle).

American spellings

Every 'colour...' argument and the 'assign_colour_*' / 'cycle_colours' / 'hf_colour_col' functions accept the American 'color...' spelling as an alias (e.g. 'color', 'color_col', 'track_color'). British spelling is canonical; supplying both spellings of a pair is an error.

See Also

[add_heading_vectors()], [derive_headings()]

Examples

library(ggplot2)
# headings from a Tracks via derive_headings(ts, rule = "crossing", ...)
hd <- data.frame(id = "A", time = 1, heading = pi / 4)
ggplot() + coord_fixed() + add_heading_points(hd)
ggplot() + coord_fixed() + add_heading_points(hd, colour = "steelblue")

Description

Draws a segment from the inner-radius crossing position to the heading endpoint on the unit circle for each row of a headings data frame. This visualises the extrapolated vector used to derive the heading and mirrors the dotted-line display in the original millipede tracking workflow.

Usage

add_heading_vectors(
  headings_df,
  colour_col = NULL,
  colour = NULL,
  linetype = "dotted",
  axial = FALSE,
  color_col = NULL,
  color = NULL
)

Arguments

Details

Requires columns 'heading', 'x_inner', and 'y_inner', which are present when [derive_headings()] is called with 'rule = "crossing"' and 'return_coords = TRUE'.

Value

A 'geom_segment()' layer.

See Also

[add_heading_points()], [derive_headings()]

Examples

library(ggplot2)
hd <- data.frame(id = "A", time = 1, heading = pi / 4,
                 x_inner = 0.15, y_inner = 0.15)
ggplot() + coord_fixed() + add_heading_vectors(hd)

Description

Draws a styled point just outside the rim at 'bearing', with a sun-like default (a gold asterisk), plus an optional text label. Change 'shape', 'colour'/'fill' and 'label' to mark any landmark (nest, feeder, light source). The bearing is given in **display units** (the value read off the axis), so the marker lands at the labelled position under any [circ_display()] convention.

Usage

add_landmark(
  bearing = 0,
  r = 1.12,
  shape = 8,
  size = 4,
  colour = "goldenrod",
  fill = "gold",
  label = NULL,
  display = circ_display(),
  ...,
  color = NULL
)

Arguments

Value

A list of ggplot layers: a 'geom_point()' layer, plus a 'geom_text()' layer when 'label' is supplied.

American spellings

Every 'colour...' argument and the 'assign_colour_*' / 'cycle_colours' / 'hf_colour_col' functions accept the American 'color...' spelling as an alias (e.g. 'color', 'color_col', 'track_color'). British spelling is canonical; supplying both spellings of a pair is an error.

See Also

[add_stimulus_arc()], [add_origin_point()]

Examples

library(ggplot2)
ggplot() + coord_fixed() + add_circ() +
  add_landmark(bearing = 45, label = "sun")

Description

This function creates a list of layers for concentric circles with specified radii that can be added to a ggplot object. The function takes optional arguments to customize the appearance of the circles.

Usage

add_multiple_circles(
  radii = c(0.25, 0.5, 0.75),
  circle_colour = "grey20",
  circle_alpha = 1,
  circle_size = 0.5,
  circle_color = NULL
)

Arguments

Value

A list of layers for concentric circles

Examples

library(ggplot2)
ggplot() + coord_fixed() + add_multiple_circles()

Description

Adds a single point at the origin '(0, 0)' – a centre reference for sparse themes where no crosshairs meet at the middle.

Usage

add_origin_point(colour = "grey50", size = 1.5, shape = 16, ..., color = NULL)

Arguments

Value

A 'geom_point()' layer.

Examples

library(ggplot2)
ggplot() + coord_fixed() + add_circ() + add_origin_point()

Description

Draws two dashed lines through the centre of the unit circle – one horizontal (0degrees/180degrees) and one vertical (90degrees/270degrees) – dividing the unit circle into four quadrants. The lines extend to the circumference (unit circle).

Usage

add_quadrant_lines(
  colour = "grey60",
  linewidth = 0.5,
  linetype = "dashed",
  color = NULL
)

Arguments

Value

A 'geom_segment()' layer.

Examples

library(ggplot2)
ggplot() + coord_fixed() + add_quadrant_lines()

Description

Returns a list of layers – an optional filled disc, concentric rings, and radial spokes, in two weights (major/minor) – to compose onto a radial 'radiate()' plot with '+'. The unit boundary (radius 1) is left to the circumference ([add_circ()]); grid rings are interior only.

Usage

add_radial_grid(
  rings_major = 0.5,
  rings_minor = c(0.25, 0.75),
  spokes_major = 4L,
  spokes_minor = 4L,
  colour = "grey92",
  colour_minor = NULL,
  linewidth = 0.5,
  linewidth_minor = NULL,
  linetype = "solid",
  disc_fill = NA,
  origin = FALSE,
  origin_colour = "grey50",
  origin_size = 1.5,
  n_pts = 200L,
  color = NULL,
  color_minor = NULL,
  origin_color = NULL
)

Arguments

Value

A list of ggplot2 layers.

See Also

[add_multiple_circles()], [add_quadrant_lines()], [add_origin_point()]

Examples

library(ggplot2)
ggplot() + coord_fixed() +
  add_radial_grid(disc_fill = "grey92", colour = "white") +
  add_circ()

Description

Places one point per observation at its heading angle, stacking coincident angles radially to avoid overplotting. If stack_r is already a column in data (from a prior call to stack_headings), it is used as-is; otherwise stacking is computed internally.

Usage

add_stacked_headings(
  data,
  col = NULL,
  step = 0.025,
  start_sep = step/2,
  tol = NULL,
  direction = "inward",
  base_r = 1,
  shade = FALSE,
  shape = FALSE,
  group = NULL,
  colour = "black",
  colour_col = NULL,
  size = 2,
  alpha = 1,
  axial = FALSE,
  ...,
  color = NULL,
  color_col = NULL
)

Arguments

Value

A geom_point() layer.

See Also

headings_frame, stack_headings, add_heading_points

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ() +
  add_stacked_headings(hd)

Description

Draws a filled ribbon on the rim of the unit circle, spanning 'width' in angular extent centred on 'bearing', depicting a dark bar or spot stimulus in an orientation arena. A wide 'width' reads as a bar; a narrow 'width' as a spot. The bearing is given in **display units** (the value read off the axis), so the arc lands at the labelled position under any [circ_display()] convention.

Usage

add_stimulus_arc(
  bearing = 0,
  width = 20,
  thickness = 0.05,
  r = 1,
  fill = "black",
  colour = NA,
  alpha = 1,
  display = circ_display(),
  color = NULL
)

Arguments

Value

A list containing one 'ggplot2::annotate("polygon")' layer.

American spellings

Every 'colour...' argument and the 'assign_colour_*' / 'cycle_colours' / 'hf_colour_col' functions accept the American 'color...' spelling as an alias (e.g. 'color', 'color_col', 'track_color'). British spelling is canonical; supplying both spellings of a pair is an error.

See Also

[add_landmark()], [add_circ()]

Examples

library(ggplot2)
ggplot() + coord_fixed() + add_circ() +
  add_stimulus_arc(bearing = 90, width = 30)

Description

Generates a 'geom_segment()' layer containing 'n' evenly spaced tick marks around the unit circle, each spanning a radial distance of 'length' straddling radius 1. The layer can be added to any ggplot.

Usage

add_ticks(
  colour = "black",
  linewidth = 0.5,
  length = 0.1,
  n = 8L,
  color = NULL
)

Arguments

Value

A 'geom_segment()' layer.

Examples

library(ggplot2)
ggplot() +
  coord_fixed() +
  add_ticks()

Description

Evaluates the von Mises probability density on a fine angular grid and draws it as a closed polygon in the same Cartesian coordinate space used by radiate and add_angle_rose. The curve peaks at scale so the two layers align when given matching scale values.

Usage

add_vonmises_density(
  fit,
  scale = 0.4,
  inner_r = 0,
  group_col = NULL,
  n_pts = 360L,
  colour = "steelblue",
  linewidth = 0.8,
  fill = NA,
  alpha = 0.8,
  display = NULL,
  axial = FALSE,
  color = NULL
)

Arguments

Value

A geom_polygon layer, or NULL if fit is all NA.

Examples

hd <- derive_headings(cpunctatus[1:10], rule = "distal")
fit <- vonmises_fit(hd)
radiate(cpunctatus[1:10]) + add_vonmises_density(fit)

Description

Evaluates dwrappedcauchy on a fine angular grid and draws it as a closed polygon in the same Cartesian space as radiate. Intended as a visual companion to add_vonmises_density: overlaying both curves shows whether the data favour the lighter-tailed von Mises or the heavier-tailed wrapped Cauchy.

Usage

add_wrappedcauchy_density(
  fit,
  scale = 0.4,
  inner_r = 0,
  group_col = NULL,
  n_pts = 360L,
  colour = "darkorange",
  linewidth = 0.8,
  fill = NA,
  alpha = 0.8,
  display = NULL,
  axial = FALSE,
  color = NULL
)

Arguments

Details

Default colour is "darkorange" to distinguish from add_vonmises_density ("steelblue") and add_circular_kde ("tomato").

Value

A geom_polygon layer, or NULL if estimation fails.

See Also

add_vonmises_density, add_circular_kde

Examples

hd <- derive_headings(cpunctatus[1:10], rule = "distal")
fit <- wrappedcauchy_fit(hd)
radiate(cpunctatus[1:10]) + add_wrappedcauchy_density(fit)

Description

The signed rate of change of travel direction at each point – how fast, and which way, the trajectory is turning. Positive is counter-clockwise (a left turn). Each interior point's turn (the angle between its incoming and outgoing step) is divided by the centred time step; the first and last point of every trajectory are 'NA'.

Usage

angular_velocity(
  ts,
  units = c("radians", "degrees"),
  x_col = ts@cols$x,
  y_col = ts@cols$y
)

Arguments

Details

Numeric (frame) time requires a frame rate ([set_frame_rate()]); POSIXct time is used directly. The result is scale-free (an angle), so no distance calibration is applied.

Value

A numeric vector, one value per observation in 'ts@data' order, 'NA' at each trajectory's first and last point.

See Also

[velocity_vector()], [instantaneous_speed()], [frame_rate()]

Examples

summary(angular_velocity(cpunctatus, units = "degrees"))

Description

Applies a user-supplied function to a loaded ['Tracks'] – for example a reference-frame correction or an angular remapping – after loading and before summary or plotting, returning a modified 'Tracks' and recording the step in its [‘transform_history']. The function is written against the 'Tracks'’s column roles ('x@cols'), not hard-coded column names.

Usage

apply_transform(x, fn, ..., by = c("trajectory", "all"), step = NULL)

Arguments

Value

A ['Tracks'] with '@data' replaced by the transformed result and one step appended to its 'transform_history'.

See Also

[transform_history()], [log_transform()]

Examples

data(cpunctatus)

# Recipe A -- a reference-frame offset (e.g. edge-referenced -> centre-
# referenced stimulus) is a frame change, so use set_reference(), not
# apply_transform(): it re-derives rel_theta/rel_x/rel_y consistently. Because
# rel_theta = abs - reference, offsetting the heading by +half (half the
# stimulus's angular width) is a reference change of (reference - half).
ts     <- set_reference(cpunctatus, 0)        # ensure a reference exists
half   <- (20 / 2) * pi / 180                 # a 20-degree-wide stimulus
newref <- reference(ts)$ref_theta - half      # per-trajectory if widths differ
ts2    <- set_reference(ts, stats::setNames(newref, reference(ts)$id))

# Recipe B -- polarization direction -> axis. Polarized-light e-vectors are
# axial (defined mod pi); doubling folds direction into orientation for axial
# circular statistics. (Doubling remaps the angular space, so rel_x/rel_y are
# not physical positions afterwards -- use it for the angle/stat path.)
direction_to_axis <- function(df, cols) {
  df[[cols$angle]] <- (2 * df[[cols$angle]]) %% (2 * pi)
  df
}
ts_axial <- apply_transform(cpunctatus, direction_to_axis, by = "all",
                            step = "direction_to_axis")

Description

Converts a vector of timestamps, dates, or a generic periodic numeric into unit-circle angles in radians ('[0, 2*pi)'), so periodic data — events by time of day (chronobiology) or time of year (phenology) — can be analysed and drawn with the circular tools ('circ_summary()', 'vonmises_fit()', 'radiate()', the distribution overlays). It is the data-side counterpart of the [circumference_labs()] / [scale_clock()] / [scale_months()] labels: the cycle start is placed at the top and time increases clockwise, so a '06:00' timestamp lands exactly on the '"6"' hours label and the 1st of each month on its month label.

Usage

as_angle(x, period)

Arguments

Value

A 'numeric' vector of angles in radians ('[0, 2*pi)'), the same length as 'x'; 'NA' entries propagate. Wrap it with [headings_frame()] (or use it as a 'heading' column) to feed the circular tools.

See Also

[circumference_labs()], [scale_clock()], [scale_months()], [headings_frame()], [circ_summary()], [radiate()]

Examples

# events through a day -> a clock-face circular distribution
set.seed(1)
times <- as.POSIXct("2020-06-01", tz = "UTC") +
  rnorm(200, mean = 9 * 3600, sd = 2 * 3600)        # clustered around 09:00
ang <- as_angle(times, "day")
circ_summarise(data.frame(heading = ang), "heading", units = "radians")

# a generic numeric cycle of length 10
as_angle(c(0, 2.5, 5, 7.5), period = 10)

Description

Returns the long-form trajectory table held in the Tracks's 'data' slot.

Usage

## S3 method for class 'Tracks'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Details

Registered as an S3 method so that 'as.data.frame(ts)' dispatches correctly from any caller. (A bare S4 method on the base S3 generic is only reached from within the package's own namespace, not from user code using the installed package.)

Value

A data frame: the Tracks's 'data' slot.

Examples

head(as.data.frame(cpunctatus))

Description

Writes a colour-key column ('into', default '".colour"') keyed on 'by', so the tracks and any overlays drawn on top share one colour scale. Two modes are chosen automatically by cardinality: * **Cycled** – 'by = "trajectory"' (the trajectory id column), or any column with more than 'n' levels: the key is a cycled '1:n' index ([cycle_colours()]), so a high-cardinality key stays legible. * **Distinct** – a column with 'n' or fewer levels: the key holds the column's raw values (as a factor), so a legend is meaningful.

Usage

assign_colour_key(x, by, n = 20, reference = NULL, into = ".colour")

assign_color_key(x, by, n = 20, reference = NULL, into = ".colour")

Arguments

Details

Pass 'reference' (another Tracks or frame sharing the key) to borrow its level order, so a given key value gets the same colour in both – e.g. tracks and their heading markers. If 'by' names a column absent from 'x' but present on 'reference', it is borrowed by matching trajectory id.

Value

'x' with the 'into' column added.

American spellings

Every 'colour...' argument and the 'assign_colour_*' / 'cycle_colours' / 'hf_colour_col' functions accept the American 'color...' spelling as an alias (e.g. 'color', 'color_col', 'track_color'). British spelling is canonical; supplying both spellings of a pair is an error.

See Also

[cycle_colours()]

Examples

ts <- simulate_tracks(n_points = 10, output = "trajset")
ts <- assign_colour_key(ts, by = "trajectory")

Description

Creates a factor column that assigns each unique trajectory a colour index in the range '1:n', cycling back to 1 after every 'n' trajectories. When 'panel_col' is supplied the cycle resets independently within each panel so that trajectory 1 in every panel gets index 1.

Usage

assign_cycle_colours(
  data,
  id_col,
  n,
  panel_col = NULL,
  out_col = "cycle_colour"
)

assign_cycle_colors(data, id_col, n, panel_col = NULL, out_col = "cycle_colour")

Arguments

Details

The resulting column can be passed to 'colour_col' in [radiate()], [add_heading_points()], or [add_heading_vectors()] to keep colours consistent across layers.

Value

'data' with an additional factor column named 'out_col' (levels '"1"' through '"n"').

Examples

df <- data.frame(id = paste0("T", 1:12), panel = rep(c("A","B"), each = 6))
df <- assign_cycle_colours(df, id_col = "id", n = 4, panel_col = "panel")
table(df$panel, df$cycle_colour)

Description

Bins angles (in radians) into fixed-width sectors and returns each angle snapped to its bin's centre. Snapping coincident-binned angles to a common value is the standard precursor to a stacked dot plot: feed the result to stack_headings (with the default tol = NULL) to build clean radial columns.

Usage

bin_angles(angles, width, phase = 0)

Arguments

Value

A numeric vector the same length as angles, each value snapped to its bin centre and wrapped to [0, 2 * pi).

See Also

stack_headings, add_stacked_headings

Examples

# 5-degree bins centred on the reference direction
bin_angles(c(0.01, 0.10, 0.11), width = pi / 36)
# circular-package style (edge-aligned) bins
bin_angles(c(0.01, 0.10, 0.11), width = pi / 36, phase = pi / 72)

Description

Computes nonparametric bootstrap confidence intervals for the concentration of each group, for both the von Mises maximum-likelihood concentration $\kappa$ and the mean resultant length $R$. Angles are resampled with replacement and the interval is the percentile envelope of the bootstrap estimates. Unlike the normal-approximation se_kappa from vonmises_fit, it makes no distributional assumption and stays usable at low concentration or small sample size, where that approximation is unreliable and where $\hat\kappa$/$\hat R$ carry a known upward bias.

Usage

boot_kappa_ci(
  hd,
  group_col = NULL,
  angle_col = "heading",
  conf = 0.95,
  R = 999L,
  axial = FALSE
)

Arguments

Details

The kappa_bias/R_bias columns report the bootstrap estimate of that bias (bootstrap mean minus the sample estimate); the intervals themselves are the raw percentile envelope and are not bias-shifted.

Value

Data frame with columns group_col (if supplied), kappa (von Mises MLE concentration), kappa_ci_lo/kappa_ci_hi (conf-level percentile CI on $\kappa$), kappa_bias, resultant_R (mean resultant length in $[0,1]$), R_ci_lo/R_ci_hi, R_bias, and n. Groups with fewer than two finite angles yield an all-NA row.

See Also

boot_mean_ci, boot_kappa_contrast, vonmises_fit, circ_dispersion, test_concentration

Examples

hd <- derive_headings(cpunctatus, rule = "distal", carry = "arc")
set.seed(1)
boot_kappa_ci(hd, group_col = "arc", R = 199)

Description

Contrasts the concentration of two (or more) groups via a stratified nonparametric bootstrap: angles are resampled with replacement within each group independently, and the contrast is recomputed on every resample. For a pair of groups it reports the difference in von Mises concentration ($\Delta\kappa$), the concentration ratio ($\kappa_1/\kappa_2$), and the difference in mean resultant length ($\Delta R$), each with a percentile confidence interval, plus a two-sided bootstrap p-value for $\Delta\kappa = 0$. It is the assumption-light, estimation-focused companion to test_concentration (parametric equal.kappa / non-parametric Wallraff).

Usage

boot_kappa_contrast(
  hd,
  group_col,
  angle_col = "heading",
  conf = 0.95,
  R = 999L,
  axial = FALSE
)

Arguments

Details

The concentration ratio is skewed and can be unstable or non-finite when the denominator concentration is near zero; $\Delta\kappa$ is the more robust default in the low-concentration regime.

Value

Data frame with one row per group pair: group1, group2, delta_kappa, delta_kappa_ci_lo/delta_kappa_ci_hi, kappa_ratio, kappa_ratio_ci_lo/kappa_ratio_ci_hi, delta_R, delta_R_ci_lo/delta_R_ci_hi, p_value (two-sided bootstrap p for $\Delta\kappa = 0$), n1, n2.

See Also

boot_kappa_ci, test_concentration

Examples

hd <- derive_headings(cpunctatus, rule = "distal", carry = "type")
set.seed(1)
boot_kappa_contrast(hd, group_col = "type", R = 199)

Description

Computes a nonparametric bootstrap confidence interval for the mean direction of each group, resampling angles with replacement and taking the percentiles of the bootstrap mean directions (centred on the sample mean). Unlike the normal-approximation interval from vonmises_fit, it makes no distributional assumption and stays usable at low concentration or small sample size, where that approximation is unreliable.

Usage

boot_mean_ci(
  hd,
  group_col = NULL,
  angle_col = "heading",
  conf = 0.95,
  R = 999L,
  axial = FALSE
)

Arguments

Value

Data frame with columns group_col (if supplied), mu (mean direction, radians), mu_deg (degrees), ci_lo and ci_hi (conf-level bootstrap interval on mu, radians; bounds may fall outside $[0, 2\pi)$ to describe an arc), resultant_R, and n. Groups with fewer than two finite angles yield an all-NA interval.

See Also

vonmises_fit, circ_dispersion

Examples

hd <- derive_headings(cpunctatus, rule = "distal", carry = "arc")
set.seed(1)
boot_mean_ci(hd, group_col = "arc", R = 199)

Description

Computes the five-number summary and fences of a circular boxplot following Buttarazzi, Pandolfo & Porzio (2018): observations are depth-ranked outward from the antimedian, the box spans the central ~50 the median), and the fence multiplier is obtained in closed form from the von Mises quantiles at the sample's estimated concentration (so ~0.7 observations are flagged as far-out under that reference). Pairs with [add_circular_boxplot()] for rendering.

Usage

circ_boxplot_stats(hd, angle_col = "heading", axial = FALSE)

Arguments

Value

A list with 'median', 'antimedian', 'hinges', 'box_arc', 'constant', 'kappa', 'fences', 'whiskers', 'far_out' (all radians, unit-circle convention), 'n', 'axial', 'drawable', and 'reason'. When 'drawable' is 'FALSE' (non-unique median or 'n < 4') the location fields are 'NA'; 'reason' may also carry a non-fatal advisory while 'drawable' remains 'TRUE' (near-uniform data).

Source

Algorithm reimplemented from the bpDir package.

References

Buttarazzi, D., Pandolfo, G. & Porzio, G. C. (2018). A boxplot for circular data. Biometrics 74(4), 1492–1501. doi:10.1111/biom.12889

See Also

[add_circular_boxplot()], [circ_summarise()], [vonmises_fit()]

Examples

tr <- simulate_tracks(output = "trajset", seed = 1)
hd <- derive_headings(tr, rule = "distal")
circ_boxplot_stats(hd)

Description

Computes the association between a heading (angle) series and either a continuous linear covariate (x_type = "linear", default) or a second set of angles (x_type = "circular").

Usage

circ_cor(
  hd,
  x_col,
  angle_col = "heading",
  group_col = NULL,
  x_type = c("linear", "circular"),
  test = TRUE
)

Arguments

Details

Circular-linear (T-linear association, Mardia and Jupp 2000):

$r^2 = (r_{cx}^2 + r_{cy}^2 - 2 r_{cx} r_{cy} r_{xy}) / (1 - r_{xy}^2)$

where $r_{cx}$, $r_{cy}$, and $r_{xy}$ are the Pearson correlations of $x$ with $\cos\theta$ and $\sin\theta$, and of $\cos\theta$ with $\sin\theta$. $r$ lies in $[0, 1]$; the test statistic $n r^2$ is approximately chi-squared with 2 degrees of freedom under the null. Note: $r$ is unsigned (association strength only, not direction).

Circular-circular (Fisher's $\rho$, via cor.circular): $r \in [-1, 1]$.

Value

Tidy data frame with columns group_col (if supplied), r, n, type, and when test = TRUE also statistic, df, p_value.

Examples

hd <- derive_headings(cpunctatus, rule = "distal")
# does the heading depend on the frame at which it was taken?
circ_cor(hd, x_col = "time")

Description

Computes circular mean direction, mean resultant length R, circular standard deviation, and sample size for each group. Designed for within-trial summaries from pose_to_headings or derive_headings(..., rule = "bodypart_axis", frame_select = "all"), but accepts any data frame with an angle column.

Usage

circ_dispersion(hd, group_col = NULL, angle_col = "heading", axial = FALSE)

Arguments

Value

Data frame with columns group_col (if supplied), mean_dir, resultant_R, circ_sd, n. Circular standard deviation is $\sqrt{-2 \log R}$.

Examples

hd <- derive_headings(cpunctatus, rule = "distal", carry = "arc")
circ_dispersion(hd, group_col = "arc")

Description

Describes how unit-circle radian angles are rendered in plots and tables. Pass to any display function as the 'display' argument.

Usage

circ_display(zero = pi/2, clockwise = TRUE, units = c("degrees", "radians"))

Arguments

Value

A 'circ_display' list.

Examples

# Default: North at top, clockwise, degrees
circ_display()

# Stimulus at East should appear at top
circ_display(zero = 0)

# Counterclockwise, radians
circ_display(clockwise = FALSE, units = "radians")

Description

Fits five candidate models to a heading sample and ranks them by the small-sample-corrected Akaike information criterion (AICc):

uniform

no preferred direction (k = 0).

unimodal

one von Mises mode (k = 2).

axial

symmetric bimodal von Mises, two equal antipodal modes (k = 2).

unimodal_uniform

a directed von Mises mode over a uniform background, $p\,vM(\mu,\kappa) + (1-p)\,U$ (k = 3).

bimodal

an asymmetric two-component von Mises mixture with free means, concentrations, and weight (k = 5).

The mixture models (unimodal_uniform, bimodal) are fitted by numerical maximum likelihood; the other three are closed-form. This model set mirrors the Schnute-Groot family implemented by the CircMLE package (Fitak & Johnsen 2017): uniform = M1, unimodal = single von Mises, axial = symmetric bimodal, unimodal_uniform = a directed component over a uniform background, and bimodal = a free two-component mixture.

Usage

circ_model_select(hd, angle_col = "heading", group_col = NULL)

Arguments

Details

Parameters for uniform, unimodal, and axial are estimated with vonmises_fit (the axial model via its axial = TRUE doubled-angle fit) and likelihoods with the circular package densities. The table reports model comparison only; obtain the fitted parameters of a chosen model from vonmises_fit.

Value

Tidy data frame, one row per candidate model (five rows, or five per group when group_col is supplied), sorted by AICc ascending (best first; NA last). Columns: group_col (if supplied), model, n, k (free parameters), logLik, AIC, AICc, BIC, dAICc (AICc minus the group minimum), and weight (Akaike weight). AICc/weight are NA for a model whose fit failed or when n - k - 1 <= 0; remaining weights sum to 1.

References

Burnham, K.P. & Anderson, D.R. (2002). Model Selection and Multimodel Inference, 2nd ed. Springer.

Schnute, J.T. & Groot, K. (1992). Statistical analysis of animal orientation data. Animal Behaviour, 43(1), 15-33.

Fitak, R.R. & Johnsen, S. (2017). Bringing the analysis of animal orientation data full circle: model-based approaches with maximum likelihood. Journal of Experimental Biology, 220(21), 3878-3882.

See Also

vonmises_fit, test_uniformity

Examples

hd <- derive_headings(cpunctatus, rule = "distal", carry = "arc",
                      coords = "relative")
# Control (no stimulus) against the widest arc
circ_model_select(hd[hd$arc %in% c("0", "50"), ], group_col = "arc")

Description

Fits the Fisher-Lee circular-linear regression $\theta_i \sim \mathrm{vM}(\mu_0 + 2\arctan(x_i'\beta), \kappa)$ via lm.circular (type = "c-l"), behind a formula interface. The response is a heading in radians (unit-circle convention); the right-hand side supplies one or more linear covariates (factors and interactions are expanded by model.matrix).

Usage

circ_regression(data, formula, init = NULL)

## S3 method for class 'circ_regression'
summary(object, conf.level = 0.95, ...)

## S3 method for class 'circ_regression'
predict(object, newdata = NULL, ...)

## S3 method for class 'circ_regression'
fitted(object, ...)

## S3 method for class 'circ_regression'
print(x, ...)

Arguments

Value

An S3 object of class "circ_regression". Use summary() for a tidy coefficient data frame, predict() / fitted() for fitted mean angles, and print() for a compact report. On non-convergence or too few rows, converged is FALSE and the coefficients are NA.

References

Fisher, N. I. & Lee, A. J. (1992). Regression models for an angular response. Biometrics 48, 665-677. Mardia, K. V. & Jupp, P. E. (2000). Directional Statistics. Wiley.

See Also

circ_cor, vonmises_fit, simulate_tracks

Examples

# Headings whose mean turns with x: mu0 = 1, slope 1.5
set.seed(1)
x <- runif(60, -1, 1)
noise <- as.numeric(circular::rvonmises(60, circular::circular(0), kappa = 8))
hd <- data.frame(x = x, heading = (1 + 2 * atan(1.5 * x) + noise) %% (2 * pi))
fit <- circ_regression(hd, heading ~ x)
fit
summary(fit)
predict(fit, newdata = data.frame(x = c(-1, 0, 1)))

Description

Computes circular summary statistics from a data frame column of angles. Supports grouped tibbles and an explicit .by argument, returning one row per group. Output mean_dir is always in radians (unit-circle convention); mean_dir_deg is that direction in degrees in the display convention (by default 0 = North, clockwise), so it is not mean_dir * 180 / pi.

Usage

circ_summarise(
  data,
  col,
  units,
  .by = NULL,
  axial = FALSE,
  stats = c("n", "mean_dir", "mean_dir_deg", "resultant_R", "kappa"),
  display = circ_display()
)

Arguments

Value

An ungrouped tibble with group columns first followed by requested stat columns in the order given in stats.

Examples

hd <- data.frame(heading = c(0, pi/4, pi/2), arc = c("a", "a", "b"))
circ_summarise(hd, heading, units = "radians")
circ_summarise(hd, heading, units = "radians", .by = "arc")
circ_summarise(hd, heading, units = "radians", .by = "arc",
               stats = c("n", "mean_dir"))

Description

Computes per-trial or global circular statistics (mean direction, resultant length, concentration) from the step-angle column of a 'Tracks'.

Usage

circ_summary(x, w = NULL, by = c("id", "global"), axial = FALSE)

## S4 method for signature 'Tracks'
circ_summary(x, w = NULL, by = c("id", "global"), axial = FALSE)

Arguments

Value

A 'data.frame' with columns 'id', 'n', 't_start', 't_end', 'mean_dir' (radians, unit-circle convention, 0 to 2pi; weighted when weights are used), 'resultant_R' (0–1), and 'kappa' (von Mises concentration: the maximum-likelihood estimate from the mean resultant length, weighted when weights are used; 'NA' for fewer than three valid angles of positive weight, 'Inf' when all angles coincide). 'n' counts the valid angles whatever their weight. No small-sample bias correction is applied, so kappa is biased upward for small n: circular::mle.vonmises(bias = TRUE) gives a corrected estimate and boot_kappa_ci() reports the bias.

Examples

data(cpunctatus)
head(circ_summary(cpunctatus, by = "id"))
circ_summary(cpunctatus, by = "global")

Description

Derives one heading per trial via 'derive_headings()', then computes circular summary statistics (mean direction, resultant length, concentration) optionally grouped by one or more metadata columns.

Usage

circ_summary_headings(x, rule, group_by = "id", ...)

Arguments

Value

A 'data.frame' with grouping columns followed by 'mean_dir' (radians, unit-circle convention, 0 to $2\pi$), 'resultant_R' (0–1), 'kappa' (von Mises concentration, with no small-sample bias correction; see circ_summary()), and 'n' (number of valid headings in the group).

Examples

data(cpunctatus)
# per-trial headings (default)
head(circ_summary_headings(cpunctatus, rule = "crossing",
                           circ0 = 0.2, circ1 = 0.4))

# per-condition summary: carry the "arc" column through to group by it
circ_summary_headings(cpunctatus, rule = "crossing",
                      circ0 = 0.2, circ1 = 0.4,
                      carry = "arc", group_by = "arc")

Description

A collection of helpers for converting between Cartesian coordinates and unit-circle representations, including orientation conversions used throughout the package. Most functions are internal, but the angle wrapping helpers remain exported for backwards compatibility.

Description

Adds circumference text labels (cardinal directions, hours, months, seconds, or a custom scale) to a radial ggplot. The display-aware sibling of [degree_labs()]: labels are positioned through the supplied 'display' so they track the plotted data when the convention changes.

Usage

circumference_labs(
  scale,
  display = circ_display(),
  colour = "black",
  size = 3.88,
  family = "",
  radius = 0.85,
  color = NULL
)

Arguments

Value

A list of ggplot2 annotation layers, add to a plot with '+'.

See Also

[degree_labs()] for degree/radian labels; [scale_cardinal()], [scale_clock()], [scale_months()], [scale_seconds()].

Examples

library(ggplot2)
ggplot() +
  coord_fixed() +
  circumference_labs(scale_months())

Description

Returns a data frame of arc bounds centred on the circular mean direction. Two built-in statistics are available: a bootstrap confidence interval for the mean direction ('"bootstrap_ci"', via [circular::mle.vonmises.bootstrap.ci()]) and +/-1 circular SD ('"sd"', via [circular::sd.circular()]). The 'lower' and 'upper' columns of the output can be replaced with Bayesian credible interval bounds from any model before passing to [add_circ_interval()].

Usage

compute_circ_interval(
  headings_df,
  heading_col = "heading",
  facets = NULL,
  group_col = NULL,
  stat = c("bootstrap_ci", "sd"),
  boot_reps = 1000L,
  boot_alpha = 0.05,
  axial = FALSE
)

Arguments

Value

A data frame with columns 'mean_dir', 'lower', 'upper' (radians, '[-pi, pi]'), and 'wraps' (logical, 'TRUE' when the arc crosses the +/-pi discontinuity). 'lower' and 'upper' are 'NA' when 'n < 3'.

See Also

[add_circ_interval()], [add_heading_interval()]

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
# Fast: +/-1 circular SD
compute_circ_interval(hd, stat = "sd")

Description

Computes the circular mean direction and resultant length (R) per group from a headings data frame, typically the output of [derive_headings()]. 'mean_dir' in the returned data frame is **always in unit-circle convention** (0 = East, counterclockwise), regardless of the input convention, making it suitable for direct use in [add_circ_mean()].

Usage

compute_circ_mean(
  headings_df,
  heading_col = "heading",
  facets = NULL,
  group_col = NULL,
  axial = FALSE
)

Arguments

Value

A data frame with columns 'mean_dir' (unit-circle radians, 0 to 2pi), 'resultant_R' (0–1), plus any 'facets'/'group_col' columns. Both statistics are 'NA' when a cell contains fewer than 2 finite angles.

See Also

[add_circ_mean()], [add_heading_arrow()]

Examples

hd <- derive_headings(cpunctatus[1:5], rule = "distal")
compute_circ_mean(hd)

Description

Evaluates a directional density for a set of heading angles and returns a tidy data frame of '(theta, density)' pairs. The result can be passed directly to [add_circular_density()] for rendering, or inspected and modified before plotting – for example to replace the 'density' column with a Bayesian posterior predictive density obtained from 'brms' or another modelling package.

Usage

compute_circular_density(
  headings_df,
  heading_col = "heading",
  colour_col = NULL,
  method = c("vonmises", "kernel", "histogram"),
  n_theta = 500L,
  bins = 36L,
  bw = NULL,
  boot_reps = 0L,
  boot_alpha = 0.05,
  axial = FALSE,
  color_col = NULL
)

Arguments

Details

Three built-in estimation methods are provided:

* '"vonmises"' – fit a von Mises distribution by MLE ([circular::mle.vonmises()]) and evaluate the fitted density on a regular grid of 'n_theta' angles. Bootstrap confidence bands are available via 'boot_reps'. * '"kernel"' – circular kernel density estimate ([circular::density.circular()]) with bandwidth chosen by [circular::bw.nrd.circular()] unless 'bw' is supplied. * '"histogram"' – angular bin counts (a circular rose diagram); 'bins' controls the number of bins.

When 'colour_col' is supplied the density is computed independently for each group and the group label is preserved in the output, enabling per-panel use with [radiate()]'s 'facets'.

When 'boot_reps > 0' and 'method = "vonmises"', a non-parametric bootstrap is run: 'boot_reps' samples are drawn with replacement, a von Mises MLE is fitted to each, and the density is evaluated on the same grid. The 'boot_alpha / 2' and '1 - boot_alpha / 2' quantiles across replicates are returned as 'density_lower' and 'density_upper' columns. These can be rendered as a confidence band by [add_circular_density()], or replaced with interval values from a Bayesian model before plotting.

Value

A data frame with columns 'theta' (radians, -pi to pi) and 'density' (non-negative), plus 'colour_col' if supplied. When 'boot_reps > 0' and 'method = "vonmises"', also includes 'density_lower' and 'density_upper'. Suitable for passing to [add_circular_density()].

See Also

[add_circular_density()], [add_heading_density()]

Examples

hd <- data.frame(heading = c(0.2, 0.3, 0.4, 0.5, -0.1, 0.1, 0.6, 0.2))
dens_df <- compute_circular_density(hd)
head(dens_df)

# Bootstrap CI band (vonmises only):
dens_df <- compute_circular_density(hd, boot_reps = 999L)
# density_lower / density_upper can be replaced with Bayesian interval values
# before passing to add_circular_density()

# Replace the density column with values from an external model before plotting:
# dens_df$density <- my_bayesian_density(dens_df$theta)
# ggplot() + coord_fixed() + add_circular_density(dens_df)

Description

Fits a von Mises model in which the concentration $\kappa$ varies with one or more covariates while the mean direction $\mu$ is a single constant: $\theta_i \sim \mathrm{vM}(\mu, \kappa_i)$ with $\kappa_i = h(x_i'\gamma)$ for an inverse link $h$. It is the concentration-regression complement to circ_regression (which models the mean with a constant concentration), and the estimator that pairs with simulate_tracks's concentration_slope. The model is fitted by maximum likelihood with optim.

Usage

concentration_regression(
  data,
  formula,
  link = c("log", "identity"),
  init = NULL
)

## S3 method for class 'concentration_regression'
summary(object, conf.level = 0.95, ...)

## S3 method for class 'concentration_regression'
predict(object, newdata = NULL, ...)

## S3 method for class 'concentration_regression'
fitted(object, ...)

## S3 method for class 'concentration_regression'
print(x, ...)

Arguments

Value

An S3 object of class "concentration_regression". Use summary() for a tidy coefficient data frame (link scale), predict() / fitted() for fitted $\kappa$ (response scale), and print() for a compact report. On non-convergence or too few rows, converged is FALSE and the coefficients are NA.

References

Mardia, K. V. & Jupp, P. E. (2000). Directional Statistics. Wiley.

See Also

circ_regression, boot_kappa_ci, test_concentration, simulate_tracks

Examples

# Does orientation sharpen as the stimulus arc widens?
hd <- derive_headings(cpunctatus, rule = "distal", carry = "arc",
                      coords = "relative")
hd$arc_deg <- as.numeric(as.character(hd$arc))
fit <- concentration_regression(hd, heading ~ arc_deg)
fit
summary(fit)
# Fitted kappa for a narrow, medium and wide arc
predict(fit, newdata = data.frame(arc_deg = c(5, 25, 50)))

Description

For each trial, counts the number of times the trajectory enters a circular zone of radius 'crossing_radius' centred on the goal location. Applicable to any circular-field analysis with a defined goal (e.g. the hidden platform in a water maze, a reward zone in an open-field).

Usage

count_goal_entries(
  x,
  target_angle,
  target_radius = 1,
  crossing_radius = 0.15,
  coords = c("absolute", "relative")
)

Arguments

Details

An "entry" is a 'FALSE -> TRUE' transition in the 'distance < crossing_radius' sequence (ordered by time). A trajectory that starts inside the zone on the first frame counts as one entry.

Value

A 'data.frame' with one row per trial: 'id' (character) and 'n_entries' (integer).

See Also

[zone_dwell()]

Examples

# Treat 45 degrees (NE) at the wall as the goal, as for a water maze probe
data(cpunctatus)
entries <- count_goal_entries(cpunctatus, target_angle = pi / 4,
                              crossing_radius = 0.15)
# n_entries > 1 indicates memory of the platform location
head(entries)

Description

Pre-processed 'Tracks' of 235 millipede trajectories from a visual-acuity experiment. *Cylindroiulus punctatus* individuals were placed at the centre of a cylindrical arena under bright, downwelling light, with a dark target of varying angular half-width on the arena wall, and their path tracked to test whether they oriented toward the target (object taxis). Eight stimulus conditions are represented: target half-widths of 5, 10, 15, 20, 30, 40, and 50 degrees, plus a featureless control ('arc = 0', an angular subtense of zero).

Usage

cpunctatus

Format

A ['Tracks'] object (44,331 observations) whose data columns include:

trial_id

Character. Unique trial identifier.

frame

Integer. Video frame number.

trans_x, trans_y

Numeric. Unit-circle Cartesian coordinates.

abs_theta

Numeric. Absolute bearing (radians).

rel_theta

Numeric. Bearing relative to the target direction.

rel_x, rel_y

Numeric. Target-relative unit-circle coordinates.

arc

Ordered factor. Target half-width in degrees ('0' < '5' < '10' < '15' < '20' < '30' < '40' < '50'; 0 = control).

type

Character. '"control"' or '"stimulus"'.

individual

Character. Animal identifier.

Details

These tracks are a **subset** of the full experiment; see Kirwan & Nilsson (2019) for the complete dataset and trial counts.

Coordinates are normalised to the unit circle (radius = 1) and rotated so the target lies in a common reference direction; 'rel_theta', 'rel_x', and 'rel_y' give the target-relative heading and position. The subject identifier is retained in the 'individual' column.

The raw dtrack landmark/track text files for every trial are shipped as one archive, 'inst/extdata/tracks.tar.gz' (unpack it with 'untar(system.file("extdata", "tracks.tar.gz", package = "radiatR"), exdir = tempdir())'), and the trial manifest in 'inst/extdata/millipede_trials.csv', so the full import pipeline can be reproduced with [get_all_object_pos()]. See 'data-raw/millipede_example.R'.

Source

Behavioural experiment from Kirwan & Nilsson (2019); raw tracks produced with dtrack and normalised with radiatR. A subset of the published dataset.

References

Kirwan, J. D., & Nilsson, D.-E. (2019). A millipede compound eye mediating low-resolution vision. *Vision Research*, 165, 36–44. doi:10.1016/j.visres.2019.09.003

Examples

cpunctatus
# One heading per trial (the bearing of its furthest point from the
# origin), keeping the target half-width
hd <- derive_headings(cpunctatus, rule = "distal", carry = "arc")
table(hd$arc)

Description

The order-stable primitive behind [assign_cycle_colours()] (and so [radiate()]'s 'colour_cycle'). Maps each value of 'x' to an index in '1:n', numbering the distinct values by 'levels' and wrapping back to '1' after every 'n'. Passing an explicit 'levels' lets two data frames that share a key (for example tracks and an overlay drawn on top of them) be coloured identically, so a given key value gets the same colour in both.

Usage

cycle_colours(x, n, levels = NULL)

cycle_colors(x, n, levels = NULL)

Arguments

Value

A factor the same length as 'x' with levels '"1"'..'"n"' giving the cycled colour index. 'NA' in 'x' is preserved as 'NA'.

See Also

[assign_cycle_colours()], [radiate()]

Examples

cycle_colours(c("a", "b", "c", "a"), n = 2)

Description

Provides a list of annotation layers that mark 45, 135, 225, and 315 degrees on a unit circle.

Usage

degree_labs(
  display = circ_display(),
  colour = "black",
  units = NULL,
  size = 3.88,
  family = "",
  position = c("outside", "inside", "split"),
  inside_radius = 0.88,
  n = NULL,
  outer_radius = NULL,
  color = NULL
)

Arguments

Value

A list of ggplot2 annotation layers.

Examples

library(ggplot2)
ggplot() +
  coord_fixed() +
  degree_labs()

Description

Given a unit-circle Cartesian position ('trans_x', 'trans_y') and a reference direction, computes the dependent coordinate columns: the radius, the absolute angle (unit-circle and clock conventions), and the reference-relative angle and Cartesian position. This is the single source of the unit-circle -> polar/relative transformation used across the package.

Usage

derive_coords(trans_x, trans_y, reference = 0)

Arguments

Value

A data frame with 'trans_rho', 'abs_theta_clock', 'abs_theta_unit', 'rel_theta_unit', 'rel_x', 'rel_y'.

See Also

[set_reference()], [reference()]

Examples

derive_coords(c(0.5, -0.3), c(0.2, 0.4), reference = pi / 2)

Description

Derive heading angle(s) from trajectories using specified rule

Usage

derive_headings(x, rule, ..., coords = c("absolute", "relative"))

## S4 method for signature 'Tracks'
derive_headings(
  x,
  rule,
  ...,
  first_only = FALSE,
  carry = NULL,
  on_missing = c("warn", "error", "quiet"),
  coords = c("absolute", "relative")
)

Arguments

Details

Passing 'return_coords = TRUE' (via '...', default 'FALSE') attaches the construction coordinates each rule used to derive the heading, in the chosen 'coords' frame: 'crossing' adds 'x_inner'/'y_inner'; 'distal' adds 'x_distal'/'y_distal'; 'net' adds 'x_start'/'y_start'/'x_end'/'y_end'; 'straight' adds 'x_seg0'/'y_seg0'/'x_seg1'/'y_seg1' (the run endpoints); 'pca_axis' adds 'x_centroid'/'y_centroid'/'axis_x'/'axis_y' (a unit axis vector). Other rules ignore it. The 'distal' rule accepts 'max_radius' (default 'Inf'): the furthest-point search is restricted to positions with radius '<= max_radius', so 'max_radius = 1' ignores beyond-circumference ('rho > 1') tracking outliers. The 'straight' rule takes 'tol' (default 'pi/18', the largest turn between successive steps) and 'min_len' (default '5', the fewest steps in a run). A step of zero length (a pause) has no direction: turns are measured between successive moving steps, so a pause neither breaks a run nor counts toward ‘min_len'. The heading is the direction of the run’s first moving step. 'pca_axis' takes 'source = "position"' (default; the principal axis of the positions about their centroid) or '"velocity"' (the principal axis of the steps about zero, which weights a step by its squared length; compare 'velocity_axis', which weights by length).

The rules that average directions take a weighting through ...:

• velocity_mean and vm_fit average the directions of the steps of a track. weight_by = "uniform" (default) counts every step once; "step_length" weights a step by its length, which gives the direction from the first position to the last, as net does. The two rules return the same heading: the maximum-likelihood mean direction of a von Mises distribution is the mean direction.

• velocity_axis takes the same weight_by, with "step_length" as its default.

• origin_mean averages the bearings of the positions from the origin, weighted by radius to the power r_power (default 0, every position counted once; 1 gives the bearing of the centroid).

A step of zero length and a position at the origin have no direction and are left out of these averages, whatever the weighting. A track with no direction left, or whose directions cancel, has heading NA.

The other rules likewise give NA where a displacement has zero length: a track that never moves (net, straight, goal_bias, maxspeed_window, window_net), one that ends where it started (net), a window whose ends coincide (window_net), positions with no spread, or steps none of which moves (pca_axis), a pca_axis track whose net displacement has no component along its axis (the axis then has no sign), and a track that stays at the origin (distal). window_net and maxspeed_window shrink their window to fit a track shorter than window_n.

Value

data.frame with columns id, time (approx), heading (radians, unit-circle convention), plus the rule-specific construction columns above when 'return_coords = TRUE'. For some rules there may be multiple headings per id.

Examples

h <- derive_headings(cpunctatus, rule = "distal")
head(h)
# ignore tracking outliers beyond the circumference and keep the point used
head(derive_headings(cpunctatus, rule = "distal", max_radius = 1,
                     return_coords = TRUE))
# per-trial reference frame, carrying a condition column for grouping
head(derive_headings(cpunctatus, rule = "net", coords = "relative",
                     carry = "arc"))

Description

Computes the circular mean direction and resultant length, returning a 'geom_segment()' layer that can be added to an existing ggplot.

Usage

directedness_arrow(
  data,
  angle_col,
  arrow_head_cm = 0.2,
  colour = "gray",
  size = 2,
  color = NULL
)

Arguments

Value

A 'geom_segment()' layer.

Examples

# Arrow showing mean direction and resultant length
hd <- derive_headings(cpunctatus[1:5], rule = "distal")
library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ() +
  directedness_arrow(hd, angle_col = "heading")

Description

Attach a physical-distance scale (and optional unit label) to a [Tracks] so path lengths and speeds can be reported in real units. The scale is physical units per unit of the recorded 'x'/'y' coordinates; it is applied on demand and the stored coordinates are never altered. radiatR otherwise analyses in normalised (unit-circle) space – this is an optional calibration hook.

Usage

distance_scale(x)

## S4 method for signature 'Tracks'
distance_scale(x)

distance_unit(x)

## S4 method for signature 'Tracks'
distance_unit(x)

set_distance_scale(x, scale, unit = NULL)

## S4 method for signature 'Tracks'
set_distance_scale(x, scale, unit = NULL)

calibrate_distance(ts, coord_distance, real_distance, unit = NULL)

Arguments

Value

'distance_scale()'/'distance_unit()' the stored values (or 'NULL'); 'set_distance_scale()'/'calibrate_distance()' the modified 'Tracks'.

See Also

[frame_rate()], [track_length()], [track_speed()]

Examples

distance_scale(cpunctatus) # NULL: not calibrated
x <- set_distance_scale(cpunctatus, 150, unit = "mm")
distance_unit(x)
# the same scale from a known separation: 0.5 coordinate units is 75 mm
x <- calibrate_distance(cpunctatus, coord_distance = 0.5,
                        real_distance = 75, unit = "mm")
distance_scale(x)
head(track_length(x))

Description

Real elapsed time of each point from its own track's start, computed on demand from the time column and (for frame-indexed time) the [frame_rate()]. POSIXct time is used directly, and so is numeric time loaded as seconds ('read_tracks(time_type = "seconds")', or a duration column): a frame rate is neither needed nor applied to it. Any other numeric time is a frame index and requires a frame rate.

Usage

elapsed_seconds(ts, units = c("seconds", "minutes", "milliseconds"))

Arguments

Value

A numeric vector aligned to the object's observations.

See Also

[frame_rate()], [track_duration()]

Examples

head(elapsed_seconds(cpunctatus))

Description

Shapes the predictions of a [circ_regression()] model into the 'summary_df' that [add_circ_mean()] draws, so a fitted mean-direction (rho) arrow can be drawn for each covariate value and colour-coded by the covariate – showing how the mean heading sweeps with the predictor. The arrow length is the model's implied resultant length circular::A1(kappa), the same for every arrow, so direction and colour carry the signal.

Usage

fitted_directions(fit, at = NULL, newdata = NULL, display = NULL)

Arguments

Value

A data frame with 'mean_dir' (fitted heading, radians, unit-circle convention), 'resultant_R' (= 'circular::A1(fit$kappa)', constant), and the covariate column(s) from 'newdata', with a 'display' attribute. Pass it to 'add_circ_mean(colour_col = "<predictor>")'. A non-converged fit yields 'NA' 'mean_dir' rows, which 'add_circ_mean()' skips.

See Also

[circ_regression()], [add_circ_mean()], [compute_circ_mean()]

Examples

set.seed(1)
x <- runif(60, -1, 1)
noise <- as.numeric(circular::rvonmises(60, circular::circular(0), kappa = 8))
hd <- data.frame(x = x, heading = (1 + 2 * atan(1.5 * x) + noise) %% (2 * pi))
fit <- circ_regression(hd, heading ~ x)
arrows <- fitted_directions(fit, at = c(-1, -0.5, 0, 0.5, 1))
arrows
library(ggplot2)
ggplot() +
  coord_fixed() +
  add_circ() +
  add_circ_mean(arrows, colour_col = "x")

Description

Attach a capture frame rate (frames per second) to a [Tracks] so the time aspect of frame-indexed tracks can be represented in real seconds. Stored in the object's metadata; the time/frame column is not altered. It converts frame indices only: time that is already real (POSIXct, or numeric seconds loaded with 'read_tracks(time_type = "seconds")') is never divided by it.

Usage

frame_rate(x)

## S4 method for signature 'Tracks'
frame_rate(x)

set_frame_rate(x, fps)

## S4 method for signature 'Tracks'
set_frame_rate(x, fps)

Arguments

Value

'frame_rate()' the stored fps (or 'NULL'); 'set_frame_rate()' the modified 'Tracks'.

See Also

[elapsed_seconds()], [track_duration()]

Examples

frame_rate(cpunctatus)
x <- set_frame_rate(cpunctatus, 25)
frame_rate(x)

Description

Iterates over the rows of 'file_tbl', reading the paired landmark and track files for each video before computing trial limits and normalised coordinates. The per-trial outputs are combined into a single tibble, and the augmented trial limits are returned alongside it. Supply 'manifest' to join per-file metadata (matched on 'file') onto every trial.

Usage

get_all_object_pos(
  landmarks = NULL,
  track = NULL,
  file_tbl,
  track_dir,
  manifest = NULL,
  manifest_cols = NULL
)

Arguments

Value

A 'Tracks' combining the normalised observations for all valid trials in the manifest. The aggregated trial limits are available via 'meta$trial_limits', which holds every trial of every file, with 'valid_track' 'FALSE' for those dropped. Each landmark and track file is tab-separated with frame, x and y in the first three fields of every line (further fields are not read); a cell that is not a number stops with a 'radiatR_malformed_values' error, and a line with fewer than three fields or an odd number of landmark rows with a 'radiatR_malformed_file' error, each naming the file. When no file holds a valid trial the call stops with a 'radiatR_no_valid_trials' error.

Examples

untar(system.file("extdata", "tracks.tar.gz", package = "radiatR"),
      exdir = tempdir())
track_dir <- file.path(tempdir(), "tracks")
file_tbl <- import_tracks(track_dir)[1:3, ]
manifest <- import_info(system.file("extdata", "millipede_trials.csv",
                                    package = "radiatR"))
manifest <- manifest[manifest$file %in% file_tbl$basename, ]
ts <- get_all_object_pos(file_tbl = file_tbl, track_dir = track_dir,
                         manifest = manifest)
ts
ts@meta$trial_limits[, c("video", "arc", "type", "ref_theta")]