fit_cylcop_cor {cylcop}

Estimate Copula Parameters from Correlation Measures

Description

This function implements a simple search of the parameter space of a 'cyl_copula' object to find the parameter values that lead to a correlation that is closest to the correlation in the data (theta and x). In some special cases of 'cyl_rect_combine' copulas, the parameter can be obtained analytically from Kendall's tau of the data.

Usage

fit_cylcop_cor(copula, theta, x, acc = NULL, n = 10000, method, ...)

## S4 method for signature 'cyl_vonmises'
fit_cylcop_cor(copula, theta, x, acc, n, method = "cor_cyl")

## S4 method for signature 'cyl_quadsec'
fit_cylcop_cor(copula, theta, x, acc, n, method = "cor_cyl")

## S4 method for signature 'cyl_cubsec'
fit_cylcop_cor(
  copula,
  theta,
  x,
  acc,
  n,
  method = "cor_cyl",
  parameter = "both"
)

## S4 method for signature 'cyl_rot_combine'
fit_cylcop_cor(copula, theta, x, acc, n, method = "mi_cyl")

## S4 method for signature 'cyl_rect_combine'
fit_cylcop_cor(copula, theta, x, acc, n, method = "tau", background = FALSE)

optCor(copula, theta, x, acc = NULL, n = 10000, method, ...)

Arguments

copula

R object of class 'cyl_copula'.

theta

numeric vector of angles (measurements of a circular variable).

x

numeric vector of step lengths (measurements of a linear variable).

acc

numeric value, the interval of the copula parameter at which to evaluate the correlation.

n

numeric value, the number of sample points at each optimization step.

method

character string describing what correlation metric to use. Either a rank-based circular-linear correlation coefficient ("cor_cyl"), mutual information ("mi_cyl"), or Kendall's tau ("tau").

...

Additional parameters (see individual methods).

parameter

For 'cyl_cubsec' copulas: A character string specifying which parameter of the copula to optimize, "a", "b", or "both"

background

For 'cyl_rect_combine' copulas : A logical value describing whether to optimize the parameter of the background copula, (background = TRUE) or the one of the copula in the rectangles (background = FALSE).

Details

The code assumes that the correlation captured by the copula increases monotonously with the copula parameter values. It starts with a parameter value close to the minimum for that copula and calculates the correlation for a sample of size n from that copula. Next, the parameter is doubled and again the correlation for a sample of size n calculated. After this exponential search pattern, a binary search is implemented similarly between the bounds found with the exponential search. For this binary search, the interval between those bounds is split into small intervals of length acc. Thus, smaller values of acc lead to higher accuracy.

If a 'cyl_rect_combine' copula has rectangles spanning the entire unit square and as background the independence copula, Kendall's tau can be used to analytically calculate the parameter value leading to the correlation of the data. No search is necessary in this case. This makes it the recommended method to use for those 'cyl_rect_combine' copulas. optCor() is an alias for fit_cylcop_cor.

See also individual methods (below) for more detailed explanations.

Value

numeric vector containing the estimated parameter value(s).

Functions

• fit_cylcop_cor(cyl_vonmises): only parameter "kappa" can be optimized, since parameter "mu" does not influence the correlation.

• fit_cylcop_cor(cyl_quadsec): the absolute value of the parameter is optimized, positive and negative values give the same correlation.

• fit_cylcop_cor(cyl_cubsec): optimization of parameters, "a" and "b", can be done separately or simultaneously.

• fit_cylcop_cor(cyl_rot_combine): the circular-linear correlation coefficient will give a value close to 0 for any parameter value. It therefore only makes sense to use method = "mi_cyl" for the optimization.

• fit_cylcop_cor(cyl_rect_combine): if the rectangles span the entire unit square and the background is the independence copula, it is recommended to use method = "tau", since this calculates the copula parameter analytically. If there is a background copula, other than the independence copula, its parameter can be optimized by setting background=TRUE.

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

mi_cyl(), cor_cyl(), fit_cylcop_ml(), opt_auto(), copula::fitCopula().

Examples

set.seed(123)

sample <- rcylcop(100, cyl_rect_combine(copula::frankCopula(2)))
fit_cylcop_cor(cyl_rect_combine(copula::frankCopula()),
  theta = sample[,1],
  x = sample[,2],
  method = "tau"
)

fit_cylcop_cor(cyl_rect_combine(copula::frankCopula()),
  theta = sample[,1],
  x = sample[,2],
  method = "mi_cyl",
  n = 100
)

fit_cylcop_cor(cyl_rect_combine(copula::claytonCopula()),
  theta = sample[,1],
  x = sample[,2],
  method = "tau"
)

fit_cylcop_cor(cyl_quadsec(), theta = sample[,1], x = sample[,2], method = "mi_cyl")
fit_cylcop_cor(cyl_quadsec(), theta = sample[,1], x = sample[,2], method = "cor_cyl")
fit_cylcop_cor(cyl_quadsec(),
  theta = sample[,1],
  x = sample[,2],
  method = "cor_cyl",
  n = 100,
  acc = 0.001
)

optCor(cyl_quadsec(),
 theta = sample[,1],
 x = sample[,2],
 method = "mi_cyl")