Package 'radiatR'

Description

Build a data frame of arrow segments representing mean direction vectors Length equals resultant_R; angle equals mean_dir

Usage

.heading_registry

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(panel_by = ...) 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 +.

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()]

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()]

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,
  width = 0.1,
  colour = "black",
  box_fill = "grey80",
  farout_shape = 8,
  show_median_arrow = TRUE,
  linewidth = 0.8,
  n_theta = 200L,
  display = 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()]

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.

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",
  group_col = NULL,
  per_group = FALSE,
  colour = "firebrick",
  colour_by_group = TRUE,
  linetype = "dashed",
  linewidth = 0.6,
  n_pts = 200L,
  color = NULL,
  color_by_group = NULL
)

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 group from hd. When group_col matches the parent radiate(panel_by = ...) argument, one circle is drawn per panel at the radius appropriate to that panel's n. For groups overlaid in a single panel, set per_group = TRUE to draw one circle per group (colour-matched), or per_group = FALSE (default) to draw a single conservative circle using the smallest n (largest critical radius).

Value

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

See Also

add_heading_arrow, add_circ

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",
  group_col = NULL,
  per_group = FALSE,
  show_region = FALSE,
  colour = "firebrick",
  linetype = "dashed",
  linewidth = 0.6,
  region_fill = "firebrick",
  region_alpha = 0.08,
  axial = FALSE,
  n_pts = 100L,
  color = NULL
)

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 group from hd, with the same options as add_critical_r: per-panel when faceting, per-group when per_group = TRUE, or a single conservative boundary (smallest n, largest $c$) otherwise.

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

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()]

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",
  colour_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_col = NULL,
  color = NULL
)

Arguments

Value

A 'geom_path()' layer.

See Also

[compute_circ_interval()], [add_circ_interval()]

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

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 = 0,
  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

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.

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

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()]

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

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.

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 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()]

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.

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(..., 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}$.

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.

Description

Fits three candidate models to a heading sample and ranks them by the small-sample-corrected Akaike information criterion (AICc): a uniform distribution (no preferred direction), a unimodal von Mises (one preferred direction), and an axial (symmetric bimodal) von Mises (a preferred axis, two equal antipodal modes). Answers whether a sample is best described as uniform, directionally, or axially oriented.

Usage

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

Arguments

Details

Parameters 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 (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.

See Also

vonmises_fit, test_uniformity

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

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; mean_dir_deg is the same value converted to degrees.

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)

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

data.frame(id, n, t_start, t_end, mean_dir, resultant_R, kappa)

A 'data.frame' with columns 'id', 'n', 't_start', 't_end', 'mean_dir' (radians, unit-circle convention, 0 to 2pi), 'resultant_R' (0–1), and 'kappa' (von Mises concentration; 'NA' when estimation fails).

Examples

## Not run: 
data(cpunctatus)
circ_summary(cpunctatus, by = "id")
circ_summary(cpunctatus, by = "global")

## End(Not run)

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 = c("crossing", "distal", "straight", "origin_mean", "net", "velocity_mean"),
  group_by = "id",
  ...
)

Arguments

Value

A 'data.frame' with grouping columns followed by 'mean_dir' (radians, unit-circle convention, 0 to 2π), 'resultant_R' (0–1), 'kappa' (von Mises concentration), and 'n' (number of valid headings in the group).

Examples

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

# per-condition summary (requires an "arc" column carried through)
circ_summary_headings(cpunctatus, rule = "crossing",
                      circ0 = 0.2, circ1 = 0.4,
                      group_by = "arc")

## End(Not run)

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

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",
  colour_col = NULL,
  stat = c("bootstrap_ci", "sd"),
  boot_reps = 1000L,
  boot_alpha = 0.05,
  axial = FALSE,
  color_col = NULL
)

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()]

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",
  colour_col = NULL,
  axial = FALSE,
  color_col = NULL
)

Arguments

Value

A data frame with columns 'mean_dir' (unit-circle radians, 0 to 2pi), 'resultant_R' (0–1), and 'colour_col' when supplied. Both are 'NA' when a group contains fewer than 2 finite angles.

See Also

[add_circ_mean()], [add_heading_arrow()]

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 'panel_by'.

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):
## Not run: 
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()

## End(Not run)

# 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

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

## Not run: 
# Water maze probe trial: former platform at 45 degrees (NE), at wall
entries <- count_goal_entries(ts, target_angle = pi / 4,
                              crossing_radius = 0.15)
