# yulesimonMeanlink: Link functions for the mean of 1-parameter discrete... In VGAMextra: Additions and Extensions of the 'VGAM' Package

## Description

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

## Usage

 ```1 2``` ``` 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 ~ 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 `yulesimonMlink` tranformation for rho > 1 is given by

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

`yulesimon`, `Links`, `posPoiMlink`, `loglink`.
 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37``` ```## 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)) ```