# pospoissonMeanlink: Link functions for the mean of 1-parameter discrete... In VGAMextra: Additions and Extensions of the 'VGAM' Package

## 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"), 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

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.

`pospoisson`, `newtonRaphson.basic`, `bisection.basic`, `Links`, `identitylink`.
 ``` 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)) ```