yulesimonMeanlink {VGAMextra} | R Documentation |
Computes the yulesimonMeanlink
transformation, its inverse
and the first two derivatives.
yulesimonMeanlink(theta, bvalue = NULL, inverse = FALSE, deriv = 0, short = TRUE, tag = FALSE)
theta |
Numeric or character. This is theta by default,
or eta depending upon other arguments.
See |
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 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.
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.
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.
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
,
posPoiMeanlink
,
loge
.
## 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))