# n_entries > 1 indicates memory of the platform location

## End(Not run)

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 (arena 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 in 'inst/extdata/tracks/', 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

Description

A tidy long-form tibble (44,331 rows) holding the per-frame observations from the same millipede experiment as cpunctatus, with the trial condition metadata ('arc', 'type', 'individual') joined onto every frame. Convenient for analyses that prefer a plain data frame to the 'Tracks' container. A subset of the published dataset.

Usage

cpunctatus_tracks

Format

A tibble with 18 columns including trial_id, frame, trans_x, trans_y, rel_x, rel_y, abs_theta, rel_theta, arc, type, and individual.

Source

Same experiment as cpunctatus.

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

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 = "",
  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 = c("crossing", "distal", "straight", "origin_mean", "net", "velocity_mean",
    "velocity_axis", "window_net", "goal_bias", "pca_axis", "ransac_straight",
    "maxspeed_window", "vm_fit", "exit", "entry", "ring_tangent"),
  ...,
  coords = c("absolute", "relative")
)

## S4 method for signature 'Tracks'
derive_headings(
  x,
  rule = c("crossing", "distal", "straight", "origin_mean", "net", "velocity_mean",
    "velocity_axis", "window_net", "goal_bias", "pca_axis", "ransac_straight",
    "maxspeed_window", "vm_fit", "exit", "entry", "ring_tangent"),
  ...,
  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.

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.

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.

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-arena) 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()]

Description

Create geom layers for Cartesian track coordinates

Usage

draw_tracks(data, x_col, y_col, geom = "path", mapping = NULL, ...)

Arguments

Value

A list containing a single ggplot2 layer.

Description

Reads a tab-separated, headerless file produced by dtrack (https://bitbucket.org/jochensmolka/dtrack). The file is expected to have at least three columns: frame number, x coordinate, y coordinate. A fourth confidence/flag column (always 1 in practice) is silently dropped.

Usage

dtrack_read(path, normalize_xy = FALSE, ...)

Arguments

Value

A Tracks.

See Also

[import_tracks()] for discovering dtrack file pairs in a directory.

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; numeric (frame) time 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()]

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()]

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.

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()]

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.

Usage

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

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

Description

Using the trial limits returned by [get_trial_limits()], this helper extracts the corresponding rows from a track data frame or 'Tracks', centres and scales the coordinates, and computes angles in both absolute and reference-relative frames. The function optionally controls how inner/outer radius crossings are selected.

Usage

get_tracked_object_pos(
  trial_limits,
  track,
  circ0 = 0.1,
  circ1 = 0.2,
  radius_criterion = c("first_past", "closest")
)

Arguments

Value

A 'Tracks' containing all valid trial observations. The corresponding trial limits (including 'valid_track' flags) are stored in 'meta$trial_limits'.

Description

Uses paired landmark coordinates to determine the temporal bounds of each trial, the origin, and the reference heading. Additional metadata from 'file_tbl' is merged into the result. Accepts landmark and track data either as data frames or as 'Tracks' objects.

Usage

get_trial_limits(landmarks, track, file_tbl, vid_num)

Arguments

Value

A tibble with one row per trial containing trial limits and reference metadata.

Description

Plot trajectories from a Tracks (overlay or faceted)

Usage

gg_traj(
  x,
  colour = NULL,
  linetype = NULL,
  alpha = NULL,
  size = 0.6,
  panel_by = NULL,
  coord = c("polar", "cartesian"),
  geom = c("path"),
  thin = 1L,
  ncol = NULL,
  color = NULL
)

## S4 method for signature 'Tracks'
gg_traj(
  x,
  colour = NULL,
  linetype = NULL,
  alpha = NULL,
  size = 0.6,
  panel_by = NULL,
  coord = c("polar", "cartesian"),
  geom = c("path"),
  thin = 1L,
  ncol = NULL,
  color = NULL
)

Arguments

Value

ggplot object

Description

Inspects a data frame's column names and returns the best guess for each 'Tracks' role ('id', 'time', 'x', 'y', 'angle', 'weight'), honouring any explicit 'mapping' overrides. Matching is case-insensitive; 'x'/'y' also match separator-suffixed names such as 'Track1_X'. A role with no match is 'NULL'. This is the same logic [read_tracks()] uses internally; call it to see or pre-fill a column mapping. It does not synthesize missing 'id'/'time' columns (a 'NULL' signals that 'read_tracks()' will apply its single-track / row-order fallback).

