zetaffMlink {VGAMextra}

Link functions for the mean of 1–parameter discrete distributions: The Zeta Distribution.

Description

Computes the zetaffMlink transformation, including its inverse and the first two derivatives.

Usage

  zetaffMlink(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 can be \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. Default is Newton–Raphson. Optionally, the bisection method is also available.

inverse, deriv, short, tag

Details at Links

Details

This is a link function for the zeta distribution, zetaff, which emerges by applying the logarithm transformation to its mean. Specifically, assume Y follows a zeta distribution with shape parameter s (this is theta in the VGLM/VGAM framework). Then, the mean of Y is

\mu = \frac{\zeta (s)}{\zeta (s + 1)},

provided s > 1, where \zeta is the Riemann's zeta function computed by zeta. The notation adopted here conforms with zetaff in terms of the density of the zeta distribution.

The zetaffMlink transformation is given by

\eta = \tt{zetaffMlink}(s) = \log \frac{\zeta (s)}{\zeta (s + 1)}.

It is particularly useful when modelling event–rate data where the expected number of events, \mu, can be modelled as

\mu = \lambda t.

Specifically, \lambda is a standardized mean per unit–time, and t is the observed timeframe.

The domain set for s, i.e. \theta, is (1, \infty). Hence, either large values of s, or those too close to 1 from the right, or out of range will result in Inf, -Inf, NA or NaN. Use argument bvalue to adequately replace them before computing the link function.

WARNING: While in zetaff the parameter s lies in (1, \infty), zetaffMlink will be real when s > 1. Consequently, for any VGLM fitted via zetaff using this link function, numerical problems will take place if any s value lies between 0.0 and 1.0 at any iteration. Use optional link functions like loglink.

When inverse = TRUE and deriv = 0, s changes into \eta, and therefore the domain set (only in this case) turns into (0, \infty). See below for further details.

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

Value

For deriv = 0, the zetaffMlink transformation of theta, if inverse = FALSE. When inverse = TRUE, theta becomes \eta, and then the inverse of zetaffMlink is required. However, it cannot be written in closed–form. Instead, the inverse image of \eta, say \theta_\eta, is returned. That is, a unique vector \theta_\eta such that

{\tt{zetaffMlink}} (\theta_\eta) = \eta.

This process is equivalent to find the root, \theta_\eta, of the function {\tt{zetaffMlink}} (\theta) - \eta, which is internally carried out via the method entered at alg.roots. Options available are “Newton-Raphson” and “bisection”.

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

The first two derivatives of the Riemman's zeta function are computed by zeta.

Besides, the zetaffMlink function as well as its derivatives are graphically delimited for specific asymptotes. Consequently, the mathematical limit of this link function is returned for special values of theta, e.g. for theta = \infty. See example 2 below.

Warning

Where the inverse image of \eta, \theta_\eta, is required, values entered at theta (becoming \eta) must be non-negative. The reason is that the zetaffMlink transformation is decreasing but strictly positive in (1, \infty) asymptotically approaching to the horizontal axis. In this way, the shifted–down zetaffMlink function

{\tt{zetaff.func}}(\theta | \eta) = {\tt{zetaffMlink}}(\theta) - \eta

uniquely intersects the horizontal axis and hence the inverse image computed by “Newton-Raphson” or “bisection” will be a real number.

Note

Overall, this link function is useful to model any parameter lying in (1, \infty), specially if the theoretical mean can be written as \mu = \lambda t, as stated above. As a result, some problems may arise if there are covariates. Try another link function if any issue, such as logloglink.

Author(s)

V. Miranda and T. W. Yee

See Also

zetaff, newtonRaphson.basic, bisection.basic, zeta, loglink, Links.

Examples

## Example 1  ##
Shapes <- 1:10 + 0.1 
zetaffMlink(theta = Shapes, deriv = 1)  ## d eta/d theta, as function of theta

zetafflk.inv <- zetaffMlink(theta = zetaffMlink(theta = Shapes), inverse = TRUE) - Shapes
 
summary(zetafflk.inv)                      ## Should be zero


## Example 2. Special values of theta, inverse = FALSE ##
Shapes <- c(-Inf, -1, 0.5, 1, 1.5, 10, 100, Inf, NaN, NA) 
print(rbind(Shapes, zetaffMlink  = zetaffMlink(theta = Shapes),
            inv.zfflink = zetaffMlink(theta = Shapes, inverse = TRUE)), digits = 3)


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

Shapes <- seq(1, 20, by = 0.01)[-1]
y.shapes <- zetaffMlink(theta = Shapes, deriv = 0)
der.1 <- zetaffMlink(theta = Shapes, deriv = 1)
der.2 <- zetaffMlink(theta = Shapes, deriv = 2)

plot(y.shapes ~ Shapes, 
     col = "black", main = "log(mu), mu = E[Y], Y ~ Zeta(s).",
     ylim = c(-5, 10), xlim = c(-0.1, 5), lty = 1, type = "l", lwd = 3)
abline(v = 1.0, col = "orange", lty = 2, lwd = 3)
abline(v = 0, h = 0, col = "gray50", lty = "dashed")

lines(Shapes, der.1, col = "blue", lty = 5)
lines(Shapes, der.2, col = "chocolate", lty = 4)
legend(2, 7, legend = c("zetaffMlink", "deriv = 1", "deriv = 2"),
       col = c("black", "blue", "chocolate"), lty = c(1, 5, 4), lwd = c(3, 1, 1))