VGAMextra (version 0.0-6)

posPoiMlink: Link functions for the mean of 1--parameter discrete distributions: The Positive Poisson Distribution.

Description

Computes the posPoiMlink transformation, its inverse and the first two derivatives.

Usage

     posPoiMlink(theta, bvalue = NULL, 
                 alg.roots = c("Newton-Raphson", "bisection")[1],
                 inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)

Value

For deriv = 0, the posPoiMlink transformation of

theta, if inverse = FALSE. When inverse = TRUE,

theta becomes \(\eta\) and the inverse of

posPoiMlink is needed but cannot be written in closed--form. Instead this link function returns the approximated inverse image of \(\eta\), say \(\theta_\eta\), such that

$$ \tt{posPoiMlink}(\theta_\eta) = \eta.$$

Here, \(\theta_\eta\) is iteratively computed as the unique root of the auxiliary function

$$ f(\theta; \eta) = \tt{posPoiMlink}(\theta) - \eta,$$

as a function of \(\theta\). This work is performed via Newton--Raphson or bisection, as per argument alg.roots.

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 are returned in terms of theta.

Arguments

theta

Numeric or character. This is \(\theta\) by default, although it becomes \(\eta\) sometimes, depending on the other parameters. See below for further details.

bvalue

Details at Links.

alg.roots

Character. The iterative method to find the inverse of this link function. Same as zetaffMlink.

inverse, deriv, short, tag

Details at Links

Warning

This link function is monotonic increasing in \((0, \infty)\) so that the horizontal axis is an asymptote. Then, in order to assure the root of the auxiliary $$ f(\theta; \eta) = \tt{posPoiMlink}(\theta) - \eta$$ to be real, \(\eta\) must be positive. As a result, posPoiMlink is shited--down and hence intersecting the horizontal axis uniquely.

Author

V. Miranda and T. W. Yee.

Details

This is a link function for the mean of the positive Poisson distribution. It is defined as $$ \eta = \tt{posPoiMlink}(\lambda) = -\log (\lambda^{-1} - \lambda^{-1} e^{-\lambda}),$$ where \(\lambda > 0\) stands for the single parameter of pospoisson, i.e. theta in the VGLM/VGAM context.

Notice, the mean of the positive Poisson is given by $$ \frac{\lambda}{1 - e^{-\lambda}}. $$ This link function comes up by taking the logarithm on both sides of this equation.

The domain set for \(\lambda\) is \((0, \infty)\). Hence, non--positive values of \(\lambda\) will result in NaN or NA. Use argument bvalue to properly replace them before computing the link function.

posPoiMlink tends to infinity as \(\lambda\) increases. Specially, its inverse grows at a higher rate. Therefore, large values of \(\lambda\) will result in Inf accordingly. See example 2 below.

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

See Also

pospoisson, newtonRaphson.basic, bisection.basic, Links, identitylink.

Examples

## Example 1. Special values for theta (or eta, accordingly)  ##
m.lambda <- c(0, 0.5, 1, 10, 20, 25, 1e2, 1e3, Inf, -Inf, NaN, NA) 

# The 'posPoiMlink' transformation and the first two derivatives.
print(rbind(m.lambda, 
  deriv1 = posPoiMlink(theta = m.lambda, inverse = FALSE, deriv = 1),
  deriv2 = posPoiMlink(theta = m.lambda, inverse = FALSE, deriv = 2)),
  digits = 2)
  
# The inverse of 'posPoiMlink' and the first two derivatives.
print(rbind(m.lambda, 
  Invderiv1 = posPoiMlink(theta = m.lambda, inverse = TRUE, deriv = 1),
  Invderiv2 = posPoiMlink(theta = m.lambda, inverse = TRUE, deriv = 2)),
  digits = 2)
  

## Example 2. The inverse of 'posPoiMlink' ##
m.lambda <- c(0, 1, 5, 10, 1e2, 1e3) 
posPoiMlink(theta = posPoiMlink(m.lambda, inverse = TRUE))
pospoi.inv <- posPoiMlink(posPoiMlink(m.lambda, inverse = TRUE)) - m.lambda
                           
summary(pospoi.inv)                      ## Should be zero.


## Example 3. Plot of 'posPoiMlink' and its first two derivatives ##
## inverse = FALSE, deriv = 0, 1, 2. ##

# \donttest{
m.lambda <- seq(0, 35, by = 0.01)[-1]
y.lambda <- posPoiMlink(theta = m.lambda, deriv = 0)
der.1 <- posPoiMlink(theta = m.lambda, deriv = 1)
der.2 <- posPoiMlink(theta = m.lambda, deriv = 2)

plot(y.lambda ~ m.lambda, col = "black", 
     main = "log(mu), mu = E[Y], Y ~ pospoisson(lambda).",
     ylim = c(-1, 10), xlim = c(-1, 26),
     lty = 1, type = "l", lwd = 3)
abline(v = 0, h = 0, col = "gray50", lty = "dashed")

lines(m.lambda, der.1, col = "blue", lty = 5, lwd = 3)
lines(m.lambda, der.2, col = "chocolate", lty = 4, lwd = 3)
legend(5, 9, legend = c("posPoiMlink", "deriv = 1", "deriv = 2"),
       col = c("black", "blue", "chocolate"), lty = c(1, 5, 4), lwd = c(3, 3, 3))
 # }