Usage

guess_columns(data, mapping = list())

Arguments

Value

A named list with elements 'id', 'time', 'x', 'y', 'angle', 'weight' (each a column name or 'NULL').

Examples

guess_columns(data.frame(Frame = 1:2, Track1_X = 0:1, Track1_Y = 0:1))

Description

Validates the angle column, optionally converts degrees to radians, and marks the data frame with class headings_frame and attributes that downstream functions (stack_headings, add_stacked_headings, radiate) will use as defaults.

Usage

headings_frame(
  data,
  col,
  units,
  angle_convention = "unit_circle",
  coords = "absolute"
)

Arguments

Value

A data.frame with additional class "headings_frame" and attributes heading_col, angle_convention, coords.

See Also

stack_headings, add_stacked_headings, radiate

Description

Accessors for the metadata a [headings_frame] carries. They also work on a plain data frame, returning sensible defaults, so any function can read the display convention without assuming the input is classed.

Usage

hf_display(x)

hf_heading_col(x)

hf_colour_col(x)

hf_color_col(x)

hf_coords(x)

Arguments

Value

'hf_display()' a [circ_display()] object; 'hf_heading_col()' / 'hf_coords()' a string; 'hf_colour_col()' a string or 'NULL'.

Description

Import landmark coordinates from text files

Usage

import_info(filename, cond_cols = NULL, file_tbl = NULL)

Arguments

Value

A data frame containing the parsed metadata (and optional 'cond' column).

Examples

## Not run: 
manifest <- import_info("trials_list.csv", cond_cols = c("type", "arc"))

## End(Not run)

Description

Scans dir for paired files matching landmark_suffix and track_suffix and returns a tibble of basenames and paths.

Usage

import_tracks(dir, landmark_suffix = NULL, track_suffix = NULL)

Arguments

Details

