VGAMextra (version 0.0-1)

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

Description

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

Usage

     posPoiMeanlink(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 zetaffMeanlink.

inverse, deriv, short, tag

Details at Links

Value

For deriv = 0, the posPoiMeanlink transformation of theta, if inverse = FALSE. When inverse = TRUE, theta becomes \(\eta\) and the inverse of posPoiMeanlink 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{posPoiMeanlink}(\theta_\eta) = \eta.$$ Here, \(\theta_\eta\) is iteratively computed as the unique root of the auxiliary function $$ f(\theta; \eta) = \tt{posPoiMeanlink}(\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{posPoiMeanlink}(\theta) - \eta$$ to be real, \(\eta\) must be positive. As a result, posPoiMeanlink is shited--down and hence intersecting the horizontal axis uniquely.

Details

This is a link function for the mean of the positive Poisson distribution. It is defined as $$ \eta = \tt{posPoiMeanlink}(\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.

posPoiMeanlink 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

# NOT RUN {
## 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 'posPoiMeanlink' transformation and the first two derivatives.
print(rbind(m.lambda, 
  deriv1 = posPoiMeanlink(theta = m.lambda, inverse = FALSE, deriv = 1),
  deriv2 = posPoiMeanlink(theta = m.lambda, inverse = FALSE, deriv = 2)),
  digits = 2)
  
# The inverse of 'posPoiMeanlink' and the first two derivatives.
print(rbind(m.lambda, 
  Invderiv1 = posPoiMeanlink(theta = m.lambda, inverse = TRUE, deriv = 1),
  Invderiv2 = posPoiMeanlink(theta = m.lambda, inverse = TRUE, deriv = 2)),
  digits = 2)
  

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


## Example 3. Plot of 'posPoiMeanlink' and its first two derivatives ##
## inverse = FALSE, deriv = 0, 1, 2. ##
# }
# NOT RUN {
<!-- % -->
# }
# NOT RUN {
m.lambda <- seq(0, 35, by = 0.01)[-1]
y.lambda <- posPoiMeanlink(theta = m.lambda, deriv = 0)
der.1 <- posPoiMeanlink(theta = m.lambda, deriv = 1)
der.2 <- posPoiMeanlink(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("posPoiMeanlink", "deriv = 1", "deriv = 2"),
       col = c("black", "blue", "chocolate"), lty = c(1, 5, 4), lwd = c(3, 3, 3))
 
# }