# GFT (R package)

Forward and inverse generalized Fisher transformation (GFT) of
correlation matrices in base R.

The GFT maps a non-singular n x n correlation matrix C to the
unrestricted vector gamma = vecl(log C) in R^d, d = n(n-1)/2, and is a
bijection onto R^d (Archakov and Hansen, 2021, Econometrica). The
inverse is computed by GFT-FP+N (Archakov and Hansen, 2026): a
fixed-point phase in the log domain followed by a matrix-free inexact
Newton phase with preconditioned conjugate gradients.

```r
library(GFT)
C <- 0.9^abs(outer(1:5, 1:5, "-"))
z <- gft(C)          # forward: correlation matrix -> R^10
r <- inv_gft(z)      # inverse: R^10 -> correlation matrix
max(abs(r$C - C))    # ~1e-15
```

Solvers: `inv_gft` (GFT-FP+N, recommended), `inv_gft_fp` (fixed point),
`inv_gft_broyden` (Chen, Fei and Yu, 2025), `inv_gft_newton` (full
Newton). All report eigendecomposition counts and convergence
diagnostics.

## Installation

```r
# from CRAN (once accepted)
install.packages("GFT")

# development version
remotes::install_github("reinhardhansen/GFT", subdir = "r")
```

## Correspondence with the Julia package

`R/GFT.R` is a line-faithful port of the Julia reference implementation
(`julia/src/GFT.jl`, same repository). The test suite includes golden
values generated by an independent NumPy implementation and shared with
the Julia tests, so a passing run is a cross-language verification.
`dev/` contains a development harness (webR) and a script comparing
solver iteration counts against the serialized draws used in the paper's
supplement; it is excluded from the built package.

## References

- Archakov, I. and Hansen, P. R. (2021). A new parametrization of
  correlation matrices. *Econometrica*, 89(4), 1699-1715.
  doi:10.3982/ECTA16910
- Archakov, I. and Hansen, P. R. (2026). A variational approach to the
  generalized Fisher transformation of correlation matrices. Working
  paper.
- Chen, H., Fei, Y. and Yu, J. (2025). Multivariate stochastic
  volatility models based on generalized Fisher transformation.
  *Journal of Econometrics*, 251, 106041.

## License

MIT. See `LICENSE`.