The default suffixes match the export naming convention used by dtrack (https://bitbucket.org/jochensmolka/dtrack). In the bundled millipede example data, _point01 files contain two landmark rows per trial (the origin and stimulus edge on the circumference) and _point02 files contain the per-frame animal trajectory. This two-file role split is specific to that experiment and is not a general dtrack convention. Use [dtrack_read()] to read an individual trajectory file.

Value

A tibble with columns basename, landmark, and track.

Description

Instantaneous speed at each point, aligned to the ‘Tracks'’s rows (the per-observation sibling of [elapsed_seconds()]). Each point carries the speed of the step that ends at it; the first point of every trajectory is 'NA'. Speeds come from [step_speed()] using the track's elapsed time from [elapsed_seconds()].

Usage

instantaneous_speed(ts, 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. With the default coordinate columns the unit is arena-units (radii) per second.

Value

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

See Also

[step_speed()], [track_speed()], [elapsed_seconds()]

Description

Opens a browser-based graphical interface for uploading tracking data, selecting a heading method, and viewing circular track plots and summary statistics. No R coding is required to use the app.

Usage

launch_app(port = NULL, launch_browser = TRUE)

Arguments

Details

The same app directory can be deployed to https://www.shinyapps.io or any Shiny-compatible server without modification:

  rsconnect::deployApp(system.file("app", package = "radiatR"))

Value

Called for its side-effect; returns the result of runApp invisibly.

Description

Find the intercept of a line with the unit circle

Usage

line_circle_intercept(x0, y0, x1, y1)

Arguments

Value

A tibble with the intersection point closest to '(x1, y1)'.

Description

Convenience wrapper that accepts a data frame (or 'Tracks@data') containing coordinates and evaluates the intersection between two rows.

Usage

line_circle_intercept_df(df, row_in, row_out)

Arguments

Value

Tibble with 'x_int'/'y_int'.

Description

Extracts the first/last rows for a given id/time range and computes the intersection with the unit circle.

Usage

line_circle_intercept_traj(traj, id, range)

Arguments

Value

Tibble with 'x_int'/'y_int'

Description

List registered custom heading rules

Usage

list_heading_rules()

Value

Sorted character vector of registered rule names.

See Also

register_heading_rule

Description

List registered loader dialects

Usage

list_loader_dialects()

Description

List registered declarative formats

Usage

list_loader_formats()

Description

This high-level helper combines the file discovery tibble returned by [import_tracks()] with optional metadata from an experiment manifest, reads each track file using [read_tracks()], and merges the results into a single 'Tracks'.

Usage

load_manifest(
  file_tbl,
  track_dir,
  manifest = NULL,
  manifest_cols = NULL,
  mapping = NULL,
  angle_unit = c("radians", "degrees", "auto"),
  time_type = c("auto", "posix", "seconds", "frames"),
  tz = "UTC",
  fps = NULL,
  normalize_xy = TRUE,
  dialect = NULL,
  keep = NULL,
  drop = NULL,
  ...
)

Arguments

Value

A 'Tracks' with metadata columns replicated for each observation.

Description

Legacy helper to merge manifest metadata with a track table

Usage

load_tracks(file_tbl, df, track_dir)

Arguments

Value

'file_tbl' with additional metadata columns bound in.

Description

Flexible metadata join for track tables

Usage

load_tracks2(file_tbl, df, track_dir, colnames)

Arguments

Value

'file_tbl' with additional columns appended.

Description

Wraps a data frame as a 'headings_frame' (a tibble subclass) carrying the canonical display/heading metadata. Most users call [headings_frame()] (which validates and normalises angles) or get one from [derive_headings()].

Usage

new_headings_frame(
  data,
  display = circ_display(),
  heading_col = "heading",
  colour_col = NULL,
  coords = "absolute",
  color_col = NULL
)

Arguments

Value

A 'headings_frame'.

Description

The straightness index is the net (start-to-end) displacement divided by the total path length travelled. It ranges from 0 (a maximally convoluted path that returns to its starting point) to 1 (a perfectly straight path), and is the reciprocal of the tortuosity ratio ([path_tortuosity()]). Unlike that ratio it is bounded and does not blow up when the net displacement is small.

Usage

path_straightness(x, y)

Arguments

Details

The index is scale-invariant: multiplying all coordinates by a constant leaves it unchanged, so absolute or relative coordinates give the same value (provided the transformation is a similarity, i.e. uniform in x and y).

Value

A single straightness value in '[0, 1]', or 'NA_real_' when fewer than two finite points are available or the path has zero length.

See Also

[straightness_index()] for a whole 'Tracks'; [path_tortuosity()].

Examples

path_straightness(x = c(0, 1, 2), y = c(0, 0, 0))   # straight -> 1
path_straightness(x = c(0, 1, 0), y = c(0, 1, 0))   # returns to start -> 0

Description

The (classic) tortuosity ratio is the total path length travelled divided by the net (start-to-end) displacement – the reciprocal of the straightness index ([path_straightness()]). It ranges from 1 (a perfectly straight path) upward; larger values indicate a more convoluted path.

Usage

path_tortuosity(x, y)

Arguments

Details

The ratio is unbounded: when a trajectory returns to its starting point the net displacement is zero and the ratio is 'Inf'. For a bounded alternative, or when start and end points may coincide, use [path_straightness()].

Like the straightness index it is scale-invariant.

Value

A single tortuosity value '>= 1', 'Inf' when the net displacement is zero, or 'NA_real_' when fewer than two finite points are available or the path has zero length.

See Also

[tortuosity_ratio()] for a whole 'Tracks'; [path_straightness()].

Examples

path_tortuosity(x = c(0, 1, 2), y = c(0, 0, 0))     # straight -> 1
path_tortuosity(x = c(0, 0, 1), y = c(0, 1, 1))     # L-shaped -> sqrt(2)

Description

Computes a heading angle for every row in df from either two bodypart keypoint columns or a pre-computed orientation angle column. Intended for tethered or mostly stationary subjects where the position trajectory is absent or uninformative and body pose is the primary signal, but also useful for extracting a dense heading time series from trajectory data. The output is compatible with circ_dispersion, sector_summary, add_heading_points, and add_angle_rose.

Usage

pose_to_headings(
  df,
  anterior = NULL,
  posterior = NULL,
  theta_col = NULL,
  id_col = NULL,
  time_col = NULL,
  angle_convention = c("unit_circle", "clock")
)

Arguments

Value

Data frame with columns id, time, heading (in radians), with an angle_convention attribute for downstream compatibility.

Description

Wrap angles to the interval (-pi, pi]

Usage

rad_shepherd(theta)

Arguments

Value

Angles wrapped to (-pi, pi].

Examples

theta <- seq(from = -5, to = 5, length.out = 6)
rad_shepherd(theta)

Description

Applies one of the standard ggplot2 themes as the look of a 'radiate()' plot, so the panel background, grid lines, and border match the familiar 'ggplot2::theme_*()' appearance. The Cartesian axis text and ticks are not meaningful on a unit-circle plot and are removed by 'radiate()' itself, so this wrapper keeps only the panel-level styling that distinguishes the themes from one another.

Usage

radial_theme(name = "void", base_size = 11)

Arguments

Value

A ggplot2 theme object.

Examples

library(ggplot2)
ggplot() + coord_fixed() + add_circ() + radial_theme("bw")

Description

Accepts either a precomputed data frame of polar/cartesian coordinates or a 'Tracks'. When a 'Tracks' is supplied, column mappings are inferred from the object and handed off to the plotting helpers.

Usage

radiate(data, ...)

## S3 method for class 'Tracks'
radiate(data, ...)

## Default S3 method:
radiate(
  data,
  x_col = "rel_x",
  y_col = "rel_y",
  geom = "path",
  group_col = NULL,
  colour_col = NULL,
  colour_cycle = NULL,
  track_colour = c("trajectory", "sequence", "time", "speed"),
  time_units = c("seconds", "minutes", "milliseconds"),
  panel_by = NULL,
  ncol = NULL,
  strip_labels = NULL,
  strip_position = c("top", "bottom", "left", "right", "inside"),
  strip_label_size = 11,
  ticks = NULL,
  degrees = NULL,
  legend = NULL,
  title = NULL,
  xlab = NULL,
  ylab = NULL,
  axes = NULL,
  angle_labels = c("degrees", "none", "radians"),
  theme = c("void", "minimal", "classic", "bw", "grey", "gray", "light", "dark",
    "linedraw"),
  quadrants = FALSE,
  rings = FALSE,
  grid = c("radial", "cartesian", "none"),
  grid_colour = NULL,
  origin = FALSE,
  circumference = TRUE,
  show_labels = NULL,
  label_col = NULL,
  label_size = 3,
  label_padding = 1.08,
  label_use_repel = TRUE,
  show_tracks = TRUE,
  show_arrow = NULL,
  arrow_angle_col = NULL,
  arrow_colour = "black",
  arrow_colour_col = NULL,
  arrow_size = 2,
  display = circ_display(),
  ...,
  color_col = NULL,
  color_cycle = NULL,
  track_color = NULL,
  grid_color = NULL,
  arrow_color = NULL,
  arrow_color_col = NULL
)

## S3 method for class 'headings_frame'
radiate(
  data,
  col = NULL,
  step = 0.025,
  tol = NULL,
  direction = "inward",
  base_r = 1,
  shade = FALSE,
  shape = FALSE,
  panel_by = NULL,
  ncol = NULL,
  ticks = TRUE,
  degrees = TRUE,
  angle_labels = c("degrees", "none", "radians"),
  title = NULL,
  theme = c("void", "minimal", "classic", "bw", "grey", "gray", "light", "dark",
    "linedraw"),
  quadrants = FALSE,
  rings = FALSE,
  grid = c("radial", "cartesian", "none"),
  grid_colour = NULL,
  circumference = TRUE,
  origin = FALSE,
  colour_col = NULL,
  legend = FALSE,
  display = circ_display(),
  show_markers = TRUE,
  ...
)

Arguments

Value

A 'ggplot2' object.

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.

Examples

tracks_demo <- simulate_tracks(conditions = data.frame(n_trials = 1L),
                               n_points = 200, seed = 1)
radiate(tracks_demo, x_col = "rel_x", y_col = "rel_y", group_col = "trial_id")

Description

Construct a Tracks from a data.frame or file(s)

Usage

read_tracks(
  x,
  mapping = list(id = NULL, time = NULL, x = NULL, y = NULL, angle = NULL, weight = NULL),
  angle_unit = c("radians", "degrees", "auto"),
  time_type = c("auto", "posix", "seconds", "frames"),
  tz = "UTC",
  fps = NULL,
  normalize_xy = TRUE,
  dialect = NULL,
  dialect_args = list(),
  read_opts = list(delim = NULL, decimal = NULL, sheet = NULL),
  mutate = NULL,
  keep = NULL,
  drop = NULL,
  id_from_filename = TRUE,
  validate = TRUE,
  format = NULL
)

Arguments