Author: Kassel Hingee

This directory contains an R package, `TFORGE`, that implements the hypothesis tests for eigenvalues in Hingee, Scealy and Wood (2026, Nonparametric bootstrap inference for the eigenvalues of geophysical tensors, [doi:10.1080/01621459.2025.2606381](https://doi.org/10.1080/01621459.2025.2606381) ).
A version of this package is available from CRAN at `https://cran.r-project.org/package=TFORGE`.

## Installation
Install this package from github by running:
```
devtools::install_github("https://github.com/kasselhingee/TFORGE")
```
or install from CRAN by running:
```
install.packages("TFORGE")
```

## About
All tests in this package are for hypotheses about the eigenvalues of the (extrinsic) mean of the sampled population(s).
Functions for conducting hypothesis tests start with `test_`.
When the matrices are constrained to a submanifold of the space of symmetric matrices we use the extrinsic mean, which projects the usual linear/Euclidean mean so that it satisfies the same constraints as the data.
Tests can be calibrated using either a chi-squared distribution or bootstrapping; in simulations bootstrapping was more reliable but slower.


The following functions conduct single sample and k-sample tests of the eigenvalues of the (extrinsic) population mean:

+ `test_unconstrained()`
+ `test_fixedtrace()` when matrices have fixed trace
+ `test_ss1()` when the squared eigenvalues of each matrix sums to 1.
+ `test_ss1fixedtrace()` when the squared eigenvalues of each matrix sums to 1 and the trace is zero.

The single sample tests conducted by the above functions test the null hypothesis of a user-provided set of eigenvalues for the extrinsic population mean against the alternative hypothesis that the extrinsic population mean has different eigenvalues.
The k-sample tests conducted by the above functions test the null hypothesis that the extrinsic population means have the same eigenvalues.

Additionally `test_unconstrained_aGOE()` can perform 2-sample tests with calibration by a Gaussian Orthogonal Ensemble (GOE) approximation (Schwartzman et al., 2010, Group comparison of eigenvalues and eigenvectors of diffusion tensors. *Journal of the American Statistical Association*).
 A bootstrapped calibration for this test is also available where the GOE approximation is used to stabilise the scale of the statistic.

There are two functions `conf_fixedtrace()` and `conf_ss1fixedtrace()` for estimating confidence regions.

The above tests all require that the eigenvalues of the population mean are distinct (with degraded performance when eigenvalues are very close to each other).
Eigenvalues are assumed to be in descending order.

Use `test_multiplicity()` to test the eigenvalue-multiplicity of the population mean of a single sample.
A test of the same hypothesis that requires that matrix elements follow a multivariate Gaussian distribution with orthogonally-invariant covariance is also available through `test_multiplicity_OI()` (Schwartzman et al., 2008, Inference for eigenvalues and eigenvectors of Gaussian symmetric matrices, *The Annals of Statistics*).
`test_multiplicity()` can also be applied to matrices with a constrained trace, but use `test_multiplicity_nonnegative()` for matrices constrained to have non-negative eigenvalues.


## Usage
To use the functions starting with `test_`, you must have symmetric matrix data formatted to be suitable for `as_fsm()` or `as_kfsm()` (please see the help for these functions for more detail).
The package includes a vignette demonstrating an application to anisotropy of magnetic susceptibility data.
For example applications of all the hypothesis tests in this package, please see the reproducibility document associated with (Hingee, Scealy and Wood, 2026, Nonparametric bootstrap inference for the eigenvalues of geophysical tensors, [doi:10.1080/01621459.2025.2606381](https://doi.org/10.1080/01621459.2025.2606381) ).
Below is a toy example using symmetric matrices simulated from a multivariate Normal (aka Gaussian) distribution.

```
# simulate data
flattened_matrices <- rsymm_norm(15, diag(c(3, 2, 1)))
# test multiplicity of eigenvalues of population mean
test_multiplicity(flattened_matrices, mult = c(1, 2))
test_multiplicity(flattened_matrices, mult = c(2, 1))
# test eigenvalues of population mean
test_unconstrained(flattened_matrices, evals = c(3, 2, 1))
```

## Contributing
Contributions welcome.
Please feel free to contact the author of this package and/or make pull requests.

The package includes substantial unit testing. 
When the `FAST_CHECK` environmental variable is `"true"`, then fast unit testing is conducted.
Package checks set `FAST_CHECK` based on the `NOT_CRAN` environmental variable (which is set by the `devtools` package).
These fast unit tests can also be interactively by running `Sys.setenv(FAST_CHECK = "true")` before running `devtools::test()` or similar.
More thorough and slower unit tests can be conducted by running `devtools::test()` or `testthat::test_local()` on the package without setting `FAST_CHECK`.
Note that the bespoke `FAST_CHECK` variable is used to enable fast interactive testing because `testthat::skip_on_cran()` currently never skips interactively, regardless of the value of `NOT_CRAN`.



