VGAMextra (version 0.0-1)

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

Description

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

Usage

    borel.tannerMeanlink(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

Value

For deriv = 0, the borel.tannerMeanlink transformation of theta, if inverse = FALSE. When inverse = TRUE, theta becomes \(\eta\) and the inverse of borel.tannerMeanlink, 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.

Details

As with zetaffMeanlink or yulesimonMeanlink, 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.tannerMeanlink}(a) = - \log (Q^{-1} - aQ^{-1}),$$ where \(a\), \(0 < a < 1\), is a scale parameter as in borel.tanner.

The domain set of borel.tannerMeanlink is the open interval \((0, 1)\), except when inverse = TRUE and deriv = 0. See below for further details about this. Moreover, unlike zetaffMranlink or posPoiMeanlink, the inverse of borel.tannerMeanlink 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.

References

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

See Also

borel.tanner, yulesimonMeanlink, zetaffMeanlink, posPoiMeanlink, Links.

Examples

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

# The borel.tannerMeanlink transformation and the first two derivatives.
print(rbind(a.par, 
 deriv1 = borel.tannerMeanlink(theta = a.par, inverse = FALSE, deriv = 1),
 deriv2 = borel.tannerMeanlink(theta = a.par, inverse = FALSE, deriv = 2)),
 digits = 2)
  
# The inverse of 'borel.tannerMeanlink()' and the first two derivatives.
# 'theta' turns into 'eta'.
print(rbind(a.par, 
    Invderiv1 = borel.tannerMeanlink(theta = a.par, inverse = TRUE, deriv = 1),
    Invderiv2 = borel.tannerMeanlink(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.tannerMeanlink(theta = a.param, inverse = TRUE))
    
data.inv <- borel.tannerMeanlink(borel.tannerMeanlink(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)
# }
# NOT RUN {
<!-- % -->
# }
# NOT RUN {
par(lwd = 2)
plot(a.param, borel.tannerMeanlink(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(s.shapes, logffMeanlink(a.param), col = "blue")
lines(s.shapes, logit(a.param), col = "limegreen")
lines(s.shapes, probit(a.param), col = "purple")
lines(s.shapes, cloglog(a.param), col = "chocolate")
lines(s.shapes, cauchit(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.tanneMeanlink", "logffMeanlink", "logit", "probit",
                  "cloglog", "cauchit"),
       col = c("gray10", "blue", "limegreen", "purple", "chocolate", "tan"),
      lwd = 1)
par(lwd = 1) 
# }
# NOT RUN {
<!-- % -->
# }