VGAMextra (version 0.0-6)

yulesimonMlink: 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)

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.

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

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.

Author

V. Miranda and T. W. Yee

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.

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 ##

# \donttest{
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))
 # }