Author: Kassel Hingee
This directory contains an R package,TFORGE, thatimplements the hypothesis tests for eigenvalues in Hingee, Scealy andWood (2026, Nonparametric bootstrap inference for the eigenvalues ofgeophysical tensors, accepted by theJournal of American StatisticalAssociation). A version of this package is available from CRAN athttps://cran.r-project.org/package=TFORGE.
Install this package from github by running:
devtools::install_github("https://github.com/kasselhingee/TFORGE")or install from CRAN by running:
install.packages("TFORGE")All tests in this package are for hypotheses about the eigenvalues ofthe (extrinsic) mean of the sampled population(s). Functions forconducting hypothesis tests start withtest_. When thematrices are constrained to a submanifold of the space of symmetricmatrices we use the extrinsic mean, which projects the usuallinear/Euclidean mean so that it satisfies the same constraints as thedata. Tests can be calibrated using either a chi-squared distribution orbootstrapping; in simulations bootstrapping was more reliable butslower.
The following functions conduct single sample and k-sample tests ofthe eigenvalues of the (extrinsic) population mean:
test_unconstrained()test_fixedtrace() when matrices have fixed tracetest_ss1() when the squared eigenvalues of each matrixsums to 1.test_ss1fixedtrace() when the squared eigenvalues ofeach matrix sums to 1 and the trace is zero.The single sample tests conducted by the above functions test thenull hypothesis of a user-provided set of eigenvalues for the extrinsicpopulation mean against the alternative hypothesis that the extrinsicpopulation mean has different eigenvalues. The k-sample tests conductedby the above functions test the null hypothesis that the extrinsicpopulation means have the same eigenvalues.
Additionallytest_unconstrained_aGOE() can perform2-sample tests with calibration by a Gaussian Orthogonal Ensemble (GOE)approximation (Schwartzman et al., 2010, Group comparison of eigenvaluesand eigenvectors of diffusion tensors.Journal of the AmericanStatistical Association). A bootstrapped calibration for this testis also available where the GOE approximation is used to stabilise thescale of the statistic.
There are two functionsconf_fixedtrace() andconf_ss1fixedtrace() for estimating confidence regions.
The above tests all require that the eigenvalues of the populationmean are distinct (with degraded performance when eigenvalues are veryclose to each other). Eigenvalues are assumed to be in descendingorder.
Usetest_multiplicity() to test theeigenvalue-multiplicity of the population mean of a single sample. Atest of the same hypothesis that requires that matrix elements follow amultivariate Gaussian distribution with orthogonally-invariantcovariance is also available throughtest_multiplicity_OI()(Schwartzman et al., 2008, Inference for eigenvalues and eigenvectors ofGaussian symmetric matrices,The Annals of Statistics).test_multiplicity() can also be applied to matrices with aconstrained trace, but usetest_multiplicity_nonnegative()for matrices constrained to have non-negative eigenvalues.
To use the functions starting withtest_, you must havesymmetric matrix data formatted to be suitable foras_fsm()oras_kfsm() (please see the help for these functions formore detail). The package includes a vignette demonstrating anapplication to anisotropy of magnetic susceptibility data. For exampleapplications of all the hypothesis tests in this package, please see thereproducibility document associated with (Hingee, Scealy and Wood, 2026,Nonparametric bootstrap inference for the eigenvalues of geophysicaltensors, accepted by theJournal of American StatisticalAssociation). Below is a toy example using symmetric matricessimulated from a multivariate Normal (aka Gaussian) distribution.
# simulate dataflattened_matrices <- rsymm_norm(15, diag(c(3, 2, 1)))# test multiplicity of eigenvalues of population meantest_multiplicity(flattened_matrices, mult = c(1, 2))test_multiplicity(flattened_matrices, mult = c(2, 1))# test eigenvalues of population meantest_unconstrained(flattened_matrices, evals = c(3, 2, 1))Contributions welcome. Please feel free to contact the author of thispackage and/or make pull requests.
The package includes substantial unit testing. When theFAST_CHECK environmental variable is"true",then fast unit testing is conducted. Package checks setFAST_CHECK based on theNOT_CRAN environmentalvariable (which is set by thedevtools package). These fastunit tests can also be interactively by runningSys.setenv(FAST_CHECK = "true") before runningdevtools::test() or similar. More thorough and slower unittests can be conducted by runningdevtools::test() ortestthat::test_local() on the package without settingFAST_CHECK. Note that the bespokeFAST_CHECKvariable is used to enable fast interactive testing becausetestthat::skip_on_cran() currently never skipsinteractively, regardless of the value ofNOT_CRAN.