borel.tannerMlink {VGAMextra}

Link functions for the mean of 1–parameter discrete distributions: The Borel–Tanner distribution.

Description

Computes the borel.tannerMlink transformation, its inverse and the first two derivatives.

Usage

    borel.tannerMlink(theta, Qsize = 1, 
                      bvalue = NULL, inverse = FALSE, 
                      deriv = 0, short = TRUE, tag = FALSE)

Arguments

theta

Numeric or character. See below for further details.

Qsize

A positive integer. It is called Q. Same as borel.tanner. Default it 1.

bvalue, inverse, deriv, short, tag

Details at Links

Details

As with zetaffMlink or yulesimonMlink, this link function is part of a set of link functions in VGAM developed under a common methodology: by taking the logarithm of the mean of the corresponding distribution.

In particular, this link function emerges by computing the logarithm of the mean of the Borel–Tanner distribution. It is defined as

\tt{borel.tannerMlink}(a) = - \log (Q^{-1} - aQ^{-1}),

where a, 0 < a < 1, is a scale parameter as in borel.tanner.

The domain set of borel.tannerMlink is the open interval (0, 1), except when inverse = TRUE and deriv = 0. See below for further details about this. Moreover, unlike zetaffMlink or posPoiMlink, the inverse of borel.tannerMlink can be written in closed–form.

Values of a (i.e. theta) out of range will result in NaN of NA.

If theta is a character, arguments inverse and deriv are discarded.

Value

For deriv = 0, the borel.tannerMlink transformation of theta, if inverse = FALSE. When inverse = TRUE, theta becomes \eta and the inverse of borel.tannerMlink, given by

1 - \frac{Q}{ e^{\eta} },

is returned. Here, the domain set changes to (0, \infty).

For deriv = 1, d eta / d theta as a function of theta if inverse = FALSE, else the reciprocal d theta / d eta.

Similarly, when deriv = 2 the second order derivatives in terms of theta are returned.

References

Haight, F. and Brueuer, M. A. (1960) The Borel–Tanner distribution. Biometrika, 47, 143–150.

Note

The vertical line a = 1 is an asymptote for this link function, which sharply grows for values of a too close to 1.0 from the left. For such cases, Inf might result when computing borel.tannerMlink.

This link function is useful to model any parameter in (0, 1). Then, some problems may occur if there are covariates causing out of range values.

Author(s)

V. Miranda and T. W. Yee

See Also

borel.tanner, yulesimonMlink, zetaffMlink, posPoiMlink, Links.

Examples

## Example 1. Special values for theta (or eta, accordingly)  ##
a.par <- c(0, 1:10/10, 20, 1e1, Inf, -Inf, NaN, NA) 

# The borel.tannerMlink transformation and the first two derivatives.
print(rbind(a.par, 
 deriv1 = borel.tannerMlink(theta = a.par, inverse = FALSE, deriv = 1),
 deriv2 = borel.tannerMlink(theta = a.par, inverse = FALSE, deriv = 2)),
 digits = 2)
  
# The inverse of 'borel.tannerMlink()' and the first two derivatives.
# 'theta' turns into 'eta'.
print(rbind(a.par, 
    Invderiv1 = borel.tannerMlink(theta = a.par, inverse = TRUE, deriv = 1),
    Invderiv2 = borel.tannerMlink(theta = a.par, inverse = TRUE, deriv = 2)),
    digits = 2)

  
## Example 2 ##
a.param <- c(0, 1, 5, 10, 1e2, 1e3) 
rbind(a.values = a.param, 
      inv.BT = borel.tannerMlink(theta = a.param, inverse = TRUE))
    
data.inv <- borel.tannerMlink(borel.tannerMlink(a.param, inv = TRUE)) - a.param
summary(data.inv)                      ## Should be zero



## Example 3. Some link functions in VGAM with domain set (0, 1) ##
a.param <- ppoints(100)

par(lwd = 2)
plot(a.param, borel.tannerMlink(a.param), ylim = c(-5, 7), xlim = c(-0.01, 1.01),
     type = "l", col = "gray10", ylab = "transformation",
     las = 1, main = "Some probability link functions")
lines(a.param, logffMlink(a.param), col = "blue")
lines(a.param, logitlink(a.param), col = "limegreen")
lines(a.param, probitlink(a.param), col = "purple")
lines(a.param, clogloglink(a.param), col = "chocolate")
lines(a.param, cauchitlink(a.param), col = "tan")
abline(v = c(0.5, 1), lty = "dashed")
abline(v = 0, h = 0, lty = "dashed")
legend(0.05, 7, c("borel.tanneMlink", "logffMlink", "logitlink", "probitlink",
                  "clogloglink", "cauchitlink"),
       col = c("gray10", "blue", "limegreen", "purple", "chocolate", "tan"),
      lwd = 1)
par(lwd = 1)