# rootWishartHD

`rootWishartHD` computes CDFs, log-CDFs, log-survival probabilities, p-values,
and critical values for Roy's largest root in single- and double-Wishart
(Jacobi / multivariate beta) settings. It is derived from Maxime Turgeon's
`rootWishart` codebase and adds scaled Pfaffian evaluation, log-tail wrappers,
adaptive multiprecision, and high-dimensional validation utilities.

## Installation

```r
# from a local source checkout
install.packages(".", repos = NULL, type = "source")
```

## Basic use

```r
library(rootWishartHD)

theta <- c(0.5, 0.8, 0.9)       # theta scale, 0 <= theta <= 1
F <- doubleWishart(theta, s = 5, m = 10, n = 10, verbose = FALSE)

log_sf <- doubleWishart_log(theta, s = 5, m = 10, n = 10,
                            tail = "upper", type = "arbitrary",
                            verbose = FALSE)

pval <- doubleWishart_pvalue(theta, s = 5, m = 10, n = 10,
                             input = "theta", verbose = FALSE)
```

The double-Wishart API uses the Jacobi scale
`theta = lambda / (1 + lambda)`. If your statistic is a beta type II or
generalized-root value `lambda`, convert it before calling CDF functions, or use
`doubleWishart_pvalue(..., input = "lambda")`.

## Multiprecision backend

The CRAN-safe default is

```make
DW_USE_MPFR=0
```

which uses Boost's header-only `cpp_dec_float` backend from the `BH` package.
This needs no system MPFR/GMP libraries and is the recommended portable setting
for CRAN, Windows, macOS, and clean Linux machines.

To force the multiprecision path at runtime, use either

```r
options(rootWishartHD.force_multiprecision = TRUE)
```

or pass `force_multiprecision = TRUE` to the CDF/log-tail wrappers.

For local source builds, users who specifically want MPFR/GMP can opt in with

```sh
DW_USE_MPFR=1 R CMD INSTALL rootWishartHD_0.95.1.tar.gz
```

or from a source directory:

```sh
DW_USE_MPFR=1 R CMD INSTALL .
```


Runtime adaptive precision (`adaptive = TRUE`) requires an MPFR/GMP build because
it changes the decimal precision during evaluation. With the default
`DW_USE_MPFR=0` build, `adaptive = TRUE` is downgraded to fixed
`cpp_dec_float` precision with a warning. To increase the fixed precision, build with for example
`DW_MP_DIGITS=300 R CMD INSTALL .`.

You need MPFR and GMP development libraries available to the compiler. Check the
compiled backend with

```r
rootWishartHD_mpfr_enabled()
```

If MPFR is explicitly requested through the deprecated `force_mpfr` interface or
old `options(rootWishart.force_mpfr = TRUE)`, but the package was compiled with
`DW_USE_MPFR=0`, `rootWishartHD` warns once and falls back to Boost
`cpp_dec_float`.

## Validation scripts

Fast tests are under `inst/tinytest/` and are run by `R CMD check`. Longer
numerical sweeps are installed under `inst/validation/` and are not run
automatically:

```r
source(system.file("validation", "test_doubleWishartHD_sweep.R",
                   package = "rootWishartHD"))
```

Those scripts may use arbitrary precision, local caches, and multiple workers;
they are intended for release validation rather than CRAN check-time execution.
