OwenT {Phi2rho}

Owen's T Function

Description

Computes Owen's T function using the modified Euler's arctangent series, tetrachoric series or Vasicek's series.

Usage

OwenT(h, a, opt = TRUE, fun = c("mOwenT", "tOwenT", "vOwenT"))

Arguments

h

Numeric scalar or vector.

a

Numeric scalar or vector.

opt

If TRUE, an optimized calculation is performed.

fun

The name of the internal function being used.

Details

If h and a are both vectors, they must be of the same length. If one of h and a is a vector and the other is a scalar, the latter is replicated to the length of the former. The calculation is performed component-wise.

The parameter fun specifies which series is used:

“mOwenT”:

modified Euler's arctangent series (default).

“tOwenT”:

tetrachoric series.

“vOwenT”:

Vasicek's series.

The opt parameter enables checking the results in the submitted article and may be dropped later.

If fun = "mOwenT" and opt = TRUE, the external arctangent function is used, otherwise all necessary values are calculated on the fly, but usually more iterations are needed.

If fun = "tOwenT" or fun = "vOwenT", and opt = TRUE, then the parameters transformation is performed when it makes sense, which significantly reduces the number of iterations.

Value

The value of computed function is returned, scalar or vector. The attribute ‘nIter’ of returned value means the number of iterations.

Note

Function is ready to work with the Rmpfr package, which enables using arbitrary precision numbers instead of double precision ones. Assuming Rmpfr is loaded, it is sufficient to be called with parameters ‘h’ and ‘a’, which have class ‘mpfr’ and the same precision.

Author(s)

Janez Komelj

References

Komelj, J. (2023): The Bivariate Normal Integral via Owen's T Function as a Modified Euler's Arctangent Series, American Journal of Computational Mathematics, 13, 4, 476–504, doi:10.4236/ajcm.2023.134026 (or reprint https://arxiv.org/pdf/2312.00011.pdf with better typography).

Owen, D. B. (1956): Tables for Computing Bivariate Normal Probabilities, The Annals of Mathematical Statistics, 27, 4, 1075–1090, doi:10.1214/aoms/1177728074.

Owen, D. B. (1980): A table of normal integrals, Communications in Statistics – Simulation and Computation, 9, 4, 389–419, doi:10.1080/03610918008812164.

See Also

Phi2xy

Examples

OwenT(2, 0.5)
OwenT(2, 0.5, fun = "mOwenT") # modified arctangent series (default)
OwenT(2, 0.5, fun = "tOwenT") # tetrachoric series
OwenT(2, 0.5, fun = "vOwenT") # Vasicek's series

rho <- 0.6
a <- rho/sqrt(1 - rho^2)
OwenT(0.3, a)
OwenT(0.3, a, fun = "tOwenT") 
OwenT(c(-1, 0.5, 4), a, fun = "vOwenT")

OwenT(2, c(-1, -0.5, 0, 0.5, 1), fun = "vOwenT")

function (h, a, opt = TRUE, fun = c("mOwenT", "tOwenT", "vOwenT")) 
{
    chkArgs1(h = h, a = a, opt = opt)
    if (length(h) < length(a)) 
        h <- rep(h, length(a))
    if (length(a) < length(h)) 
        a <- rep(a, length(h))
    z <- h
    n <- rep(0, length(z))
    z[a == 0] <- 0
    z[is.na(a)] <- NA
    i <- a != 0 & !is.na(a)
    if (any(i)) {
        h <- h[i]
        a <- a[i]
        ph <- pnorm(h)
        fun <- match.arg(fun)
        if (fun == "mOwenT") 
            j <- abs(a) > 1
        if (fun == "tOwenT") 
            j <- opt & abs(a) > 1
        if (fun == "vOwenT") 
            j <- opt & abs(a) < 1
        pah <- h
        if (any(j)) 
            pah[j] <- pnorm(a[j] * h[j])
        pah[is.nan(pah)] <- 0
        w <- eval(call(fun, h, a, ph, pah, opt))
        z[i] <- w
        n[i] <- attr(w, "nIter")
    }
    attr(z, "nIter") <- n
    return(z)
  }