plot_joint_box {cylcop}

Circular Boxplot of Turn Angles and Step Lengths

Description

This function produces circular boxplots (a 'ggplot' object) of the turn angles corresponding to specific quantiles of the step lengths.

Usage

plot_joint_box(
  traj = NULL,
  theta = NULL,
  x = NULL,
  levels = 5,
  marginal_lin = NULL,
  spacing = 0.3,
  legend_pos = "right"
)

Arguments

traj

data.frame containing the trajectory produced by e.g. traj_sim(). It must contain the columns traj$angle and traj$steplength.

theta

(alternatively) numeric vector of angles (measurements of a circular variable) or "circular" component of pseudo-observations.

x

(alternatively) numeric vector of step lengths (measurements of a linear variable) or "linear" component of pseudo-observations.

levels

integer value between 1 and 15, the number of quantiles into which the step lengths are split.

marginal_lin

named list (for parametric estimates) or a 'density' object (for kernel density estimates). The output of function fit_steplength() can be used here directly for both cases. If marginal_lin is specified, the limits of the quantiles of the step lengths are determined from that distribution instead of from the data specified with traj$steplength or x.

spacing

numeric value between 0 and 10 determining the spacing between the boxplots.

legend_pos

character string denoting the position of the legend (limits of the step length quantiles). Either "left", "right", "top", or "bottom"

Details

The step lengths are split into quantiles. For each quantile a boxplot of the corresponding turn angles is produced and wrapped around the circle. The turn angle values are plotted as scatter plot overlaying the boxplot. Outliers are plotted in red. The median of the turn angles is defined as the center of the shortest arc that connects all points. The length of the whiskers is 1.5 times the interquartile range.

You can either specify traj or the angels (theta) and step lengths (codex). If entered "by hand", the named list describing the marginal linear distribution (for marginal_lin) must contain 2 entries:

1. name: a character string denoting the name of the linear distribution, i.e. the name of its distribution function without the "p", e.g. "norm" for normal distribution.

2. coef: a named list containing the parameters of the distribution given in "name".

Value

A 'ggplot' object, the circular boxplot.

References

Hodel FH, Fieberg JR (2022). “Circular-Linear Copulae for Animal Movement Data.” Methods in Ecology and Evolution. doi:10.1111/2041-210X.13821.

Hodel FH, Fieberg JR (2021). “Cylcop: An R Package for Circular-Linear Copulae with Angular Symmetry.” bioRxiv. doi:10.1101/2021.07.14.452253, https://www.biorxiv.org/content/10.1101/2021.07.14.452253v3/.

See Also

plot_cop_scat(), plot_track(), plot_joint_circ(), plot_cop_surf().

Examples

set.seed(1234)

traj <- traj_sim(100,
  copula = cyl_rect_combine(copula::frankCopula(6)),
  marginal_circ = list(name= "vonmises", coef=list(0, 2)),
  marginal_lin = list(name = "weibull", coef=list(shape=3))
)

plot1 <- plot_joint_box(traj)
plot2 <- plot_joint_box(traj,
  marginal_lin=list(name = "weibull", coef=list(shape=3))
)