yulesimonMlink {VGAMextra}

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

Description

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

Usage

 yulesimonMlink(theta, bvalue = NULL, inverse = FALSE, 
                deriv = 0, short = TRUE, tag = FALSE)

Arguments

theta

Numeric or character. This is \theta by default, or \eta depending upon other arguments. See Links.

bvalue, inverse, deriv, short, tag

Details at Links

Details

Assume Y \sim {\rm{Yule-Simon}}(\rho) , where \rho is a shape parameter as in yulesimon. Then, the mean of Y is given by

\mu = \frac{\rho}{\rho - 1} = (1 - \rho^{-1})^{-1},

provided \rho > 1 .

This link function may be conceived as a natural link function for the mean of the Yule–Simon distribution which comes up by taking the logarithm on both sides of this equation. More precisely, the yulesimonMlink tranformation for \rho > 1 is given by

{\tt{yulesimonMlink}}(\rho) = - \log (1 - \rho^{-1}).

While this link function can be used to model any parameter lying in (1, \infty), it is particularly useful for event-rate data where the mean, \mu, can be written in terms of some rate of events, say \lambda, and the timeframe observed t. Specifically,

\mu = \lambda t.

Assuming that additional covariates might be available to linearly model \lambda (or \log \lambda), this model can be treated as a VGLM with one parameter where the time t (as \log t) can be easily incorporated in the analysis as an offset.

Under this link function the domain set for \rho is (1, \infty). Hence, values of \rho 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.

Unlike logffMlink or zetaffMlink, the inverse of this link function can be written in close form.

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

Value

For deriv = 0, the yulesimonMlink transformation of theta when inverse = FALSE, and if inverse = TRUE then exp(theta) / (exp(theta) - 1).

For deriv = 1, d eta / d theta as a function of theta if inverse = FALSE, else the reciprocal d theta / d eta.

For deriv = 2 the second order derivatives are correspondingly returned.

Warning

Conforming with yulesimon, the domain set for rho is (0, \infty). However, in order for yulesimonMlink to be a real number, rho must be greater then 1.0. Then, when a VGLM is fitted via yulesimon using this link function, numerical instability will occur if the estimated or the true value of rho lies between 0 and 1, or if the initial values for rho generated by yulesimon fail to meet rho > 1. Alternatively, try posPoiMlink or loglink if this happens.

Note

If the underlying assumption \rho > 1 is not met, then this function returns NaN. This is equivalent to claim that the mean is infinite or negative and, consequently, its logarithm will not be real.

The vertical line theta = 1 is an asymptote for this link function. As a result, it may return Inf for values of \rho too close to 1 from the right.

Author(s)

V. Miranda and T. W. Yee

See Also

yulesimon, Links, posPoiMlink, loglink.

Examples

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

yulesl.inv <- 
    # The inverse  minus actual values
    yulesimonMlink(theta = yulesimonMlink(theta = Shapes),  inverse = TRUE) - Shapes
                      
summary(yulesl.inv)     ## zero


## Example 2. Special values of theta (rho) ##
rhos <- c(-Inf, -2, -1, 0.0, 0.5, 1, 5, 10, 100, Inf, NaN, NA) 
rbind(rho = rhos, 
      yuleslink  = yulesimonMlink(theta = rhos),
      inv.yulesl =yulesimonMlink(theta = rhos, inverse = TRUE))


## Example 3 The yulesimonMlink transformation and the first two derivatives ##

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

plot(y.rhos ~ rhos, col = "black", 
     main = "log(mu), mu = E[Y], Y ~ Yule-Simon(rho).",
     ylim = c(-5, 10), xlim = c(-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(rhos, der.1, col = "blue", lty = 5)
lines(rhos, der.2, col = "chocolate", lty = 4)
legend(2, 7, legend = c("yulesimonMlink", "deriv = 1", "deriv = 2"),
       col = c("black", "blue", "chocolate"), lty = c(1, 5, 4))