yulesimonMeanlink {VGAMextra}R Documentation

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

Details

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

μ = 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

yulesimonMeanlink(rho) = - log (1 - rho^(-1)).

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

μ = λ t.

Assuming that additional covariates might be available to linearly model λ (or log(λ)), 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, ∞). 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.

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, ∞). 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.

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, posPoiMeanlink, loge.

Examples


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


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

[Package VGAMextra version 0.0-1 Index]