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 |
bvalue , inverse , deriv , short , tag |
Details at |
Details
Assume ,
where
is a shape parameter as in
yulesimon
.
Then, the mean of
is given by
provided .
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
is given by
While this link function can be used to model any parameter lying in
, 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
.
Specifically,
Assuming that additional covariates might be available to linearly
model (or
),
this model can be treated as a VGLM with one parameter where
the time
(as
) can be easily incorporated
in the analysis as an offset.
Under this link function the domain set for
is
. Hence, values of
too
close to
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 is
. However, in order for
yulesimonMlink
to be a real number, 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
lies between 0 and 1, or if the initial values for
generated by
yulesimon
fail to meet
. Alternatively, try
posPoiMlink
or
loglink
if this happens.
Note
If the underlying assumption 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
too close to
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))