VGAMextra (version 0.0-1)

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

Description

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

Usage

 yulesimonMeanlink(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

Value

For deriv = 0, the yulesimonMeanlink 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 yulesimonMeanlink 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 posPoiMeanlink or loge if this happens.

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 yulesimonMeanlink tranformation for \(\rho > 1\) is given by $$ {\tt{yulesimonMeanlink}}(\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 logffMeanlink and zetaffMeanlink, 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, posPoiMeanlink, loge.

Examples

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

yulesl.inv <-
        yulesimonMeanlink(theta = yulesimonMeanlink(theta = Shapes),  # the inverse
                               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  = yulesimonMeanlink(theta = rhos),
      inv.yulesl =yulesimonMeanlink(theta = rhos, inverse = TRUE))


## Example 3 The yulesimonMeanlink transformation and the first two derivatives ##
# }
# NOT RUN {
<!-- % -->
# }
# NOT RUN {
rhos <- seq(1, 20, by = 0.01)[-1]
y.rhos <- yulesimonMeanlink(theta = rhos, deriv = 0)
der.1  <- yulesimonMeanlink(theta = rhos, deriv = 1)
der.2  <- yulesimonMeanlink(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("yulesimonMeanlink", "deriv = 1", "deriv = 2"),
       col = c("black", "blue", "chocolate"), lty = c(1, 5, 4))
 
# }