ridge_pca {ridgetorus}

Toroidal PCA via density ridges

Description

This function computes the whole process of toroidal PCA via density ridges on a given sample: parameter estimation of the underlying distribution, estimation of the connected component of the ridge, and determination of its Fourier expansion from which to obtain the first and second scores.

Usage

ridge_pca(
  x,
  type = c("auto", "bvm", "bwc")[1],
  N = 500,
  K = 15,
  scale = TRUE,
  lrts = TRUE,
  alpha = 0.05,
  at2 = TRUE,
  ...
)

Arguments

x

matrix of dimension c(n, 2) containing the n observations of the pair of angles.

type

either "bvm" (bivariate sine von Mises), "bwc" (bivariate wrapped Cauchy), or "auto" (default). "auto" performs both fits and uses the one with lowest BIC.

N

number of discretization points for approximating curve lengths. Defaults to 5e2.

K

number of terms in the Fourier expansion. Defaults to 15.

scale

scale the resulting scores to [-\pi, \pi)^2? Defaults to TRUE.

lrts

run biv_lrt to check the null hypothesis of homogeneous concentration parameters using likelihood ratio tests? If TRUE (default), enforces the special horizontal/vertical/diagonal cases to become "sticky" fits.

alpha

significance level for the homogeneity test.

at2

do the atan2 fit instead of the sine fit (only using S_m)? Defaults to TRUE. at2 = FALSE is not recommended to use.

...

optional parameters passed to fit_bvm_mle and fit_bwc_mle, such as start, lower, or upper.

Value

A list with:

mu_hat

estimated circular means of the sample.

coefs_hat

estimated Fourier coefficients.

ind_var

indexing variable.

scores

scores for each of the sample points.

var_exp

percentage of explained variance.

fit_mle

maximum likelihood fit.

bic_fit

BIC of the fit.

data

original sample.

scales

vector of length 2 with the scale limits for the axes.

type

type of fit performed.

p_hom

p-value of the homogeneity test.

p_indep

p-value of the independence test.

Examples

## Bivariate von Mises

n <- 100
x <- r_bvm(n = n, mu = c(1, 2), kappa = c(0.4, 0.4, 0.5))
fit <- ridge_pca(x = x, type = "bvm")
show_ridge_pca(fit = fit, col_data = "red")

x <- r_bvm(n = n, mu = c(2, 1), kappa = c(1, 2, 0))
fit <- ridge_pca(x = x, type = "bvm")
show_ridge_pca(fit = fit, col_data = "red")

x <- r_bvm(n = n, mu = c(2, 1), kappa = c(3, 2, 0))
fit <- ridge_pca(x = x, type = "bvm")
show_ridge_pca(fit = fit, col_data = "red")

## Bivariate wrapped Cauchy

x <- r_bwc(n = n, mu = c(1, 2), xi = c(0.2, 0.2, 0.5))
fit <- ridge_pca(x = x, type = "bwc")
show_ridge_pca(fit = fit, col_data = "red")

x <- r_bwc(n = n, mu = c(1, 2), xi = c(0.2, 0.8, 0))
fit <- ridge_pca(x = x, type = "bwc")
show_ridge_pca(fit = fit, col_data = "red")

x <- r_bwc(n = n, mu = c(1, 2), xi = c(0.5, 0.2, 0))
fit <- ridge_pca(x = x, type = "bwc")
show_ridge_pca(fit = fit, col_data = "red")