sphunif (version 1.4.3)

unif_stat: Circular and (hyper)spherical uniformity statistics

Description

Implementation of several statistics for assessing uniformity on the (hyper)sphere \(S^{p-1} := \{{\bf x} \in R^p : ||{\bf x}|| = 1\}\), \(p\ge 2\), for a sample \({\bf X}_1,\ldots,{\bf X}_n\in S^{p-1}\).

unif_stat receives a (several) sample(s) of directions in Cartesian coordinates, except for the circular case (\(p=2\)) in which the sample(s) can be angles \(\Theta_1,\ldots,\Theta_n\in [0, 2\pi)\).

unif_stat allows to compute several statistics to several samples within a single call, facilitating thus Monte Carlo experiments.

Usage

unif_stat(data, type = "all", data_sorted = FALSE, CCF09_dirs = NULL,
  CJ12_reg = 3, cov_a = 2 * pi, Cressie_t = 1/3, K_CCF09 = 25,
  Poisson_rho = 0.5, Pycke_q = 0.5, Rayleigh_m = 1, Riesz_s = 1,
  Rothman_t = 1/3, Sobolev_vk2 = c(0, 0, 1), Softmax_kappa = 1,
  Stein_K = 10, Stein_cf = FALSE, Stereo_a = 0)

Value

A data frame of size c(M, length(type)), with column names given by type, that contains the values of the test statistics.

Arguments

data

sample to compute the test statistic. An array of size c(n, p, M) containing M samples of size n of directions (in Cartesian coordinates) on \(S^{p-1}\). Alternatively, a matrix of size c(n, M) with the angles on \([0, 2\pi)\) of the M circular samples of size n on \(S^{1}\). Other objects accepted are an array of size c(n, 1, M) or a vector of size n with angular data. Must not contain NA's.

type

type of test to be applied. A character vector containing any of the following types of tests, depending on the dimension \(p\):

• Circular data: any of the names available at object avail_cir_tests.

• (Hyper)spherical data: any of the names available at object avail_sph_tests.

If type = "all" (default), then type is set as avail_cir_tests or avail_sph_tests, depending on the value of \(p\).

data_sorted

is the circular data sorted? If TRUE, certain statistics are faster to compute. Defaults to FALSE.

CCF09_dirs

a matrix of size c(n_proj, p) containing n_proj random directions (in Cartesian coordinates) on \(S^{p-1}\) to perform the CCF09 test. If NULL (default), a sample of size n_proj = 50 directions is computed internally.

CJ12_reg

type of asymptotic regime for CJ12 test, either 1 (sub-exponential regime), 2 (exponential), or 3 (super-exponential; default).

cov_a

\(a_n = a / n\) parameter used in the length of the arcs of the coverage-based tests. Must be positive. Defaults to 2 * pi.

Cressie_t

\(t\) parameter for the Cressie test, a real in \((0, 1)\). Defaults to 1 / 3.

K_CCF09

integer giving the truncation of the series present in the asymptotic distribution of the Kolmogorov-Smirnov statistic. Defaults to 25.

Poisson_rho

\(\rho\) parameter for the Poisson test, a real in \([0, 1)\). Defaults to 0.5.

Pycke_q

\(q\) parameter for the Pycke "\(q\)-test", a real in \((0, 1)\). Defaults to 1 / 2.

Rayleigh_m

integer \(m\) for the \(m\)-modal Rayleigh test. Defaults to m = 1 (the standard Rayleigh test).

Riesz_s

\(s\) parameter for the \(s\)-Riesz test, a real in \((0, 2)\). Defaults to 1.

Rothman_t

\(t\) parameter for the Rothman test, a real in \((0, 1)\). Defaults to 1 / 3.

Sobolev_vk2

weights for the finite Sobolev test. A non-negative vector or matrix. Defaults to c(0, 0, 1).

Softmax_kappa

\(\kappa\) parameter for the Softmax test, a non-negative real. Defaults to 1.

Stein_K

truncation \(K\) parameter for the Stein test, a positive integer. Defaults to 10.

Stein_cf

logical indicating whether to use the characteristic function in the Stein test. Defaults to FALSE (moment generating function).

Stereo_a

\(a\) parameter for the Stereo test, a real in \([-1, 1]\). Defaults to 0.

Details

Except for CCF09_dirs, K_CCF09, and CJ12_reg, all the test-specific parameters are vectorized.

Descriptions and references for most of the statistics are available in García-Portugués and Verdebout (2018).

References

García-Portugués, E. and Verdebout, T. (2018) An overview of uniformity tests on the hypersphere. arXiv:1804.00286. tools:::Rd_expr_doi("10.48550/arXiv.1804.00286")

Examples

## Circular data

# Sample
n <- 10
M <- 2
Theta <- r_unif_cir(n = n, M = M)

# Matrix
unif_stat(data = Theta, type = "all")

# Array
unif_stat(data = array(Theta, dim = c(n, 1, M)), type = "all")

# Vector
unif_stat(data = Theta[, 1], type = "all")

## Spherical data

# Circular sample in Cartesian coordinates
n <- 10
M <- 2
X <- array(dim = c(n, 2, M))
for (i in 1:M) X[, , i] <- cbind(cos(Theta[, i]), sin(Theta[, i]))

# Array
unif_stat(data = X, type = "all")

# High-dimensional data
X <- r_unif_sph(n = n, p = 3, M = M)
unif_stat(data = X, type = "all")

## Specific arguments

# Rothman
unif_stat(data = Theta, type = "Rothman", Rothman_t = 0.5)

# CCF09
unif_stat(data = X, type = "CCF09", CCF09_dirs = X[, , 1])
unif_stat(data = X, type = "CCF09", CCF09_dirs = X[, , 1], K_CCF09 = 1)

# CJ12
unif_stat(data = X, type = "CJ12", CJ12_reg = 3)
unif_stat(data = X, type = "CJ12", CJ12_reg = 1)