traj_sim {cylcop}

Generate a Trajectory with Correlated Step Lengths and Turn Angles

Description

The function draws values from a circular-linear bivariate distribution of turn angles and step lengths specified by the marginal distributions and a circular-linear copula. From the start point (0,0) and the second (potentially user specified) point, a trajectory is then built with these turn angles and step lengths.

Usage

traj_sim(
  n,
  copula,
  marginal_circ,
  marginal_lin,
  ignore_first = TRUE,
  pos_2 = NULL
)

Arguments

n

integer, number of trajectory steps to generate.

copula

'cyl_copula' object.

marginal_circ

named list (for parametric estimates) or a 'density.circular' object (for kernel density estimates). The output of function fit_angle() can be used here directly for both cases.

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.

ignore_first

logical value. If ignore_first = TRUE (default), a trajectory of length n+2 is generated and the first two steps of that trajectory are removed.

pos_2

(optional) numeric vector of length 2 containing the coordinates of the second point in the trajectory. The first point is always at (0,0). If no value is specified, the second point is obtained by going in a random direction from the first point for a distance drawn from the marginal step length distribution.

Details

Samples are drawn from the circular-linear copula and then transformed using the quantile functions of the marginal circular and the marginal linear distribution. To generate draws from any bivariate joint distribution (not necessarily a circular-linear one) without also producing a trajectory, the function rjoint() can be used.

If entered "by hand", the named lists describing the parametric distributions (marginal_circ and marginal_lin) must contain 2 entries:

1. name: a character string denoting the name of the distribution. For the circular distribution, it can be "vonmises", "vonmisesmix", or "wrappedcauchy". For the linear distribution, it must be a string denoting the name of a linear distribution in the environment, i.e. the name of its distribution function without the "p", e.g. "norm" for normal distribution

2. coef: For the circular distribution coef is a (named) list of parameters of the circular marginal distribution as taken by the functions qvonmises(), qvonmisesmix(), or qwrappedcauchy(). For the linear distribution, coef is a named list containing the parameters of the distribution given in "name".

Value

A data.frame containing the trajectory. It has 6 columns containing the x and y coordinates, the turn angles, the step lengths, and the values sampled from the copula.

See Also

traj_get(), fit_steplength(), fit_angle(), plot_track(), plot_cop_scat(), plot_joint_scat(), plot_joint_circ().

Examples

require(circular)
set.seed(123)

traj <- traj_sim(n = 5,
copula = cyl_quadsec(0.1),
marginal_circ = list(name="vonmises",coef=list(0, 1)),
marginal_lin = list(name="weibull",coef=list(shape=3))
)

traj

angles <- rvonmisesmix(100,
  mu = c(0, pi),
  kappa = c(2, 3),
  prop = c(0.4, 0.6)
)
angles <- full2half_circ(angles)
bw <- opt_circ_bw(theta = angles, method = "nrd", kappa.est = "trigmoments")
marg_ang <- fit_angle(theta = angles, parametric = FALSE, bandwidth = bw)

steplengths <- rlnorm(100, 0, 0.3)
marg_stepl <- fit_steplength(x = steplengths, parametric = "lnorm")

traj_sim(n = 5,
copula = cyl_quadsec(0.1),
marginal_circ = marg_ang,
marginal_lin = marg_stepl,
ignore_first = FALSE,
pos_2 = c(5,5)
)