Distance covariance independence test for manifold-valued data.

Aligns X and Y to a common sample size, chooses (or validates a user-supplied) base point for each, maps both data sets from the manifold to the tangent space via the inverse exponential map, then runs a distance covariance permutation test to assess independence between them. It implements the DistCov (default) and RankCov tests of Liu et al. (2026); see Details.

Usage

manifold.dcov.test(
  X,
  Y,
  manifold = "torus",
  px_base = NULL,
  py_base = NULL,
  R = 500,
  seed = 2024,
  center_outward = FALSE,
  base_point_method = NULL,
  n_start = 10,
  maxit = 200,
  verbose = TRUE
)

Arguments

X: A matrix or data frame of data on manifold, in its representation (for the torus, rows in \([0,1)^d\); for hyperbolic space, rows on the hyperboloid; for the Grassmann manifold, flattened Stiefel matrices); rows are samples, columns are coordinates. A vector is treated as a one-column matrix.
Y: A matrix or data frame of data on manifold, analogous to X.
manifold: The manifold X and Y lie on: a name accepted by get_manifold ("torus", the default, or "hyperbolic") or a manifold object, such as manifold_grassmann(n, k).
px_base: Base point used to map X to the tangent space. If NULL (the default) or not valid for X according to the manifold's cut-locus check (e.g. is_valid_torus), a base point is chosen automatically with choose_base_point.
py_base: Base point used to map Y to the tangent space, analogous to px_base.
R: Number of permutations for the distance covariance test, passed to dcov.test. Defaults to 500.
seed: Random seed used by align_sample_sizes when the sample sizes of X and Y differ, by choose_base_point when base_point_method = "optimize", and by center_outward_transform when center_outward = TRUE. Defaults to 2024.
center_outward: If TRUE, runs the RankCov test of Liu et al. (2026): applies the center-outward rank transform (Hallin et al. 2021, center_outward_transform) to the log-mapped X and Y before testing, so the distance covariance test is computed on multidimensional ranks bounded in the unit ball rather than on the raw tangent-space coordinates. This makes the test valid without moment conditions on the original data. If FALSE (the default), runs the DistCov test: the test runs directly on the tangent-space coordinates from the manifold's log map. On hyperbolic space, FALSE raises a warning, since DistCov then relies on moment conditions that may fail.
base_point_method: Base point method, passed as method to choose_base_point for any base point that must be chosen automatically. If NULL (the default), the manifold's default method is used. Every built-in manifold offers "auto" (the default, closed form) and "optimize" (numerical, data-centered). See choose_base_point.
n_start: Number of random restarts passed to choose_base_point. Only used by iterative methods such as "optimize". Defaults to 10.
maxit: Maximum optim iterations per restart, passed to choose_base_point. Only used by iterative methods such as "optimize". Defaults to 200.
verbose: If TRUE (the default), prints a summary of the alignment, base points, and test result to the console.

Value

A list with five elements:

dcov_test: The dcov.test result object, as returned by dcov.test.
px_base: The base point used to map X: either the supplied px_base, or the one chosen automatically.
py_base: The base point used to map Y, analogous to px_base.
X_mapped: The mapped X samples actually used for the test: rows in the unit ball \(S^d\) from center_outward_transform if center_outward = TRUE (RankCov), otherwise the tangent-space coordinates from the manifold's log map (DistCov).
Y_mapped: The mapped Y samples actually used for the test, analogous to X_mapped.

Details

The function implements the two tests of Liu et al. (2026), selected by center_outward:

DistCov (center_outward = FALSE, the default): the distance covariance test is applied directly to the tangent-space coordinates. It requires finite second moments of the distances (always the case on compact manifolds such as the torus and the Grassmann manifold) and is sensitive to outliers. On hyperbolic space, which is not compact, a warning suggests using RankCov instead.
RankCov (center_outward = TRUE): the distance covariance test is applied to the center-outward ranks (center_outward_transform) of the tangent-space coordinates. It requires no moment condition and is robust to outliers, but requires continuous distributions and can lose power in high dimensions or with small samples.

Both tests have exact finite-sample level by permutation. See the user guide on the package website for advice on choosing between them.

References

Liu, H., Li, M., González-Delgado, J. and Hallin, M. (2026). Independence test on Riemannian manifolds. Manuscript.

Hallin, M., del Barrio, E., Cuesta-Albertos, J. and Matrán, C. (2021). Distribution and quantile functions, ranks and signs in dimension d: a measure transportation approach. The Annals of Statistics, 49(2), 1139–1165.

Examples

# \donttest{
X <- matrix(runif(30), nrow = 10, ncol = 3)
Y <- matrix(runif(20), nrow = 10, ncol = 2)
result <- manifold.dcov.test(X, Y, manifold = "torus", R = 200)
#> Choosing base point for X...
#> Chosen base point for X: (0.10, 0.79, 0.65)
#> Choosing base point for Y...
#> Chosen base point for Y: (0.61, 0.61)
#> Performing distance covariance test...
#> 
#> ========================================
#>  Distance Covariance Independence Test Result
#> ========================================
#> Method: DistCov (tangent-space coordinates)
#> Sample size: 10
#> X Dimension: 3
#> Sample size: 10
#> Y Dimension: 2
#> Distance covariance statistic V_n: 0.23901
#> p: 0.29851
#> ========================================
result$dcov_test$p.value
#> [1] 0.2985075
result$px_base
#> [1] 0.09548647 0.79089584 0.65274746
dim(result$X_mapped)
#> [1] 10  3
# }