Description Usage Arguments Details Value Warning Note Author(s) See Also Examples

Computes the `yulesimonMlink`

transformation, its inverse
and the first two derivatives.

1 2 |

`theta` |
Numeric or character. This is |

`bvalue, inverse, deriv, short, tag` |
Details at |

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.

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.

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.

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.

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

Embedding an R snippet on your website

Add the following code to your website.

For more information on customizing the embed code, read Embedding Snippets.