circ_varcor_model {BAMBI}

Analytic circular variances and correlations for bivariate angular models

Description

Analytic circular variances and correlations for bivariate angular models

Usage

circ_varcor_model(
  model = "vmsin",
  kappa1 = 1,
  kappa2 = 1,
  kappa3 = 0,
  mu1 = 0,
  mu2 = 0,
  nsim = 10000,
  ...
)

Arguments

model

bivariate angular model. Must be one of "vmsin", "vmcos", or "wnorm2".

kappa1, kappa2, kappa3

concentration and covariance parameters. Recycled to the same size. kappa3^2 must be < kappa1*kappa2 in the wnorm2 model (see rwnorm2 for a detailed parameterization of wnorm2).

mu1, mu2

mean parameters. Ignored as they do not play any role in the analytical formulas.

nsim

Monte Carlo sample size. Ignored if all of kappa1, kappa2 and abs(kappa3) are < 150 or if model = "wnorm2".

...

additional model specific argment

Details

The function computes the analytic circular variances and correlations (both Jammalamadaka-Sarma (JS) and Fisher-Lee (FL) forms) for von Mises sine, von Mises cosine and bivariate wrapped normal distributions.

For wnorm2, expressions for the circular variances, JS and FL correlation coefficients can be found in Mardia and Jupp (2009), Jammalamadaka and Sarma (1988) and Fisher and Lee (1983) respectively. For vmsin and vmcos these expressions are provided in Chakraborty and Wong (2018).

Because the analytic expressions in vmsin and vmcos models involve infinite sums of product of Bessel functions, if any of kappa1, kappa2 and abs(kappa3) is larger than or equal to 150, IID Monte Carlo with sample size nsim is used to approximate rho_js for numerical stability. From rho_js, rho_fl is computed using Corollary 2.2 in Chakraborty and Wong (2018), which makes cost-complexity for the rho_fl evaluation to be of order O(nsim) for vmsin and vmcos models. (In general, rho_fl evaluation is of order O(nsim^2)).

In addition, for the vmcos model, when -150 < kappa3 < -1 or 50 < max(kappa1, kappa2, abs(kappa3)) <= 150, the analytic formulas in Chakraborty and Wong (2018) are used; however, the reciprocal of the normalizing constant and its partial derivatives are all calculated numerically via (quasi) Monte carlo method for numerical stability. These (quasi) random numbers can be provided through the argument qrnd, which must be a two column matrix, with each element being a (quasi) random number between 0 and 1. Alternatively, if n_qrnd is provided (and qrnd is missing), a two dimensional sobol sequence of size n_qrnd is generated via the function sobol from the R package qrng. If none of qrnd or n_qrnd is available, a two dimensional sobol sequence of size 1e4 is used.

Value

Returns a list with elements var1, var2 (circular variances for the first and second coordinates), rho_fl and rho_js (circular correlations). See details.

References

Fisher, N. I. and Lee, A. (1983). A correlation coefficient for circular data. Biometrika, 70(2):327-332.

Jammalamadaka, S. R. and Sarma, Y. (1988). A correlation coefficient for angular variables. Statistical theory and data analysis II, pages 349-364.

Mardia, K. and Jupp, P. (2009). Directional Statistics. Wiley Series in Probability and Statistics. Wiley.

Chakraborty, S. and Wong, S, W.K. (2018). On the circular correlation coefficients for bivariate von Mises distributions on a torus. arXiv e-print.

Examples

circ_varcor_model("vmsin", kappa1= 1, kappa2 = 2, kappa3 = 3)

# Monte Carlo approximation
set.seed(1)
dat <- rvmsin(1000, 1, 2, 3)
# sample circular variance
circ_var <- function(x)
  1 - mean(cos(x - atan2(mean(sin(x)), mean(cos(x))) ))
circ_var(dat[, 1])
circ_var(dat[, 2])
circ_cor(dat, "fl")
circ_cor(dat, "js")