fit_cylcop_ml {cylcop}

Estimate Parameters of a Circular-Linear Copula According to Maximum Likelihood

Description

The code of this function is based on copula::fitCopula(). A circular-linear copula is fit to a set of bivariate observations.

Usage

fit_cylcop_ml(
  copula,
  theta,
  x,
  parameters = NULL,
  start = NULL,
  lower = NULL,
  upper = NULL,
  optim.method = "L-BFGS-B",
  optim.control = list(maxit = 100),
  estimate.variance = FALSE,
  traceOpt = FALSE
)

optML(
  copula,
  theta,
  x,
  parameters = NULL,
  start = NULL,
  lower = NULL,
  upper = NULL,
  optim.method = "L-BFGS-B",
  optim.control = list(maxit = 100),
  estimate.variance = FALSE,
  traceOpt = FALSE
)

Arguments

copula

R object of class 'cyl_copula'.

theta

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

x

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

parameters

vector of character strings holding the names of the parameters to be optimized. These can be any parameters in copula@parameters. Default is to optimize the first 2 parameters or the single parameter if copula only has 1.

start

vector of starting values of the parameters. Default is to take the starting values from copula.

lower

(optional) vector of lower bounds of the parameters.

upper

(optional) vector of upper bounds of the parameters.

optim.method

character string, optimizer used in optim(), can be "Nelder-Mead", "BFGS", "CG", "L-BFGS-B", "SANN", or "Brent". Default is "L-BFGS-B".

optim.control

list of additional controls passed to optim().

estimate.variance

logical value, denoting whether to include an estimate of the variance (NOT YET IMPLEMENTED).

traceOpt

logical value, whether to print information regarding convergence, current values, etc. during the optimization process.

Details

The data is first converted to pseudo observations to which the copula is then fit. Therefore, the result of the optimization will be exactly the same whether measurements (theta=theta and x=x) or pseudo observations (theta=copula::pobs(theta,x)[,1] and x=copula::pobs(theta,x)[,2]) are provided. If you wish to fit parameters of a 'Copula' object (package 'copula'), use the function copula::fitCopula(). optML() is an alias for fit_cylcop_ml.

Value

A list of length 3 containing the same type of 'cyl_copula' object as copula, but with optimized parameters, the log-likelihood and the AIC.

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

copula::fitCopula(), fit_cylcop_cor(), opt_auto().

Examples

set.seed(123)

sample <- rcylcop(100,cyl_quadsec(0.1))
fit_cylcop_ml(copula = cyl_quadsec(),
  theta = sample[,1],
  x = sample[,2],
  parameters = "a",
  start = 0
)
fit_cylcop_ml(copula = cyl_rect_combine(copula::frankCopula()),
  theta = sample[,1],
  x = sample[,2],
  parameters = "alpha",
  start = 1
)


sample <- rjoint(
  n = 100,
  copula = cyl_cubsec(0.1, -0.08),
  marginal_1 = list(name = "vonmisesmix", coef = list(
     mu = c(pi, 0),
     kappa = c(2, 5),
     prop = c(0.3, 0.7)
    )),
  marginal_2 = list(name = "exp", coef = list(0.3))
  )
  fit_cylcop_ml(copula = cyl_cubsec(),
  theta = sample[,1],
  x = sample[,2],
  parameters = c("a","b"),
  start = c(0,0),
  upper= c(0.1, 1/(2*pi))
)

optML(copula = cyl_quadsec(),
  theta = sample[,1],
  x = sample[,2],
  parameters = "a",
  start = 0
)