posPoiMlink {VGAMextra}

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)

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

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.

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.

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.

Note

This link function is useful to model any parameter in (0, \infty). Some numerical issues may arise if there are covariates causing negative values the parameter. Try identitylink alternatively.

Author(s)

V. Miranda and T. W. Yee.

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. ##

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))