pospoissonMeanlink: Link functions for the mean of 1-parameter discrete...

Description Usage Arguments Details Value Warning Note Author(s) See Also Examples

Description

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

Usage

1
2
3
     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

η = posPoiMlink(λ) = - log (λ^(-1)- λ^(-1) * exp(-λ)),

where λ > 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

λ / (1 - exp(-λ)).

This link function comes up by taking the logarithm on both sides of this equation.

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

posPoiMlink tends to infinity as λ increases. Specially, its inverse grows at a higher rate. Therefore, large values of λ 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 η and the inverse of posPoiMlink is needed but cannot be written in closed–form. Instead this link function returns the approximated inverse image of η, say θ[η], such that

posPoiMlink(θ[η]) =η.

Here, θ[η] is iteratively computed as the unique root of the auxiliary function

f(θ; η) = posPoiMlink(θ) - η,

as a function of θ. 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, ∞) so that the horizontal axis is an asymptote. Then, in order to assure the root of the auxiliary

f(θ; η) = posPoiMlink(θ) - η

to be real, η 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, ∞). 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
## 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))
 

VGAMextra documentation built on May 24, 2021, 9:07 a.m.