yulesimonMlink {VGAMextra}R Documentation

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 YYuleSimon(ρ)Y \sim {\rm{Yule-Simon}}(\rho) , where ρ\rho is a shape parameter as in yulesimon. Then, the mean of YY is given by

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

provided ρ>1 \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 ρ>1\rho > 1 is given by

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

While this link function can be used to model any parameter lying in (1,)(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 tt. Specifically,

μ=λt.\mu = \lambda t.

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

Under this link function the domain set for ρ\rho is (1,)(1, \infty). Hence, values of ρ\rho too close to 11 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 rhorho is (0,)(0, \infty). However, in order for yulesimonMlink to be a real number, rhorho 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 rhorho lies between 0 and 1, or if the initial values for rhorho generated by yulesimon fail to meet rho>1rho > 1. Alternatively, try posPoiMlink or loglink if this happens.

Note

If the underlying assumption ρ>1\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 11 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))
 

[Package VGAMextra version 0.0-6 Index]